Template

Description

sealed class Tinman.Core.Formatting.Template

A very simplistic text-based template engine.

To use the template engine, do the following steps:

  1. Write a template, which must be a text file. For this, define three tokens that will not interfere with the semantic of the text file format. These tokens will be used to mark template blocks and placeholders for values. The default tokens are:

    • '// BEGIN:'
      Marks the beginning of a new template block (see BlockBegin), if the whitespace-trimmed line of the template text starts with this token.

    • '// END:'
      Marks the end of the current template block (see BlockEnd), if the whitespace-trimmed line of the template text starts with this token.

    • '$#$'
      Format pattern for placeholder values (see BlockValue).

    Template blocks may be nested.

  2. Create an instance of Template.

  3. Configure the tokens (or use the default ones).

  4. Call Initialize to start template processing.

  5. Use Begin, End, Is, Rewind, RewindBegin, Skip, SkipRewind and SkipRewindBegin methods to iterate through the tree structure of the template blocks, using in-order traversal.

  6. Use Value during traversal to specify block values.

  7. Call End after processing all template blocks, to finish template processing.

  8. Use Write to write the output file or object.ToString to get the output text.

  9. To re-use the Template object for another processing cycle, jump to step 3.

Public / Constructors

File

public static method File → (2)

input in : Path

[not-null]
The input file that contains the template text.

encoding opt : CharacterEncoding = null

The encoding to use for reading input in. If null, CharacterEncoding.UTF_8 will be used.

returns → Template

The Template object for input in.

Creates a Template instance for the given template file.

IOException

If an I/O error has occurred.

Template

public constructor Template → (1)

text in : Text

[not-null]
The template text.

Creates a new instance of Template.

Public / Methods

Begin

public method Begin → (1)

name in : string

[not-empty]
The name of the template block. Block names must not contain whitespace characters.

returns → Template

this

Moves to the next template block.

In the template text, the block begin token must be followed by a block declaration, which specifies the block name and its values, for example:

// BEGIN: my-block(a,b,c)

This will declare the block named 'my-block', having three values 'a', 'b' and 'c'. All values must be specified via Value. Any content on the same line that follows the block declaration is ignored.

ValidatingException

If the template is malformed.

See also

Template.End
Template.Rewind
Template.RewindBegin
Template.Skip

End

public method End → ()

Finishes the current template block.

In the template text, the block end token must be followed by the block name:

// END: my-block

This will end the current block, which must be named 'my-block'. Any content on the same line that follows the block name is ignored.

ValidatingException

If the template is malformed.

See also

Template.Begin

Initialize

public method Initialize → ()

Initializes template processing.

The current values of BlockBegin, BlockEnd and BlockValue will be used for processing the template, subsequent changes will not be taken into account until template processing is initialized again.

An implicit block is created that contains the whole template and does not have any block values. This implicit block must be ended by calling End after all template blocks have been processed.

Is

[Pure]
public method Is → (1)

name in : string

The block name to check.

returns → bool

true if the inner-most block has the given name in,
false if it has a different name or if there is no block.

Checks if the inner-most block has the given name in.

Rewind

public method Rewind → ()

returns → string

The current block name.

Finishes the current template block and rewinds it.

Begin must be called next, passing the current block name, in order to continue template processing.

ValidatingException

If the template is malformed.

See also

Template.Begin

Rewind​Begin

public method RewindBegin → ()

Finishes the current template block and rewinds it, leaving template processing in the state as if Begin had just been called.

ValidatingException

If the template is malformed.

See also

Template.Begin

Skip

public method Skip → ()

Cancels the current template block by skipping all remaining content.

ValidatingException

If the template is malformed.

See also

Template.Begin

Skip​Rewind

public method SkipRewind → ()

returns → string

The current block name.

Cancels the current template block by skipping all remaining content and rewinds it.

Begin must be called next, passing the current block name, in order to continue template processing.

ValidatingException

If the template is malformed.

See also

Template.Begin

Skip​Rewind​Begin

public method SkipRewindBegin → ()

Cancels the current template block by skipping all remaining content and rewinds it, leaving template processing in the state as if Begin had just been called.

ValidatingException

If the template is malformed.

See also

Template.Begin

Value

public method Value → (3)

name in : string

[not-empty]
The block value placeholder.

value in : string

[not-null]
The block value content, which will be escaped with ValueEscape or escape opt.

escape opt : StringEscape = null

The escaping rules to use for value in, instead of ValueEscape.

returns → Template

this

Specifies content for a block value placeholder.

Each template block has its own set of block values. Within a block, values defined in an ancestor block may be referenced.

ValidatingException

If the template is malformed.

Write

public method Write → (2)

output in : Path

[not-null]
The output file to write the generated text to.

encoding opt : CharacterEncoding = null

The encoding to use for writing output in. If null, CharacterEncoding.UTF_8 will be used.

Writes the output file.

IOException

If an I/O error has occurred.

Public / Attributes

Block​Begin

public attribute BlockBegin → (get,set)

value : string

[not-empty]
The block begin line token.

The line token to use for the beginning of a new template block.

The default value is: '// BEGIN:'

Block​End

public attribute BlockEnd → (get,set)

value : string

[not-empty]
The block end line token.

The line token to use for the end of the current template block.

The default value is: '// END:'

Block​Value

public attribute BlockValue → (get,set)

value : string

[not-empty]
The block value name pattern.

The format pattern that will be used to generate placeholder names for block values.

The default value is: '$#$'

See also

Format.One

Value​Escape

public attribute ValueEscape → (get,set)

value : StringEscape

The escaping rules or null.

Optional escaping rules to use for Value.

Defaults to null.