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 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 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' 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 expessions. The '$params' 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'.