Class TemplateProcessor

java.lang.Object
org.bzdev.util.TemplateProcessor

public class TemplateProcessor extends Object
Template Processor. A template processor is initialized with a list of keymaps, searched last to first so that later entries override previous one. A template file contains text and directives. The directives are denoted by an initial '$' followed by a delimiter, the default being '('. The directive consists of all the text up to but not including the closing delimiter, whose default is ')'. The sequence "$$" is replaced with a single '$' and any following character is treated as an ordinary character.

The directives are treated as follows:

  • Directives starting with '!' are treated as comments.
  • A directive consisting of letters, digits, underscores ('_') or periods ('.') indicate that text is to be replaced. The directive is treated as a string used to look up a replacement string. If the lookup fails, the replacement is an empty string.
  • A directive consisting of two subdirectives (sequences of letters, digits, underscores, or periods), with the two sequences separated by a colon (":") indicate repetition. The first subdirective is treated as a string used to look up an array of KeyMap objects. The second subdirective indicates the name of a directive terminating the part of the template where iteration applies. For this region, each KeyMap is put at the top of a KeyMap stack in turn and that region of the template is processed until the KeyMap array is exhausted. Iterations can be nested, but the names of the second subdirective of different iteration directives must differ if the iteration directives are nested, and the names of the first subdirective of an iteration directive must not collide with the name of a string-replacement directive (otherwise only one will be visible).
  • A directive consisting of a '+' or '-' followed by two subdirectives (sequences of letters, digits, underscores, or periods), with the two sequences separated by a colon (":") indicate repetition conditionally:
    • When the first subdirective is prefaced by a '+' and there is no key matching the subdirective, no iterations will be performed. If there is a key, the default number of iterations is 1, but that can be changed by using the method TemplateProcessor.KeyMap.put(String,Object,Object,Object).
    • When the first subdirective is prefaced by a '-' and there is a key matching the subdirective, no iterations will be performed. If there is not a key, the default number of iterations is 1, but that can be changed by using the method TemplateProcessor.KeyMap.put(String,Object,Object,Object).
    Directives with a '+' or '-' can be used to create conditional statements without having to explicitly add new directives whose only use is to indicate status.

