offapi/com/sun/star/util/XStringSubstitution.idl

   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 __com_sun_star_util_XStringSubstitution_idl__
  21 #define __com_sun_star_util_XStringSubstitution_idl__
  22
  23 #include <com/sun/star/uno/XInterface.idl>
  24 #include <com/sun/star/container/NoSuchElementException.idl>
  25
  26
  27  module com {  module sun {  module star {  module  util {
  28
  29 /** A common interface for substituting string variables with
  30     other strings.
  31
  32     <p>
  33     The substitution algorithm and the syntax for a string variable are
  34     not part of this interface definition.  Please look at the documentation
  35     of the implementation that must specify these parameters.
  36     </p>
  37
  38     @since OOo 1.1.2
  39 */
  40 published interface XStringSubstitution : com::sun::star::uno::XInterface
  41 {
  42     /** Exchanges variables inside a given text with a substitution text
  43         defined for the variables.
  44
  45         <p>
  46         The method iterates through it's internal variables list to match the
  47         variables in the given string. A match replaces the variable with the
  48         string defined for this variable. If no variable can be found in the string
  49         it will be returned unchanged. The behavior if a variable is found in
  50         the string but it is unknown for the implementation depends on the parameter
  51         bSubstRequired.
  52         </p>
  53
  54         @param aText
  55             A string containing variables that should be substituted.
  56
  57         @param bSubstRequired
  58             Specifies if a successful substitution is required. The
  59             function throws a com::sun::star::container::NoSuchElementException
  60             if it finds a variable that is unknown. In this case it is possible
  61             that the returned string would not be what the caller expected!
  62
  63         @return
  64             Returns a string based on <var>aText</var> where all variables were
  65             exchanged with their value defined at calling time.
  66     */
  67     string substituteVariables( [in] string aText, [in] boolean bSubstRequired )
  68         raises( com::sun::star::container::NoSuchElementException );
  69
  70     /** Tries to replace parts of aText with variables that represents
  71         these sub strings.
  72
  73         <p>
  74         The method iterates through it's internal variable list and tries to match
  75         parts of the given string Tries to replace parts of <var>aText</var> with
  76         variables that represents these sub strings.If more than one variable
  77         matches the one with the longest matching sub string will be chosen.
  78         </p>
  79
  80         @param aText
  81             A string where known substrings should be replaced by variables.
  82
  83         @return
  84             Returns the resubstituted string with variables for all parts
  85             that could be replaced. The unchanged argument will be returned
  86             if nothing can be resubstituted.
  87     */
  88
  89     string reSubstituteVariables( [in] string aText );
  90
  91     /** Returns the current value of a variable.
  92
  93         <p>
  94         The method iterates through it's internal variable list and tries to
  95         find the given variable. If the variable is unknown a
  96         com::sun::star::container::NoSuchElementException
  97         is thrown.
  98         </p>
  99
 100         @param variable
 101             The name of a variable.
 102
 103         @return
 104             Returns a string that represents the variable. If the
 105             variable is unknown a com::sun::star::container::NoSuchElementException
 106             is thrown.
 107     */
 108     string getSubstituteVariableValue( [in] string variable )
 109         raises (::com::sun::star::container::NoSuchElementException );
 110 };
 111
 112
 113 }; }; }; };
 114
 115 #endif
 116
 117 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */