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 which 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 just have to take care to enclose it in a letter which is not contained in combination with a directly following closing brace. So above example could also contain email addresses without problems. The substitution test extent over multiple lines.

  For nicer optics there are a few markers which 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

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