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
  20 #ifndef INCLUDED_UNOTOOLS_CONFIGPATHS_HXX
  21 #define INCLUDED_UNOTOOLS_CONFIGPATHS_HXX
  22
  23 #include <unotools/unotoolsdllapi.h>
  24 #include <rtl/ustring.hxx>
  25
  26 namespace utl
  27 {
  28
  29     /** extract the local nodename and the parent nodepath
  30         from a configuration path.
  31
  32         @param _sInPath
  33             A configuration path that is not an empty or root path.<BR/>
  34             If this is not a valid configuration path, it is interpreted as
  35             local name of a node.
  36
  37         @param _rsOutPath
  38             On exit: The configuration path obtained by dropping
  39                      the last level off <var>_sInPath</var>.<BR/>
  40                      If <var>_sInPath</var> could not be parsed as a valid
  41                      configuration path, this is set to an empty string.
  42
  43         @param _rsLocalName
  44             On exit: The plain (non-escaped) name of the node identified by
  45                      <var>_sInPath</var>. <BR/>
  46                      If <var>_sInPath</var> could not be parsed as a valid
  47                      configuration path, this is set to <var>_sInPath</var>.
  48
  49         @returns
  50             <TRUE/>,  if a parent path could be set
  51             <FALSE/>, if the path was a one-level path or an invalid path
  52
  53     */
  54     UNOTOOLS_DLLPUBLIC bool splitLastFromConfigurationPath(OUString const& _sInPath,
  55                                             OUString& _rsOutPath,
  56                                             OUString& _rsLocalName);
  57
  58     /** extract the first nodename from a configuration path.
  59
  60         @param _sInPath
  61             A relative configuration path that is not empty.<BR/>
  62             If this is not a valid configuration path, it is interpreted as
  63             a single name of a node.
  64
  65         @param _sOutPath
  66             If non-null, contains the remainder of the path upon return.
  67
  68         @returns
  69             The plain (non-escaped) name of the node that is the first step
  70             when traversing <var>_sInPath</var>.<BR/>
  71             If <var>_sInPath</var> could not be parsed as a valid
  72             configuration path, it is returned unaltered.
  73
  74     */
  75     UNOTOOLS_DLLPUBLIC OUString extractFirstFromConfigurationPath(
  76         OUString const& _sInPath, OUString* _sOutPath = nullptr);
  77
  78     /** check whether a path is to a nested node with respect to a parent path.
  79
  80         @param _sNestedPath
  81             A configuration path that maybe points to a descendant of the node
  82             identified by <var>_sPrefixPath</var>, with both paths starting
  83             from the same node (or both being absolute).
  84
  85         @param _sPrefixPath
  86             A configuration path.<BR/>
  87             If this path is absolute, <var>_sNestedPath</var> should be absolute;
  88             If this path is relative, <var>_sNestedPath</var> should be relative;
  89             If this path is empty,    <var>_sNestedPath</var> may start with a '/',
  90             which is disregarded.
  91
  92         @returns
  93             <TRUE/>, if <var>_sPrefixPath</var> is  a prefix of <var>_sNestedPath</var>;
  94             <FALSE/> otherwise.<BR/>
  95             If both paths are equal <TRUE/> is returned.
  96
  97     */
  98     bool isPrefixOfConfigurationPath(OUString const& _sNestedPath,
  99                                          OUString const& _sPrefixPath);
 100
 101     /** get the relative path to a nested node with respect to a parent path.
 102
 103         @param _sNestedPath
 104             A configuration path that points to a descendant of the node
 105             identified by <var>_sPrefixPath</var>, with both paths starting
 106             from the same node (or both being absolute).
 107
 108         @param _sPrefixPath
 109             A configuration path.<BR/>
 110             If this path is absolute, <var>_sNestedPath</var> must be absolute;
 111             If this path is relative, <var>_sNestedPath</var> must be relative;
 112             If this path is empty, <var>_sNestedPath</var> may start with a '/',
 113             which is stripped.
 114
 115         @returns
 116             The remaining relative path from the target of <var>_sPrefixPath</var>
 117             to the target of <var>_sNestedPath</var>.<BR/>
 118             If <var>_sPrefixPath</var> is not a prefix of <var>_sNestedPath</var>,
 119             <var>_sNestedPath</var> is returned unaltered.
 120
 121     */
 122     UNOTOOLS_DLLPUBLIC OUString dropPrefixFromConfigurationPath(OUString const& _sNestedPath,
 123                                                     OUString const& _sPrefixPath);
 124
 125     /** Create a one-level relative configuration path from a set element name
 126         without a known set element type.
 127
 128         @param _sElementName
 129             An arbitrary string that is to be interpreted as
 130             name of a configuration set element.
 131
 132         @returns
 133             A one-level relative path to the element, of the form
 134             "*['<Name>']", where <Name> is properly escaped.
 135
 136     */
 137     UNOTOOLS_DLLPUBLIC OUString wrapConfigurationElementName(OUString const& _sElementName);
 138
 139     /** Create a one-level relative configuration path from a set element name
 140         and a known set element type.
 141
 142         @param _sElementName
 143             An arbitrary string that is to be interpreted as
 144             name of a configuration set element.
 145
 146         @param _sTypeName
 147             An string identifying the type of the element. Usually this is be
 148             the name of the element-template of the set.<BR/>
 149
 150         @returns
 151             A one-level relative path to the element, of the form
 152             "<Type>['<Name>']", where <Name> is properly escaped.
 153
 154     */
 155     OUString wrapConfigurationElementName(OUString const& _sElementName,
 156                                                  OUString const& _sTypeName);
 157
 158 }   // namespace utl
 159
 160 #endif // INCLUDED_UNOTOOLS_CONFIGPATHS_HXX
 161
 162 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */