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