de.caff.util.templ

## Class Template

- java.lang.Object
- - de.caff.util.templ.Template

-     public class Template
      extends java.lang.Object

  A simple class for string substitution in templates.

  Templates are just defined by strings which contain placeholders. Placeholders may contain defaults which are used when no user-defined value is provided.

  - General text is just text. I.e., anything that is not a placeholder.
  - Normal placeholders have the form `%{name}` where name is at least one character long and consists of ASCII letters, decimal numbers, colons, double colons, underscores, or plus and minus signs.
  - Placeholders with defaults have the form `%{name|@default@}`, where the rules for name are the same as for normal placeholders. The vertical bar indicates a default, which itself is enclosed in any letter of your choice as a marker (here for example `@`) is used. This allows the default text to contain any letters, you have to take care to enclose it in a letter which is not contained in combination with a directly following closing brace. So the above example could also contain email addresses without problems. The substitution test extent over multiple lines.

    For nicer optics there are a few markers that expect a different end marker (here `...` stands for the fallback text):

    - `%{name|<...>}`
    - `%{name|(...)}`
    - `%{name|[...]}`
    - `%{name|{...}}`
    and this also works the other way round, e.g. `%{name|>...<}`.
  Since:
    December 12, 2022
  Author:
    Rammi

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static java.lang.String` | `FALLBACK_SEPARATOR` The separator used to include a fallback.
    `(package private) static java.lang.String` | `PLACEHOLDER_PREFIX` Prefix of a text holder mark.
    `(package private) static java.lang.String` | `PLACEHOLDER_SUFFIX` Suffix of a text holder mark.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String` | `apply(Dict<java.lang.String,java.lang.String> variableMapping)` Apply the given variable mapping and return the result.
    `java.lang.String` | `apply(java.util.Map<java.lang.String,java.lang.String> variableMapping)` Apply the given variable mapping and return the result.
    `java.lang.String` | `apply(java.lang.String name1, java.lang.Object value1, java.lang.Object... moreNameValuePairs)` Apply the given name-variable mapping and return the result.
    `static void` | `checkName(java.lang.String name)` Check a name that it does not contain invalid characters.
    `static Template` | `from(java.lang.String templateText)` Create a template.
    `Countable<java.lang.String>` | `getPlaceholders()` Get the set of placeholder names which are used in this template.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### PLACEHOLDER_PREFIX

          static final java.lang.String PLACEHOLDER_PREFIX

      Prefix of a text holder mark.
      See Also:
        Constant Field Values

    - #### PLACEHOLDER_SUFFIX

          static final java.lang.String PLACEHOLDER_SUFFIX

      Suffix of a text holder mark.
      See Also:
        Constant Field Values

    - #### FALLBACK_SEPARATOR

          static final java.lang.String FALLBACK_SEPARATOR

      The separator used to include a fallback.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getPlaceholders

          @NotNull
          public Countable<java.lang.String> getPlaceholders()

      Get the set of placeholder names which are used in this template.
      Returns:
        required placeholder names, optional placeholders are not contained

    - #### from

          @NotNull
          public static Template from(@NotNull
                                               java.lang.String templateText)
                                        throws java.text.ParseException

      Create a template.
      Parameters:
        `templateText` - template text
      Returns:
        template
      Throws:
        `java.text.ParseException` - if text does contain invalid placeholder definitions

    - #### apply

          @NotNull
          public java.lang.String apply(@NotNull
                                                 Dict<java.lang.String,java.lang.String> variableMapping)

      Apply the given variable mapping and return the result.
      Parameters:
        `variableMapping` - variable mapping, has to contain a key for each name
      Returns:
        text with placeholders replaced by the values given by `variableMapping`

    - #### apply

          @NotNull
          public java.lang.String apply(@NotNull
                                                 java.util.Map<java.lang.String,java.lang.String> variableMapping)

      Apply the given variable mapping and return the result.
      Parameters:
        `variableMapping` - variable mapping, has to contain a key for each name
      Returns:
        text with placeholders replaced by the values given by `variableMapping`

    - #### apply

          @NotNull
          public java.lang.String apply(@NotNull
                                                 java.lang.String name1,
                                                 @NotNull
                                                 java.lang.Object value1,
                                                 @NotNull
                                                 java.lang.Object... moreNameValuePairs)

      Apply the given name-variable mapping and return the result.
      Parameters:
        `name1` - name of first placeholder
        `value1` - substitution value of first placeholder
        `moreNameValuePairs` - further name-value pairs, each even entry has to be a non-null string, and each following odd entry has to be something non-null, for which its string representation will be used as substitution value
      Returns:
        text with placeholders replaced

    - #### checkName

          public static void checkName(@NotNull
                                       java.lang.String name)

      Check a name that it does not contain invalid characters.
      Parameters:
        `name` - name to check
      Throws:
        `java.lang.IllegalArgumentException` - if name contains invalid characters