KeyMap keys must match directives. For a simple replacement, the value must be a string. For iteration, the KeyMap key corresponding to the first subdirective must be an array of KeyMap instances or an instance of TemplateProcessor.KeyMapIterable, determining the mappings to be used in each iteration. As a special case, if the KeyMap value is another KeyMap, the iteration includes only that KeyMap. The class TemplateProcessor.KeyMapList provides a list implementation of the KeyMapIterable interface.

  • Constructor Details

    • TemplateProcessor

      public TemplateProcessor(TemplateProcessor.KeyMap... tbls)
      Constructor.
      Parameters:
      tbls - a list of KeyMap tables, searched last to first for a value matching a key.
  • Method Details

    • setDelimiter

      public void setDelimiter(char delim)
      Set the open-delimiter character. The matching close-delimiter character is implied. The default delimiter is '('.
      Parameters:
      delim - an open delimiter, either '(', '{', '[', or '<'.
    • processTemplate

      public void processTemplate(Reader reader, Writer writer) throws IOException
      Process a template.
      Parameters:
      reader - the Reader used to read a template
      writer - the Writer used to output the replacement text
      Throws:
      IOException - an IO error occurred during processing
    • processTemplate

      public void processTemplate(Reader reader, int sizeHint, Writer writer) throws IOException
      Process a template given a size hint for buffering.
      Parameters:
      reader - the Reader used to read a template
      sizeHint - the buffer space to allocate for copying.
      writer - the Writer used to output the replacement text
      Throws:
      IOException - an IO error occurred during processing
    • processTemplate

      public void processTemplate(Reader reader, String encoding, File outputFile) throws IOException
      Process a template given a reader, specifying the output as a file.
      Parameters:
      reader - the Reader used to read a template
      encoding - the character encoding for the output file
      outputFile - a file in which the output is stored
      Throws:
      IOException - an IO error occurred during processing
    • processTemplate

      public void processTemplate(Reader reader, String encoding, OutputStream os) throws IOException
      Process a template given a reader and output stream.
      Parameters:
      reader - the Reader used to read a template
      encoding - the character encoding for the output stream
      os - the output stream
      Throws:
      IOException - an IO error occurred during processing
    • processSystemResource

      public void processSystemResource(String resource, String encoding, File outputFile) throws IOException
      Process a template stored as a system resource, specifying the output as a File. This can be problematic with Java modules unless the module containing the resource is an open module.
      Parameters:
      resource - the name of the resource containing the template
      encoding - the character encoding for the resource
      outputFile - a file in which the output is stored
      Throws:
      IOException - an IO error occurred during processing
    • processSystemResource

      public void processSystemResource(String resource, String encoding, Writer writer) throws IOException
      Process a template stored as a system resource. This can be problematic with Java modules unless the module containing the resource is an open module.
      Parameters:
      resource - the name of the resource containing the template
      encoding - the character encoding for the resource
      writer - the Writer used to output the replacement text
      Throws:
      IOException - an IO error occurred during processing
    • processSystemResource

      public void processSystemResource(String resource, String encoding, OutputStream os) throws IOException
      Process a template stored as a system resource, specifying the output as an output stream. This can be problematic with Java modules unless the module containing the resource is an open module.
      Parameters:
      resource - the name of the resource containing the template
      encoding - the character encoding for the resource
      os - an output stream for the processed template
      Throws:
      IOException - an IO error occurred during processing
    • processSystemResource

      public void processSystemResource(Class clasz, String resource, String encoding, File outputFile) throws IOException
      Process a template stored as a system resource, specifying the output as a File and provided a class in the same package as the resource. Typically, the first argument will be this.getClass() or just getClass(). The first argument is needed in most cases due to the restrictions modules place on the visibility of resources.
      Parameters:
      clasz - a class in the same package as the resource
      resource - the name of the resource containing the template
      encoding - the character encoding for the resource
      outputFile - a file in which the output is stored
      Throws:
      IOException - an IO error occurred during processing
    • processSystemResource

      public void processSystemResource(Class clasz, String resource, String encoding, Writer writer) throws IOException
      Process a template stored as a system resource and provided a class in the same package as the resource. Typically, the first argument will be this.getClass() or just getClass(). The first argument is needed in most cases due to the restrictions modules place on the visibility of resources.
      Parameters:
      clasz - a class in the same package as the resource
      resource - the name of the resource containing the template
      encoding - the character encoding for the resource
      writer - the Writer used to output the replacement text
      Throws:
      IOException - an IO error occurred during processing
    • processSystemResource

      public void processSystemResource(Class clasz, String resource, String encoding, OutputStream os) throws IOException
      Process a template stored as a system resource, specifying the output as an output stream and provided a class in the same package as the resource. Typically, the first argument will be this.getClass() or just getClass(). The first argument is needed in most cases due to the restrictions modules place on the visibility of resources.
      Parameters:
      clasz - a class in the same package as the resource
      resource - the name of the resource containing the template
      encoding - the character encoding for the resource
      os - an output stream for the processed template
      Throws:
      IOException - an IO error occurred during processing
    • processURL

      public void processURL(URL url, String encoding, Writer writer) throws IOException
      Process a template located via a URL.
      Parameters:
      url - the url locating the template
      encoding - the character encoding for the resource
      writer - the Writer used to create the output
      Throws:
      IOException - an IO error occurred during processing
    • processURL

      public void processURL(URL url, String encoding, File outputFile) throws IOException
      Process a template located via a URL, specifying the output as a File.
      Parameters:
      url - the url locating the template
      encoding - the character encoding for the resource
      outputFile - a file in which the output is stored
      Throws:
      IOException - an IO error occurred during processing
    • processURL

      public void processURL(URL url, String encoding, OutputStream os) throws IOException
      Process a template located via a URL, specifying the output as an output stream.
      Parameters:
      url - the url locating the template
      encoding - the character encoding for the resource
      os - an output stream for the processed template
      Throws:
      IOException - an IO error occurred during processing