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

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27
  28 #ifndef __com_sun_star_util_XStringSubstitution_idl__
  29 #define __com_sun_star_util_XStringSubstitution_idl__
  30
  31 #ifndef __com_sun_star_uno_XInterface_idl__
  32 #include <com/sun/star/uno/XInterface.idl>
  33 #endif
  34
  35 #ifndef __com_sun_star_container_NoSuchElementException_idl__
  36 #include <com/sun/star/container/NoSuchElementException.idl>
  37 #endif
  38
  39 //=============================================================================
  40
  41  module com {  module sun {  module star {  module  util {
  42
  43 //=============================================================================
  44 /** A common interface for substituting string variables with
  45     other strings.
  46
  47     <p>
  48     The substitution algorithm and the syntax for a string variable are
  49     not part of this interface definition.  Please look at the documentation
  50     of the implementation that must specify these parameters.
  51     </p>
  52
  53     @since OOo 1.1.2
  54 */
  55 published interface XStringSubstitution : com::sun::star::uno::XInterface
  56 {
  57     //-------------------------------------------------------------------------
  58     /** Exchanges variables inside a given text with a substitution text
  59         defined for the variables.
  60
  61         <p>
  62         The method iterates through it's internal variables list to match the
  63         variables in the given string. A match replaces the variable with the
  64         string defined for this variable. If no variable can be found in the string
  65         it will be returned unchanged. The behavior if a variable is found in
  66         the string but it is unknown for the implementation depends on the parameter
  67         bSubstRequired.
  68         </p>
  69
  70         @param aText
  71             A string containing variables that should be substituted.
  72
  73         @param bSubstRequired
  74             Specifies if a successfull substitution is required. The
  75             function throws a <type scope="com::sun::star::container">NoSuchElementException</type>
  76             if it finds a variable that is unknown. In this case it is possible
  77             that the returned string would not be what the caller expected!
  78
  79         @return
  80             Returns a string based on <var>aText</var> where all variables were
  81             exchanged with their value defined at calling time.
  82     */
  83     string substituteVariables( [in] string aText, [in] boolean bSubstRequired )
  84         raises( com::sun::star::container::NoSuchElementException );
  85
  86     //-------------------------------------------------------------------------
  87     /** Tries to replace parts of aText with variables that represents
  88         these sub strings.
  89
  90         <p>
  91         The method iterates through it's internal variable list and tries to match
  92         parts of the given string Tries to replace parts of <var>aText</var> with
  93         variables that represents these sub strings.If more than one variable
  94         matches the one with the longest matching sub string will be chosen.
  95         </p>
  96
  97         @param aText
  98             A string where known substrings should be replaced by variables.
  99
 100         @return
 101             Returns the resubstituted string with variables for all parts
 102             that could be replaced. The unchanged argument will be returned
 103             if nothing can be resubtituted.
 104     */
 105
 106     string reSubstituteVariables( [in] string aText );
 107
 108     //-------------------------------------------------------------------------
 109     /** Returns the current value of a variable.
 110
 111         <p>
 112         The method iterates through it's internal variable list and tries to
 113         find the given variable. If the variable is unkown a
 114         <type scope="com::sun::star::container">NoSuchElementException</type>
 115         is thrown.
 116         </p>
 117
 118         @param variable
 119             The name of a variable.
 120
 121         @return
 122             Returns a string that represents the variable. If the
 123             variable is unknown a <type scope="com::sun::star::container">NoSuchElementException</type>
 124             is thrown.
 125     */
 126     string getSubstituteVariableValue( [in] string variable )
 127         raises (::com::sun::star::container::NoSuchElementException );
 128 };
 129
 130 //=============================================================================
 131
 132 }; }; }; };
 133
 134 #endif