Ittf, Indented Text Tree Format, is a document type for declaring a textual representation of a tree structure of name-valued nodes.

Ittf documents are building blocks, made to be loaded and composed into a javascript tree structure, named mTree.

A single ittf document, when loaded, becomes an mTreeBrick, a composition element that can include or mix other mTreeBricks and can in turn be included or mixed.

Ittf documents also can be templates or pieces of templates. They can contain conditional or repeat template node commands and can use context objects, passed to the mTree load function, for creating new nodes of the composed mTree.

Further ittf documents may be seen as code units. They can codify statements and expressions using a sandboxed subset of the ECMA-262 javascript standard named 'jsWizzi'. Statements can create, and modify, variables (in the evaluation context of an mTreeBrick or in the global evaluation context) that template node commands can use to select or create nodes.

Documents are made of text lines separated by a:

• x'000a' char or
• x'000d' char or
• x'000a' \b x'000d' couple of chars

A line is made of a node-name and a node-value separated by a white-char (space or tab).

                    
   1 name value
   2   name value
                    

Node-values always are trimmed, you cannot have a node-value that starts or ends with a white-char sequence.

When loaded, both these nodes will containg the 'value' string in the node-value.

                    
   1 name1 value
   2   name2 value
                    

The node hierarchy is built calculating the indentation of node-names in a text line. Every tab or every 4 space chars preeceding a node-name count for one level of indentation.

The node-name of the first line (the root node-name) must have indentation zero. The root node-name must start at column 1 (1-based) of the first row.

An ittf document cannot have more than one root node. If the semantic of a document require more than one root node, a convenience '$group' node command can be used. It must be the root node of a composed document (included or mixed) and is ignored during the mTree build up, so that all its childs become root nodes of the included document.

Example. Ittf document with two root nodes.

                    
   1 $group
   2   root1 value1
   3   root2 value2
                    

A line becomes a node which parent is the first preceeding line with a lesser indentation.

Phisical text lines may have line continuatios and a 'logical' line may contain many phisical lines. There are three pre-defined node-names that allow line continuation:

• '\' means that the node-value is joined to the node-value of the parent node without separation.
• '\b' means that the node-value is joined to the node-value of the parent node with one space char separator.
• '\n' means that the node-value is joined to the node-value of the parent node with one Line Feed char separator.

                    
   1 - root
   2   - name1 I am
   3     - a single
   4     - line
   5   - name2 I am a single line
                    

Node names and values are text strings by design, and never require quotes (they are unquoted by the lexer). The wizzi factory is a text manipulator. If the semantic of a node-value require that it is treated as a different type (boolean, integer, float or date), that can be done using wizzi schemas, that apply types to the tree structure resulting from loading an ittf document (see mTrees).

One exception to this rule is when an argument is passed to a mixed ittf document, and will become part of its evaluation context. Types different from string can be usefull in jswizzi statements and expessions. The '$params' node command, that declares the parameters received by a mixed ittf document, may assign a type to passed arguments.

In any case the lexer do not detect types. When needed they must be declared.

Content model

XML differentiates two types: elements containing only element content (no character data) and mixed content (elements that may contain character data, optionally interspersed with child elements).

Ittf documents have no mixed content. They have ittf nodes only. They do not have the concept of element or attribute or text.

Only the application of a wizzi schema to an mTree, when loading a Wizzi Model, can trasform an ittf node in an element or attribute or text, depending on the schema declarations.

Document types and document type definitions

A wizzi schema is actually a documemnt type definition, but it applies to loaded mTrees not to ittf documents. Ittf documents creators must design their documents to obtain a valid mTree after composition and evaluation, just before loading it in a Wizzi Model.

An ittf document, when created for composing an mTree for a specific wizzi schema, can be considered to have the type of that wizzi schema. The type of an ittf document must be recognizable from its name, that must end with '.`schema`.ittf'. Example of ittf document of type 'js': 'index.js.ittf'.

Markup declaration and markup model

