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

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