[ Home | Main Table Of Contents | Table Of Contents | Keyword Index ]

NAME

mustache::frame - Mustache - Data frames with fields

Table Of Contents
Synopsis
Description
Overview
Class API
Instance API
Scalar Instance API
Mapping Instance API
Bugs, Ideas, Feedback
Keywords
Copyright

SYNOPSIS

package require mustache::frame

DESCRIPTION

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.

Overview

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.

Class API

::mustache frame fromTags spec

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
- bool
  
  The value is a boolean.
- float
  
  The value is a floating point number.
- int
  
  The value is an integer number.
- null
  
  The value is null/nil/missing.
- scalar
- string
  
  The value is an arbitrary string. Internally it is mapped to string! frames.
- sequence
  
  The value is a Tcl list containing nested specs.
- mapping
  
  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}
	}}
}
```
::mustache frame bool create obj value
::mustache frame bool new value
::mustache frame float create obj value
::mustache frame float new value
::mustache frame int create obj value
::mustache frame int new value
::mustache frame null create obj ?value?
::mustache frame null new ?value?
::mustache frame scalar create obj value
::mustache frame scalar new value
::mustache frame string create obj value
::mustache frame string new value
::mustache frame string! create obj value
::mustache frame string! new value

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.
::mustache frame sequence create obj value
::mustache frame sequence new value

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.
::mustache frame mapping create obj value
::mustache frame mapping new value

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.

Instance API

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?).

frameCmd type

Returns the type of the frame.
frameCmd is type

Checks if the frame is of the specified type and returns the result as a boolean value.
frameCmd has? field

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.
frameCmd field field

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.
frameCmd iter context script

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.
frameCmd iterable?

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.
frameCmd nil?

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.
frameCmd value

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.
frameCmd as type

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.
frameCmd visit ?word...?

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.
- {*}word... type frame value
  
  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.
- {*}word... sequence start frame
  
  Called at the beginning of a sequence, enables initializations in the converter. The return value, if any, is ignored.
- {*}word... sequence exit frame value
  
  Called after visiting the children of a sequence. The value is a list containing the results of visiting the sequence's elements.
- {*}word... mapping start frame
  
  Called at the beginning of a mapping, enables initializations in the converter. The return value, if any, is ignored.
- {*}word... mapping exit frame value
  
  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 Instance API

Scalar data frames provide more than just the generic API. These additional methods should only be used after a type check:

scalarCmd set value

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.
scalarCmd validate value

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 Instance API

Mapping data frames provide more than just the generic API. These additional methods should only be used after a type check:

mappingCmd set key value

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.
mappingCmd unset key

Removes the assignment identified by key from the mapping. The associated value frame is destroyed. The command returns the empty string.
mappingCmd rename key newkey

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.

Bugs, Ideas, Feedback

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.

KEYWORDS

data frame, logic-less templates, mustache, templating, typed value, value

Mustache