mustache::frame - Mustache - Data frames with fields
Welcome to the Mustache project for Tcl, written by Andreas Kupries.
It provides a set of five related Tcl packages for the parsing and rendering of mustache-style logic-less templates, plus an application for easy command-line access to the functionality.
For availability please read Mustache - How To Get The Sources.
mustache::context objects make use of data frame objects to hold the values they will hand to the mustache render command while it renders a template.
mustache::frame provides seven TclOO classes for holding scalar values of various types, sequences, and mappings, all suitable for working with the objects provided by the mustache::context package.
Note however that any command prefix supporting the Instance API below will be suitable for working with the same.
This is not necessarily true for custom context objects. Such may have their own API for working with typed values.
Converts the tagged nested data structure in spec, representing a hierarchy of mappings, sequences, and scalar values, into an equivalent hierarchy of data frame objects.
Returns the root object of the generated data frame hierarchy.
The spec has to be a 2-element list of tag and value, in this order. The accepted tags and the associated values are
The value is a boolean.
The value is a floating point number.
The value is an integer number.
The value is null/nil/missing.
The value is an arbitrary string. Internally it is mapped to string! frames.
The value is a Tcl list containing nested specs.
The value is a Tcl dictionary whose keys and values are nested specs. Note however that it is expected that keys are always tagged as scalars.
Note that the TclYAML package is able to generate this type of tagged structure.
Note further that the type-specific tags are only generated by TclYAML version 0.5 and up. Version 0.4 and before generate only the un-typed scalar tag.
Example:
mapping {
{scalar FIELD} {scalar VAL}
{scalar SEQ} {sequence {
{scalar 1}
{scalar 2}
{scalar 3}
}}
{scalar SUB} {mapping {
{scalar CHILD} {scalar X}
}}
}
These constructor commands create a new scalar data frame of the given type, initialize it using the value and return the fully qualified name of that instance.
ATTENTION Of these three, best use string! over all else.
Do not use string. While the disrecommended type is the original type for string values it is now present only to pass the mustache compatibility tests. It comes with auto-magic behaviour counter to what is expected from a string type, i.e. to pass all values as they are.
string does not do that. Any value which looks like a number it "normalizes".
The new type string! on the other hand does exactly that. No auto-magic normalization, i.e. mangling of things looking like numbers. Just passing values as they are.
These constructor commands create a new sequence data frame, initialize it using the value and return the fully qualified name of that instance.
The value has to be a list of data frame objects.
Attention: The new sequence takes over ownership of the data frames in the list, and they will be destroyed when the sequence is destroyed.
These constructor commands create a new mapping data frame, initialize it using the value and return the fully qualified name of that instance.
The value has to be a dictionary mapping arbitrary strings to data frames. The keys of the dictionary name the fields which can be found in the mapping later on, and the data frames hold the associated values.
Attention: The new mapping takes over ownership of the data frames in the dictionary, and they will be destroyed when the mapping is destroyed.
Data frames are what the context uses as containers for typed values. It should be noted that it actually does not care about the specific type of a value, only about the behaviour it supports, which can be queried (See the methods nil? and iterable?).
Returns the type of the frame.
Checks if the frame is of the specified type and returns the result as a boolean value.
Checks if the value has the named field.
Returns a boolean value indicating either success (true) or failure (false) of the search.
Note that scalars and sequences do not have fields. Searching them always fails.
Returns the data frame for the named field.
Scalars and sequences throw an error, as they do not have fields. A mapping will throw an error only if the named field is not known.
Iterates over the elements of the frame and invokes the script for each of them. During the execution of the script the active element will be pushed into the context, and popped again after.
Returns the empty string.
Scalars and mappings will throw an error, as they cannot be iterated over.
Asks the frame if it can be iterated over. In other words, if it is a non-empty sequence of values.
Returns a boolean value. true signals that the frame can be iterated over.
Scalars and mappings always return false. Sequences return false only if they are mpty.
Asks the frame if it is nil, false, empty, etc.
Returns a boolean value. true signals that the frame's value is indeed nil, empty, false, etc.
Strings are nil if they are either the empty string, or their value can be interpreted as a boolean value, and is representing false.
Numbers are never nil, nulls are always nil, and booleans are nil if they represent false.
Sequences and mappings are nil if they are empty, i.e of length or size 0.
Returns the Tcl string value of the frame. Supported by all types.
Sequences and mappings return Tcl stringifications of their list or dictionary, respectively. This will recurse through nested structures.
Returns the string representation of the data frame as per the specified type.
It is expected that the type is backed by a package named ::mustache::frame::as::<type>, exporting a command of the same name.
This command has to be suitable for use with the data frame's visit method. The as method will invoke visit with the type command to perform the actual conversion.
This method visits the data frame and its children in interleaved pre- and post-order, invoking the command prefix specified by the word... for each frame once (scalars) or twice (sequences, and mappings).
The result of the method is the result of the last invokation of the command prefix for the top data frame.
The command prefix is always called in the global scope. It is expected to support the signatures below. The frame argument is always the object command of the data frame the call is for.
Called for all scalar frames, once. The value is the Tcl value of the scalar. The type is one of the possible scalar type tags.
Called at the beginning of a sequence, enables initializations in the converter. The return value, if any, is ignored.
Called after visiting the children of a sequence. The value is a list containing the results of visiting the sequence's elements.
Called at the beginning of a mapping, enables initializations in the converter. The return value, if any, is ignored.
Called after visiting the value children of a mapping. The value is a dictionary mapping the field names to the results of visiting their frames.
Scalar data frames provide more than just the generic API. These additional methods should only be used after a type check:
Set the new scalar value into the frame. An error will be thrown if the value does not match the type of the frame. The command returns the empty string.
Validates the scalar value against the frame. An error will be thrown if the value does not match the type of the frame. The command returns the normalized value, as per the frame's type.
Mapping data frames provide more than just the generic API. These additional methods should only be used after a type check:
Extends or modifies the mapping. After the call the key maps to the value frame. A previously existing assignment for the key is destroyed. The command returns the empty string.
Removes the assignment identified by key from the mapping. The associated value frame is destroyed. The command returns the empty string.
Move the assignment of key to the newky. An error will be thrown if the key does not exist. A previously existing assignment for the newkey is destroyed. The command returns the empty string.
Both the package(s) and this documentation will undoubtedly contain bugs and other problems. Please report such at Mustache Tracker.
Please also report any ideas you may have for enhancements of either package(s) and/or documentation.
Copyright © 2019-2021 Andreas Kupries
Copyright © 2019-2021 Documentation, Andreas Kupries