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*/ 55published 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 135