Module org.klojang.templates
Package org.klojang.templates

Class Regex

java.lang.Object
org.klojang.templates.Regex
public final class Regex extends Object
Tokens and regular expressions used by the template parser to parse templates. For all intents and purposes, this is an internal class. However, by making this class and the constants defined in it public, the API documentation as a whole becomes more self-contained as it is the only class from which you can infer which syntactical constructs are available in a Klojang template. This class might also be useful for toolmakers (e.g. when writing a syntax highlighting plugin).

  • Field Details

    • REGEX_VAR_GROUP

      public static final String REGEX_VAR_GROUP
      Regular expression for variable group names. Variable groups can be specified inline (within the template) using this syntax: ~%vargroup:varname%. For example: ~%html:firstName%. Variable group names must start with a letter and be followed by zero or more letters, digits, underscores or hyphens. "begin" and "end" are illegal names for variable groups.
      See Also:

    • REGEX_NAME

      public static final String REGEX_NAME
      Regular expression for nested template names and path segments within a variable name. Since these names may correspond to keys in Map objects, there are very few constraints on what constitutes a valid name. They must consist of at least one character, and they must not contain any of the following characters: ~%:.\n\r\0. Of course, if the names are to correspond to, for example, bean properties, they are externally constrained: they must be valid Java identifiers.
      See Also:

    • REGEX_PATH

      public static final String REGEX_PATH

      Regular expression for path strings. Variable names are paths through an object graph. For example: ~%company.address.city%. This variable would map to the city property of the Address object within the Company object within the object that you populate the template with. Each of the name segments must match REGEX_NAME. In practice, you are more likely to use nested and doubly-nested templates, and then use simple names at the appropriate nesting level (e.g. ~%city%).

      Do not confuse this regular expression with REGEX_INCLUDE_PATH). The latter is used for included templates, in which you specify a path to a file system or classpath resource.

      See Also:

    • REGEX_VARIABLE

      public static final String REGEX_VARIABLE
      Regular expression for template variables. The pattern for a variable name is: ~%[vargroup:]varname%, where vargroup is REGEX_VAR_GROUP and varname is REGEX_PATH.
      See Also:

    • REGEX_CMT_VARIABLE

      public static final String REGEX_CMT_VARIABLE

      Regular expression for a template variable that is placed inside an HTML comment. For example: <!-- ~%firstName% -->. This is rendered just like ~%firstName%. However, when using HTML comments, the raw, unprocessed template still renders nicely in a browser — without "odd" tilde-percent sequences spoiling the HTML page. This works even better if you also provide a placeholder value, as in the following example: <!-- ~%firstName% -->John<!--%-->. This, too, renders just like ~%firstName%. Now, when the browser renders the raw template, it will display the string "John", because it is outside any HTML comments. But when Klojang Templates renders the template, "John" will have disappeared, and the only thing that remains is the value of firstName.

      Note that the entire construct (<!-- ~%firstName% -->John<!--%-->) must be on a single line. If you want to provide a placeholder value that spans multiple lines, use the syntax in the example below: 

      
 <tr>
   <td>
   <!-- ~%firstName% -->
   <!--%-->
       This entire piece of text, and
       the placeholder tags on either
       side of it, will be gone when
       the template is rendered
   <!--%-->
   </td>
 </tr>

      However, contrary to the single-line syntax, this value is not recorded as the placeholder for the preceding variable. It is just something that will be visible in the raw template, but gone in the rendered version.

      The space character surrounding the variable (as in <!-- ~%firstName% -->) is optional. You may also omit it (<!--~%firstName%-->). Multiple spaces or other characters are not allowed.

      See Also:

    • REGEX_INLINE_TEMPLATE_BEGIN

      public static final String REGEX_INLINE_TEMPLATE_BEGIN

      Regular expression for inline templates begin tags. The following examples are all valid begin tags:

      • ~%%begin:foo%
      • <!-- ~%%begin:foo%
      • <!-- ~%%begin:foo% -->

      However, the parser enforces an extra symmetry:

      • <!-- ~%%begin:foo% --> must terminate with <!-- ~%%end:foo% -->
      • <!-- ~%%begin:foo% must terminate with ~%%end:foo% -->
      • ~%%begin:foo% must terminate with ~%%end:foo%

      The space character following "<!--" and/or preceding "-->" is optional. Multiple spaces or other characters are not allowed.

      See Also:

    • REGEX_INLINE_TEMPLATE_END

      public static final String REGEX_INLINE_TEMPLATE_END

      Regular expression for inline templates end tags. The following examples are all valid end tags:

      • ~%%end:foo%
      • ~%%end:foo% -->
      • <!-- ~%%end:foo% -->

      However, the parser enforces an extra symmetry:

      • <!-- ~%%begin:foo% --> must terminate with <!-- ~%%end:foo% -->
      • <!-- ~%%begin:foo% must terminate with ~%%end:foo% -->
      • ~%%begin:foo% must terminate with ~%%end:foo%

      The space character following "<!--" and/or preceding "-->" is optional. Multiple spaces or other characters are not allowed.

      See Also:

    • REGEX_INCLUDE_PATH

      public static final String REGEX_INCLUDE_PATH
      Regular expression for the path specified in an included template. Templates are included in another template using this syntax: ~%%include:/path/to/template.html%% or ~%%include:template-name:/path/to/template.html%%. The path is a sequence of one more valid URL characters. So: letters, digits and: _-~:;/?#!$&%,@+.=[]().
      See Also:

    • REGEX_INCLUDED_TEMPLATE

      public static final String REGEX_INCLUDED_TEMPLATE
      Regular expression for included templates. This is the basic pattern: ~%%include:[template-name:]path%%. If no name is provided, the template name will be the base name of the last path element. So for ~%%include:/path/to/foo.html%% that would be "foo".
      See Also:

    • REGEX_CMT_INCLUDED_TEMPLATE

      public static final String REGEX_CMT_INCLUDED_TEMPLATE
      Regular expression for an included template that is placed inside an HTML comment. For example: <!-- ~%%include:/path/to/foo.html%% -->.
      See Also:

    • REGEX_DITCH_BLOCK

      public static final String REGEX_DITCH_BLOCK
      Regular expression for ditch blocks. A ditch block consists of a pair of <!--%%--> tokens and any text between them. A ditch block is the Klojang Templates equivalent of an HTML or Java comment. Ditch blocks can be used to "comment out" nested templates, template variables, static HTML, etc. They cannot themselves be nested inside any syntactical construct provided by Klojang Templates, including nested templates.
      See Also:

    • REGEX_PLACEHOLDER

      public static final String REGEX_PLACEHOLDER
      Regular expression for placeholders. A placeholder consists of a pair of <!--%--> tokens and any text between them. When a template is rendered by Klojang Templates, these tokens, and any text between them are erased from the template. However, since <!--%--> is a self-closed HTML comment, a browser would display what is between these tokens when rendering the raw, unprocessed template. Contrary to ditch blocks, placeholders may appear inside a nested template.
      See Also:

  • Method Details

    • printAll

      public static void printAll()
      Prints the regular expressions.