Class 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

      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)
      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