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