org.clapper.util.text
Class WindowsCmdVariableSubstituter

java.lang.Object
  org.clapper.util.text.AbstractVariableSubstituter
      org.clapper.util.text.WindowsCmdVariableSubstituter

All Implemented Interfaces:

VariableNameChecker, VariableSubstituter

public class WindowsCmdVariableSubstituter
extends AbstractVariableSubstituter

The WindowsCmdVariableSubstituter class implements the VariableSubstituter interface and provides an inline variable substitution capability using a syntax that's reminiscent of the Microsoft Windows cmd.exe command interpreter. This syntax assumes that variable references are surrounded by "%" characters. For example, given the string (variables in bold):

 file:%user.home%/profiles/%PLATFORM%/config.txt
 

and the variable values:

 user.home=/home/bmc
 PLATFORM=freebsd
 

a WindowsCmdVariableSubstituter 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, double it.
2. If a variable doesn't have a value, its reference is replaced by an empty string.
3. As with all VariableSubstituter classes, an instance of the WindowsCmdVariableSubstituter class enforces its own variable syntax 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 WindowsCmdVariableSubstituter 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.

Version:

$Revision: 6735 $

Author:

Copyright © 2004-2007 Brian M. Clapper

See Also:

UnixShellVariableSubstituter, VariableDereferencer, VariableSubstituter, String

Constructor Summary

WindowsCmdVariableSubstituter()
Default constructor.

Method Summary

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.

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

Constructor Detail

WindowsCmdVariableSubstituter

public WindowsCmdVariableSubstituter()

Default constructor.

Method Detail

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 and underscores.

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:

VariableSubstitutionException - substitution error

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

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

See Also:

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