/*---------------------------------------------------------------------------*\
$Id: f20b3b933b383a8744f75c5c14bda7947e29707b $
---------------------------------------------------------------------------
This software is released under a BSD-style license:
Copyright (c) 2004-2007 Brian M. Clapper. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. The end-user documentation included with the redistribution, if any,
must include the following acknowlegement:
"This product includes software developed by Brian M. Clapper
(bmc@clapper.org, http://www.clapper.org/bmc/). That software is
copyright (c) 2004-2007 Brian M. Clapper."
Alternately, this acknowlegement may appear in the software itself,
if wherever such third-party acknowlegements normally appear.
3. Neither the names "clapper.org", "clapper.org Java Utility Library",
nor any of the names of the project contributors may be used to
endorse or promote products derived from this software without prior
written permission. For written permission, please contact
bmc@clapper.org.
4. Products derived from this software may not be called "clapper.org
Java Utility Library", nor may "clapper.org" appear in their names
without prior written permission of Brian M. Clapper.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
NO EVENT SHALL BRIAN M. CLAPPER BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
\*---------------------------------------------------------------------------*/
package org.clapper.util.text;
/**
* This interface defines the methods for a class that does inline
* variable substitution, converting strings containing variable references
* into strings where the variables are replaced with their corresponding
* values. It defines the semantics of variable substitution, but it does
* not define the syntax. Each subclass defines its own syntax (and logic)
* for recognizing and replacing a variable reference within a string.
*
* The VariableSubstituter interface defines the minimum
* functionality and behavior of classes that provide inline string
* variable substitution. A VariableSubstituter object
* replaces variable references in a string with the variables' values.
* Examples of variable references include (but are not limited to) some of
* the following:
*
*
*
* The value of HOME is %HOME% # Windows-style variable reference
* The value of HOME is $HOME # Unix shell-style variable reference
* The value of HOME is %(HOME)s # Python ConfigParser syntax
*
*
*
* A VariableSubstituter object parses a string passed to
* it. It copies literal text from the source string to the result string;
* when it encounters a variable reference, it resolves the variable's
* value through a separate {@link VariableDereferencer} object, and
* substitutes the resulting value in place of the variable reference in
* the result string. Each individual VariableSubstituter
* class uses its own variable reference syntax. For example, the
* {@link UnixShellVariableSubstituter} class recognizes variable
* references using the traditional UNIX Bourne Shell variable syntax. The
* {@link WindowsCmdVariableSubstituter} class recognizes %-delimited
* variable references, the way the Windows cmd.exe program
* does.
*
* A VariableSubstituter object dereferences a variable's
* value by calling the getVariableValue() method in a
* VariableDereferencer object. One such object might choose
* to dereference variables by looking them up in a Properties
* object. Another might resolve variables via hard-coded method calls. Yet
* another might use a symbol table built by a parser. The variable
* substitution logic is separated from the variable dereferencing logic;
* the same variable substitution object (with its specific variable
* syntax) can resolve variables from a number of different sources.
*
* @see VariableDereferencer
*
* @version $Revision$
*
* @author Copyright © 2004-2007 Brian M. Clapper
*/
public interface VariableSubstituter
{
/*----------------------------------------------------------------------*\
Required Methods
\*----------------------------------------------------------------------*/
/**
* Substitute all variable references in the supplied string,
* returning the new String, according to the variable syntax defined
* by the implementing class. This method uses a supplied
* VariableDereferencer object to resolve variable values.
* Note that this method throws no exceptions. Syntax errors in the
* variable references are silently ignored. Variables that have no
* value are substituted as the empty string. The
* VariableSubstituter class enforces its own notion of what
* characters are legal in a variable name. If you want more control
* over the legal characters, use the second substitute
* method.
*
* @param s the string containing possible variable references
* @param deref the VariableDereferencer object
* to use to resolve the variables' values.
* @param context an optional context object, passed through unmodified
* to the deref object's
* {@link VariableDereferencer#getVariableValue} method.
* This object can be anything at all (and, in fact, may
* be null if you don't care.) It's primarily useful
* for passing context information from the caller to
* the (custom) VariableDereferencer.
*
* @return The (possibly) expanded string.
*
* @throws UndefinedVariableException undefined variable, and
* {@link #getAbortOnUndefinedVariable}
* returns true
* @throws VariableSyntaxException syntax error, and
* {@link #getAbortOnSyntaxError}
* returns true
* @throws VariableSubstitutionException substitution error
*
* @see #substitute(String,VariableDereferencer,VariableNameChecker,Object)
* @see VariableDereferencer#getVariableValue(String,Object)
*/
public String substitute (String s,
VariableDereferencer deref,
Object context)
throws VariableSubstitutionException;
/**
* Substitute all variable references in the supplied string,
* returning the new String, according to the variable syntax defined
* by the implementing class. This method uses a supplied
* VariableDereferencer object to resolve variable values.
* Note that this method throws no exceptions. Syntax errors in the
* variable references are silently ignored. Variables that have no
* value are substituted as the empty string. If the
* nameChecker parameter is not null, this method calls its
* {@link VariableNameChecker#legalVariableCharacter(char)} method to
* determine whether a given character is a legal part of a variable
* name. If nameChecker is null, then this method uses its
* own notion of legal variable name characters.
*
* @param s the string containing possible variable references
* @param deref the VariableDereferencer object
* to use to resolve the variables' values.
* @param nameChecker the VariableNameChecker object to be
* used to check for legal variable name characters,
* or null
* @param context an optional context object, passed through
* unmodified to the deref object's
* {@link VariableDereferencer#getVariableValue}
* method. This object can be anything at all (and,
* in fact, may be null if you don't care.) It's
* primarily useful for passing context information
* from the caller to the
* VariableDereferencer.
*
* @return The (possibly) expanded string.
*
* @throws VariableSubstitutionException substitution error
* @throws UndefinedVariableException undefined variable, and
* {@link #getAbortOnUndefinedVariable}
* returns true
* @throws VariableSyntaxException syntax error, and
* {@link #getAbortOnSyntaxError}
* returns true
*
* @see #substitute(String,VariableDereferencer,Object)
* @see VariableDereferencer#getVariableValue(String,Object)
*/
public String substitute (String s,
VariableDereferencer deref,
VariableNameChecker nameChecker,
Object context)
throws VariableSubstitutionException;
/**
* Get the value of the flag that controls whether the
* substitute() methods will abort when they encounter an
* undefined variable. If this flag is clear, then an undefined variable
* is expanded to an empty string. If this flag is set, then an undefined
* value results in an {@link UndefinedVariableException}.
*
* @return true if the "abort on undefined variable" capability
* is enabled, false if it is disabled.
* @see #setAbortOnUndefinedVariable
*/
public boolean getAbortOnUndefinedVariable();
/**
* Set or clear the flag that controls whether the substitute()
* methods will abort when they encounter an undefined variable. If this
* flag is clear, then an undefined variable is expanded to an empty
* string. If this flag is set, then an undefined value results in an
* {@link UndefinedVariableException}. The flag defaults to false.
*
* @param enable true to enable the "abort on undefined variable"
* flag, false to disable it.
* @see #getAbortOnUndefinedVariable
*/
public void setAbortOnUndefinedVariable(boolean enable);
/**
* Get the value of the flag that controls whether the
* substitute() methods will abort when they encounter a
* syntax error. If this flag is clear, then this object will recover
* from a syntax error (usually by leaving the syntactically bad
* variable reference untouched in the resulting string). If this flag
* is set, then a syntax error results in a
* {@link VariableSyntaxException}.
*
* @return true if the "abort on syntax error" capability
* is enabled, false if it is disabled.
*
* @see #setAbortOnUndefinedVariable
*/
public boolean getAbortOnSyntaxError();
/**
* Set or clear the flag that controls whether the
* substitute() methods will abort when they encounter a
* syntax error. If this flag is clear, then this object will recover
* from a syntax error (usually by leaving the syntactically bad
* variable reference untouched in the resulting string). If this flag
* is set, then a syntax error results in a
* {@link VariableSyntaxException}. The flag defaults to false.
*
* @param enable true to enable the "abort on syntax error"
* flag, false to disable it.
*
* @see #getAbortOnUndefinedVariable
*/
public void setAbortOnSyntaxError(boolean enable);
}
Ads help maintain this website.