org.clapper.util.text
Interface VariableSubstituter

All Known Implementing Classes:

AbstractVariableSubstituter, UnixShellVariableSubstituter, WindowsCmdVariableSubstituter

public interface VariableSubstituter

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 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 UnixShellVariableSubstituter class recognizes variable references using the traditional UNIX Bourne Shell variable syntax. The 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.

Version:

$Revision: 6735 $

Author:

Copyright © 2004-2007 Brian M. Clapper

See Also:

VariableDereferencer

Method Summary

boolean	getAbortOnSyntaxError() Get the value of the flag that controls whether the substitute() methods will abort when they encounter a syntax error.
boolean	getAbortOnUndefinedVariable() Get the value of the flag that controls whether the substitute() methods will abort when they encounter an undefined variable.
void	setAbortOnSyntaxError(boolean enable) Set or clear the flag that controls whether the substitute() methods will abort when they encounter a syntax error.
void	setAbortOnUndefinedVariable(boolean enable) Set or clear the flag that controls whether the substitute() methods will abort when they encounter an undefined variable.
java.lang.String	substitute(java.lang.String s, VariableDereferencer deref, java.lang.Object context) Substitute all variable references in the supplied string, returning the new String, according to the variable syntax defined by the implementing class.
java.lang.String	substitute(java.lang.String s, VariableDereferencer deref, VariableNameChecker nameChecker, java.lang.Object context) Substitute all variable references in the supplied string, returning the new String, according to the variable syntax defined by the implementing class.

Method Detail

substitute

java.lang.String substitute(java.lang.String s,
                            VariableDereferencer deref,
                            java.lang.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. 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.

Parameters:

s - the string containing possible variable references

deref - the VariableDereferencer object to use to resolve the variables' values.

context - an optional context object, passed through unmodified to the deref object's VariableDereferencer.getVariableValue(java.lang.String, java.lang.Object) 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.

Returns:

The (possibly) expanded string.

Throws:

UndefinedVariableException - undefined variable, and getAbortOnUndefinedVariable() returns true

VariableSyntaxException - syntax error, and getAbortOnSyntaxError() returns true

VariableSubstitutionException - substitution error

See Also:

substitute(String,VariableDereferencer,VariableNameChecker,Object), VariableDereferencer.getVariableValue(String,Object)

substitute

java.lang.String substitute(java.lang.String s,
                            VariableDereferencer deref,
                            VariableNameChecker nameChecker,
                            java.lang.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 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.

Parameters:

s - the string containing possible variable references

deref - the VariableDereferencer object to use to resolve the variables' values.

nameChecker - the VariableNameChecker object to be used to check for legal variable name characters, or null

context - an optional context object, passed through unmodified to the deref object's VariableDereferencer.getVariableValue(java.lang.String, java.lang.Object) 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.

Returns:

The (possibly) expanded string.

Throws:

VariableSubstitutionException - substitution error

UndefinedVariableException - undefined variable, and getAbortOnUndefinedVariable() returns true

VariableSyntaxException - syntax error, and getAbortOnSyntaxError() returns true

See Also:

substitute(String,VariableDereferencer,Object), VariableDereferencer.getVariableValue(String,Object)

getAbortOnUndefinedVariable

boolean getAbortOnUndefinedVariable()

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 UndefinedVariableException.

Returns:

true if the "abort on undefined variable" capability is enabled, false if it is disabled.

See Also:

setAbortOnUndefinedVariable(boolean)

setAbortOnUndefinedVariable

void setAbortOnUndefinedVariable(boolean enable)

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 UndefinedVariableException. The flag defaults to false.

Parameters:

enable - true to enable the "abort on undefined variable" flag, false to disable it.

See Also:

getAbortOnUndefinedVariable()

getAbortOnSyntaxError

boolean getAbortOnSyntaxError()

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 VariableSyntaxException.

Returns:

true if the "abort on syntax error" capability is enabled, false if it is disabled.

See Also:

setAbortOnUndefinedVariable(boolean)

setAbortOnSyntaxError

void setAbortOnSyntaxError(boolean enable)

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 VariableSyntaxException. The flag defaults to false.

Parameters:

enable - true to enable the "abort on syntax error" flag, false to disable it.

See Also:

getAbortOnUndefinedVariable()