org.clapper.util.text

Class UnixShellVariableSubstituter

java.lang.Object

org.clapper.util.text.AbstractVariableSubstituter

org.clapper.util.text.UnixShellVariableSubstituter

All Implemented Interfaces:

VariableNameChecker, VariableSubstituter

public class UnixShellVariableSubstituter
extends AbstractVariableSubstituter

The UnixShellVariableSubstituter class implements the VariableSubstituter interface and provides an inline variable substitution capability using a simplified Unix Bourne (or GNU bash) shell variable syntax. This syntax recognizes the "$var", "${var}" and "${var?default} sequences as variable references. For example, given the string (variables in bold):

 file:$user.home/profiles/$PLATFORM/${cfg?config}.txt
 

and the variable values:

 user.home=/home/bmc
 PLATFORM=freebsd
 

a UnixShellVariableSubstituter will produce the result string (substitutions noted in bold):

 file:/home/bmc/profiles/freebsd/config.txt
 

Notes and Caveats

1. To include a literal "$" character in a string, precede it with a backslash.
2. If a variable doesn't have a value, its reference is replaced by an empty string, unless it is of the form ${var?default}. For instance, if variable foo does not have a value, the string $foo will substitute "", ${foo} will substitute "", and ${foo?foo value} will substitute "foo value".
3. As with all VariableSubstituter classes, an instance of the UnixShellVariableSubstituter class enforces its own variable syntax (Unix Bourne shell-style, in this case), but defers actual variable value resolution to a separate VariableDereferencer object. One consequence of that approach is that variable names may be case-sensitive or case-insensitive, depending on how the supplied VariableDereferencer object interprets variable names.

It's also possible to configure a UnixShellVariableSubstituter to throw a UndefinedVariableException, rather than substituting a blank, if a variable is undefined and a default value is not specified. See the AbstractVariableSubstituter.setAbortOnUndefinedVariable(boolean) method.

See Also:

WindowsCmdVariableSubstituter, VariableDereferencer, VariableSubstituter, String

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	VARIABLE_METACHARACTERS List of metacharacters that are used to introduce a variable reference.

Constructor Summary

Constructors

Constructor and Description
UnixShellVariableSubstituter() Default constructor.

Method Summary

Modifier and Type	Method and Description
boolean	getHonorEscapes() Get the value of the flag that controls whether or not the substitute() method will honor backslash escapes within variable references.
static boolean	isVariableMetacharacter(char c) Determine whether a character is one of the variable metacharacters (i.e., the characters that identify a variable reference).
void	setHonorEscapes(boolean enable) Set the value of the flag that controls whether or not the substitute() method will honor backslash escapes within variable references.
java.lang.String	substitute(java.lang.String s, VariableDereferencer deref, VariableNameChecker nameChecker, java.lang.Object context) Substitute all variable references in the supplied string, using a Unix Bourne Shell-style variable syntax.
java.lang.String	substitute(java.lang.String s, VariableDereferencer deref, VariableNameChecker nameChecker, java.lang.Object context, boolean allowEscapes) Deprecated. As of version 2.3; please use setHonorEscapes(boolean)

Methods inherited from class org.clapper.util.text.AbstractVariableSubstituter

getAbortOnSyntaxError, getAbortOnUndefinedVariable, legalVariableCharacter, setAbortOnSyntaxError, setAbortOnUndefinedVariable, substitute, substitute

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VARIABLE_METACHARACTERS

public static final java.lang.String VARIABLE_METACHARACTERS

List of metacharacters that are used to introduce a variable reference. These characters cannot be permitted in a variable name.

Constructor Detail

UnixShellVariableSubstituter

public UnixShellVariableSubstituter()

Default constructor.

Method Detail

getHonorEscapes

public boolean getHonorEscapes()

Get the value of the flag that controls whether or not the substitute() method will honor backslash escapes within variable references.

Returns:

true if backslash escapes are honored, false if not.

See Also:

setHonorEscapes(boolean)

setHonorEscapes

public void setHonorEscapes(boolean enable)

Set the value of the flag that controls whether or not the substitute() method will honor backslash escapes within variable references. The flag defaults to false.

Parameters:

enable - true if backslash escapes should be honored, false if not.

See Also:

getHonorEscapes()

substitute

public java.lang.String substitute(java.lang.String s,
                                   VariableDereferencer deref,
                                   VariableNameChecker nameChecker,
                                   java.lang.Object context,
                                   boolean allowEscapes)
                            throws VariableSyntaxException,
                                   UndefinedVariableException,
                                   VariableSubstitutionException

Deprecated. As of version 2.3; please use setHonorEscapes(boolean)

Substitute all variable references in the supplied string, using a Unix Bourne Shell-style variable syntax. 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 assumes that variable names may consist solely of alphanumeric characters, underscores and periods. This syntax is sufficient to substitute variables from System.properties, for instance.

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.

allowEscapes - whehther or not escape sequences are honored

Returns:

The (possibly) expanded string.

Throws:

UndefinedVariableException - undefined variable, and AbstractVariableSubstituter.getAbortOnUndefinedVariable() returns true

VariableSyntaxException - syntax error, and AbstractVariableSubstituter.getAbortOnSyntaxError() returns true

VariableSubstitutionException - substitution error

See Also:

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

substitute

public java.lang.String substitute(java.lang.String s,
                                   VariableDereferencer deref,
                                   VariableNameChecker nameChecker,
                                   java.lang.Object context)
                            throws VariableSyntaxException,
                                   UndefinedVariableException,
                                   VariableSubstitutionException

Substitute all variable references in the supplied string, using a Unix Bourne Shell-style variable syntax. 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 assumes that variable names may consist solely of alphanumeric characters, underscores and periods. This syntax is sufficient to substitute variables from System.properties, for instance.

Specified by:

substitute in interface VariableSubstituter

Specified by:

substitute in class AbstractVariableSubstituter

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:

UndefinedVariableException - undefined variable, and AbstractVariableSubstituter.getAbortOnUndefinedVariable() returns true

VariableSyntaxException - syntax error, and AbstractVariableSubstituter.getAbortOnSyntaxError() returns true

VariableSubstitutionException - substitution error

See Also:

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

isVariableMetacharacter

public static boolean isVariableMetacharacter(char c)

Determine whether a character is one of the variable metacharacters (i.e., the characters that identify a variable reference). Such characters cannot be part of a variable name.

Parameters:

c - the character to test

Returns:

true if the character is one of the variable metacharacters, false if not