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