Package ca.cgjennings.text

Class TemplateProcessor

java.lang.Object

ca.cgjennings.text.TemplateProcessor

Direct Known Subclasses:

SETemplateProcessor

public class TemplateProcessor
extends java.lang.Object

A template processor assists in the automated writing of scripts and other text files by filling in a template file using variables and simple boolean conditions. Sections of the template that are to be generated automatically are marked with symbols. A symbol consists of a special token placed between braces. The tokens begin with a specific marker character and are followed by an identifier. The identifier may consist of any characters except spaces or the closing brace. The following codes are recognized:

{%variable}
Replaces the symbol with the value of the variable. Throws an exception if the variable is undefined.

{?condition} ... {/?condition}
If the condition is set to true, then the text between the start and end symbols will be included in the document. Otherwise, it will be left out. Throws an exception if the condition has not been set.

{!condition} ... {/!condition}
If the condition is set to false, then the text between the start and end symbols will be included in the document. Otherwise, it will be left out. Throws an exception if the condition has not been set.

Since:

3.0

Author:

Chris Jennings

Constructor Summary

Constructors

Constructor	Description
TemplateProcessor()	Creates a new processor that uses the default locale when adding format strings.
TemplateProcessor(TemplateProcessor source)	Creates a new processor that copies its locales, variables, and conditions from another processor.
TemplateProcessor(java.util.Locale locale)	Creates a new processor that uses the specified locale when adding format strings.

Method Summary

Modifier and Type	Method	Description
protected void	error(java.lang.String message, java.lang.String remainder)	Throws an exception to describe a parsing error.
java.lang.String	get(java.lang.String name)	Returns the value of a variable.
java.util.Locale	getLocale()	Returns the locale used to process format strings.
boolean	isConditionSet(java.lang.String name)	Returns true if the named condition is set.
java.lang.String	process(java.lang.String template)	Processes a template, replacing the symbols as specified in the class description.
protected java.lang.String	processSymbol(java.lang.StringBuilder buffer, java.lang.String symbol, char code, java.lang.String name, java.lang.String remainder)	This method is called to process a symbol.
TemplateProcessor	set(java.lang.String name, java.lang.String value)	Sets a variable.
TemplateProcessor	set(java.lang.String name, java.lang.String formatString, java.lang.Object... formatArgs)	Sets a variable to the result of formatting the string using the template processor's locale.
TemplateProcessor	setAll(java.lang.String... nameValuePairs)	Sets a group of variable definitions from an array.
TemplateProcessor	setCondition(java.lang.String name, boolean value)	Sets the value of a condition.
void	setLocale(java.util.Locale locale)	Sets the locale used to process format strings.

Methods inherited from class java.lang.Object

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

Constructor Detail

TemplateProcessor

public TemplateProcessor()

Creates a new processor that uses the default locale when adding format strings.

TemplateProcessor

public TemplateProcessor(java.util.Locale locale)

Creates a new processor that uses the specified locale when adding format strings.

Parameters:

locale - the locale to use when formatting strings

TemplateProcessor

public TemplateProcessor(TemplateProcessor source)

Creates a new processor that copies its locales, variables, and conditions from another processor.

Parameters:

source -

Method Detail

getLocale

public java.util.Locale getLocale()

Returns the locale used to process format strings.

Returns:

the formatting locale

setLocale

public void setLocale(java.util.Locale locale)

Sets the locale used to process format strings. If null, the default locale is set.

set

public TemplateProcessor set(java.lang.String name,
                             java.lang.String value)

Sets a variable.

Parameters:

name - the variable name

value - the string value of the variable

Returns:

this processor, so that the method can be chained

set

public TemplateProcessor set(java.lang.String name,
                             java.lang.String formatString,
                             java.lang.Object... formatArgs)

Sets a variable to the result of formatting the string using the template processor's locale.

Parameters:

name - the variable name

formatString - the string that describes the format

formatArgs - the arguments used to complete the format string

Returns:

this processor, so that the method can be chained

setAll

public TemplateProcessor setAll(java.lang.String... nameValuePairs)

Sets a group of variable definitions from an array. The elements of the array form pairs of variable names and values, with the names at even array indices. Example:
setAll( "var1", "apple", "var2", "3.14159", "var3", "sun dance" )

Parameters:

nameValuePairs - the pairs of variable names and values to set

Returns:

this processor, so that the method can be chained

get

public java.lang.String get(java.lang.String name)

Returns the value of a variable.

Parameters:

name - the variable name

Returns:

the value of the variable

Throws:

java.lang.NullPointerException - if the variable name is null

java.lang.IllegalArgumentException - if the variable name is undefined

setCondition

public TemplateProcessor setCondition(java.lang.String name,
                                      boolean value)

Sets the value of a condition.

Parameters:

name - the condition name

value - true if the condition is to be set

Returns:

this processor, so that the method can be chained

isConditionSet

public boolean isConditionSet(java.lang.String name)

Returns true if the named condition is set.

Parameters:

name - the name of the condition

Returns:

true if the named condition is set

Throws:

java.lang.NullPointerException - if the variable name is null

java.lang.IllegalArgumentException - if the variable name is undefined

process

public java.lang.String process(java.lang.String template)

Processes a template, replacing the symbols as specified in the class description.

Parameters:

template - the template text to process

Returns:

the filled-in template

processSymbol

protected java.lang.String processSymbol(java.lang.StringBuilder buffer,
                                         java.lang.String symbol,
                                         char code,
                                         java.lang.String name,
                                         java.lang.String remainder)

This method is called to process a symbol. Subclasses may override it to extend the template processor's capabilities. The pattern for doing so is to first check the code against those codes that you wish to handle and then either handle the symbol in the subclass or return the result of the super implementation. A typical code pattern is:

 protected String processSymbol( StringBuilder buffer, String symbol, char code, String name, String remainder ) {
     switch( code ) {
         case '*':
             buffer.append( "text for a *-code with variable name: " + name );
             break;
         // ...
         default:
             remainder = super( buffer, symbol, code, name, remainder );
     }
     return remainder;
 }
 

Parameters:

buffer - a buffer that the symbol's replacement text, if any, should be appended to

symbol - the full text of the symbol, e.g., {%variable}

code - the single-character code identifying the symbol type, e.g., %

name - the name part of the the symbol following the code, e.g., variable

remainder - the template text that follows the symbol

Returns:

the template text that follows the symbol after the symbol is processed (usually just remainder)

Throws:

java.lang.IllegalArgumentException - if there is a syntax error in the template or a runtime error (such as an undefined variable)

error

protected void error(java.lang.String message,
                     java.lang.String remainder)
              throws java.lang.IllegalArgumentException

Throws an exception to describe a parsing error. The value of remainder is used to provide context about the error.

Parameters:

message - the error message to provide

remainder - the remaining unprocessed text (may be null)

Throws:

java.lang.IllegalArgumentException