1/************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24#ifndef __com_sun_star_util_XStringSubstitution_idl__ 25#define __com_sun_star_util_XStringSubstitution_idl__ 26 27#ifndef __com_sun_star_uno_XInterface_idl__ 28#include <com/sun/star/uno/XInterface.idl> 29#endif 30 31#ifndef __com_sun_star_container_NoSuchElementException_idl__ 32#include <com/sun/star/container/NoSuchElementException.idl> 33#endif 34 35//============================================================================= 36 37 module com { module sun { module star { module util { 38 39//============================================================================= 40/** A common interface for substituting string variables with 41 other strings. 42 43 <p> 44 The substitution algorithm and the syntax for a string variable are 45 not part of this interface definition. Please look at the documentation 46 of the implementation that must specify these parameters. 47 </p> 48 49 @since OpenOffice 1.1.2 50*/ 51published interface XStringSubstitution : com::sun::star::uno::XInterface 52{ 53 //------------------------------------------------------------------------- 54 /** Exchanges variables inside a given text with a substitution text 55 defined for the variables. 56 57 <p> 58 The method iterates through it's internal variables list to match the 59 variables in the given string. A match replaces the variable with the 60 string defined for this variable. If no variable can be found in the string 61 it will be returned unchanged. The behavior if a variable is found in 62 the string but it is unknown for the implementation depends on the parameter 63 bSubstRequired. 64 </p> 65 66 @param aText 67 A string containing variables that should be substituted. 68 69 @param bSubstRequired 70 Specifies if a successfull substitution is required. The 71 function throws a <type scope="com::sun::star::container">NoSuchElementException</type> 72 if it finds a variable that is unknown. In this case it is possible 73 that the returned string would not be what the caller expected! 74 75 @return 76 Returns a string based on <var>aText</var> where all variables were 77 exchanged with their value defined at calling time. 78 */ 79 string substituteVariables( [in] string aText, [in] boolean bSubstRequired ) 80 raises( com::sun::star::container::NoSuchElementException ); 81 82 //------------------------------------------------------------------------- 83 /** Tries to replace parts of aText with variables that represents 84 these sub strings. 85 86 <p> 87 The method iterates through it's internal variable list and tries to match 88 parts of the given string Tries to replace parts of <var>aText</var> with 89 variables that represents these sub strings.If more than one variable 90 matches the one with the longest matching sub string will be chosen. 91 </p> 92 93 @param aText 94 A string where known substrings should be replaced by variables. 95 96 @return 97 Returns the resubstituted string with variables for all parts 98 that could be replaced. The unchanged argument will be returned 99 if nothing can be resubtituted. 100 */ 101 102 string reSubstituteVariables( [in] string aText ); 103 104 //------------------------------------------------------------------------- 105 /** Returns the current value of a variable. 106 107 <p> 108 The method iterates through it's internal variable list and tries to 109 find the given variable. If the variable is unkown a 110 <type scope="com::sun::star::container">NoSuchElementException</type> 111 is thrown. 112 </p> 113 114 @param variable 115 The name of a variable. 116 117 @return 118 Returns a string that represents the variable. If the 119 variable is unknown a <type scope="com::sun::star::container">NoSuchElementException</type> 120 is thrown. 121 */ 122 string getSubstituteVariableValue( [in] string variable ) 123 raises (::com::sun::star::container::NoSuchElementException ); 124}; 125 126//============================================================================= 127 128}; }; }; }; 129 130#endif 131