In XML a markup declaration is a syntactical construct within a DTD declaring an entity or defining a markup structure.

Wizzi schemas do not need to declare entities, because ittf document can contain expressions and template commands. But, like DTDs, they declare an elements and attributes structure, and like DTDs they define a model (Wizzi Model) of an mTree content.

In the wizzi factory, Wizzi Models are implemented as javascript module, generated from a wizzi schema declaration. They can load valid mTrees, and may be used as a context object by the mTree loader, model transformers and artifact generators.

Elements and element types

Wizzi schema elements and XML DTD element types have the same goal. Wizzi model elements are such only after the mTree loading of an ittf document. In ittf documents we have potential model elements, attributes and texts.

Valid characters

Ittf documents accept any character. The wizzi factory ignores the content of documents and has no concept of data type. Wizzi schemas only can constrain node names and values.

When generating the javascript of a Wizzi Model the names of classes and attributes are checked and invalid chars for javascript names are replaced with the '_' char. Class names colliding with javascript keywords are prefixed with the letter 'x'.

An ittf document, when loaded, becomes a javascript object called `mTreeBrick`.

mTreeBricks are composition units. They can mix, or include, other bricks and can be mixed, or included. The mix or include operation is declared on a node of the mixer or includer brick, that will be replaced from the nodes of the mixed or included one.

An mTree loading begins loading a primary ittf document, that become the primary mTreeBrick, the starting point of the composition. Included and mixed ittf documents become composed mTreeBricks.

A single mTreeBrick can be composed many times in different positions of the builded mTree. It is loaded once, and cloned for composition.

Include and mix operations have a different behaviour. When included, cloned mTreeBricks, become part of the includer brick and their nodes acquire its brick key and its brick evaluation context. Instead, mixed mTreeBricks, are inserted in the node structure of the mixer, but each of them mantains its original brick key and brick evaluation context. When coding an ittf document, that will become a mixed mTreeBrick, created variables will have a scope limited to the nodes declared in the document, even if they will be merged in the mixer brick.

Summarizing: primary and fragment mTreeBricks have their own evaluation context, included mTreeBricks use the evaluation context of their includer.

In case of a mixed mTreeBrick the mixer node can have children nodes that in turn can replace 'hook' nodes of the mixed brick. See the '$hook' and '$append' ittf command nodes for the composition rules of a mix operation.

Ittf main documents and fragments are composable templates, and their nodes can contain template node commands and jswizzi expressions, that will be processed in the evaluation step of the mTree loading.

The buildup of the resulting mTree can create new nodes using repeat node commands like '$foreach', '$backeach' and '$while' and can include or exclude node branches using '$if', '$elif' and '$else' conditional node commands.

jswizzi statements and expression are executed in the fragment evaluation context and may access global context variables.

$foreach repeat node command

                    
   1 - ...
   2   - $foreach item-name in collection-name
   3     - ... node branch ...
                    

Descendant nodes of this node command are a repeat template; item-name is user defined and collection-name is a jswizzi expression that evaluates to an iterable javascript object, in scope in the local or global jsWizziContext.

The var statement that declares item-name is auto-generated.

Descendant nodes are repeated having item-name as a value in scope.

$while repeat node command

This is a repeat template statement where descendant nodes are repeated until the jswizzi-expression evaluates to false.

$ or $global node commands must be used to modify the context values of the exit condition. There is a limit of 10000 iterations to guard against accidental loops, after that an exception is raised.

TODO make the limit of 10000 iterations configurable and an optional parameter of the loadMTree function.

                    
   1 - ...
   2   - $while jswizzi-expression
   3     - ... node branch ...
   4     - $ jswizzi-exit-condition-change
                    

$break, $continue repeat node commands

This statements have the same meaning than in javascript but operate breaking or continuing the template repetition.

A label for continuation is not implemented.

                    
   1 - ...
   2   - $foreach ... | $while ...
   3     - $break empty-value
   4     - ...
   5     - $continue empty-value