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 totrue
, 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 tofalse
, 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
All Methods Instance Methods Concrete Methods 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)
Returnstrue
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.
-
-
-
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. Ifnull
, the default locale is set.
-
set
public TemplateProcessor set(java.lang.String name, java.lang.String value)
Sets a variable.- Parameters:
name
- the variable namevalue
- 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 nameformatString
- the string that describes the formatformatArgs
- 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 isnull
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 namevalue
-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)
Returnstrue
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 isnull
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 tosymbol
- 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., variableremainder
- 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 provideremainder
- the remaining unprocessed text (may benull
)- Throws:
java.lang.IllegalArgumentException
-
-