include/unotools/configpaths.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #include <unotools/unotoolsdllapi.h>
  20
  21 #ifndef INCLUDED_UNOTOOLS_CONFIGPATHS_HXX
  22 #define INCLUDED_UNOTOOLS_CONFIGPATHS_HXX
  23 #include <sal/types.h>
  24 #include <rtl/ustring.hxx>
  25
  26 //----------------------------------------------------------------------------
  27 namespace utl
  28 {
  29 //----------------------------------------------------------------------------
  30     /** extract the local nodename and the parent nodepath
  31         from a configuration path.
  32
  33         @param _sInPath
  34             A configuration path that is not an empty or root path.<BR/>
  35             If this is not a valid configuration path, it is interpreted as
  36             local name of a node.
  37
  38         @param _rsOutPath
  39             On exit: The configuration path obtained by dropping
  40                      the last level off <var>_sInPath</var>.<BR/>
  41                      If <var>_sInPath</var> could not be parsed as a valid
  42                      configuration path, this is set to an empty string.
  43
  44         @param _rsLocalName
  45             On exit: The plain (non-escaped) name of the node identified by
  46                      <var>_sInPath</var>. <BR/>
  47                      If <var>_sInPath</var> could not be parsed as a valid
  48                      configuration path, this is set to <var>_sInPath</var>.
  49
  50         @returns
  51             <TRUE/>,  if a parent path could be set
  52             <FALSE/>, if the path was a one-level path or an invalid path
  53
  54     */
  55     UNOTOOLS_DLLPUBLIC sal_Bool splitLastFromConfigurationPath(OUString const& _sInPath,
  56                                             OUString& _rsOutPath,
  57                                             OUString& _rsLocalName);
  58
  59 //----------------------------------------------------------------------------
  60     /** extract the first nodename from a configuration path.
  61
  62         @param _sInPath
  63             A relative configuration path that is not empty.<BR/>
  64             If this is not a valid configuration path, it is interpreted as
  65             a single name of a node.
  66
  67         @param _sOutPath
  68             If non-null, contains the remainder of the path upon return.
  69
  70         @returns
  71             The plain (non-escaped) name of the node that is the first step
  72             when traversing <var>_sInPath</var>.<BR/>
  73             If <var>_sInPath</var> could not be parsed as a valid
  74             configuration path, it is returned unaltered.
  75
  76     */
  77     UNOTOOLS_DLLPUBLIC OUString extractFirstFromConfigurationPath(
  78         OUString const& _sInPath, OUString* _sOutPath = 0);
  79
  80 //----------------------------------------------------------------------------
  81     /** check whether a path is to a nested node with respect to a parent path.
  82
  83         @param _sNestedPath
  84             A configuration path that maybe points to a descendant of the node
  85             identified by <var>_sPrefixPath</var>, with both paths starting
  86             from the same node (or both being absolute).
  87
  88         @param _sPrefixPath
  89             A configuration path.<BR/>
  90             If this path is absolute, <var>_sNestedPath</var> should be absolute;
  91             If this path is relative, <var>_sNestedPath</var> should be relative;
  92             If this path is empty,    <var>_sNestedPath</var> may start with a '/',
  93             which is disregarded.
  94
  95         @returns
  96             <TRUE/>, if <var>_sPrefixPath</var> is  a prefix of <var>_sNestedPath</var>;
  97             <FALSE/> otherwise.<BR/>
  98             If both paths are equal <TRUE/> is returned.
  99
 100     */
 101     sal_Bool isPrefixOfConfigurationPath(OUString const& _sNestedPath,
 102                                          OUString const& _sPrefixPath);
 103
 104 //----------------------------------------------------------------------------
 105     /** get the relative path to a nested node with respect to a parent path.
 106
 107         @param _sNestedPath
 108             A configuration path that points to a descendant of the node
 109             identified by <var>_sPrefixPath</var>, with both paths starting
 110             from the same node (or both being absolute).
 111
 112         @param _sPrefixPath
 113             A configuration path.<BR/>
 114             If this path is absolute, <var>_sNestedPath</var> must be absolute;
 115             If this path is relative, <var>_sNestedPath</var> must be relative;
 116             If this path is empty, <var>_sNestedPath</var> may start with a '/',
 117             which is stripped.
 118
 119         @returns
 120             The remaining relative path from the target of <var>_sPrefixPath</var>
 121             to the target of <var>_sNestedPath</var>.<BR/>
 122             If <var>_sPrefixPath</var> is not a prefix of <var>_sNestedPath</var>,
 123             <var>_sNestedPath</var> is returned unaltered.
 124
 125     */
 126     UNOTOOLS_DLLPUBLIC OUString dropPrefixFromConfigurationPath(OUString const& _sNestedPath,
 127                                                     OUString const& _sPrefixPath);
 128
 129 //----------------------------------------------------------------------------
 130     /** Create a one-level relative configuration path from a set element name
 131         without a known set element type.
 132
 133         @param _sElementName
 134             An arbitrary string that is to be interpreted as
 135             name of a configuration set element.
 136
 137         @returns
 138             A one-level relative path to the element, of the form
 139             "*['<Name>']", where <Name> is properly escaped.
 140
 141     */
 142     UNOTOOLS_DLLPUBLIC OUString wrapConfigurationElementName(OUString const& _sElementName);
 143
 144 //----------------------------------------------------------------------------
 145     /** Create a one-level relative configuration path from a set element name
 146         and a known set element type.
 147
 148         @param _sElementName
 149             An arbitrary string that is to be interpreted as
 150             name of a configuration set element.
 151
 152         @param _sTypeName
 153             An string identifying the type of the element. Usually this is be
 154             the name of the element-template of the set.<BR/>
 155
 156         @returns
 157             A one-level relative path to the element, of the form
 158             "<Type>['<Name>']", where <Name> is properly escaped.
 159
 160     */
 161     OUString wrapConfigurationElementName(OUString const& _sElementName,
 162                                                  OUString const& _sTypeName);
 163
 164 //----------------------------------------------------------------------------
 165 }   // namespace utl
 166 //----------------------------------------------------------------------------
 167
 168 #endif // INCLUDED_UNOTOOLS_CONFIGPATHS_HXX
 169
 170 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */