1 md
2 h2 Ittf document loading
3 + A textual Ittf document is loaded into an mTree object by these modules
4 \b that are run in sequence.
5 ul
6 li liner
7 li nodifier
8 li includer
9 li mixer
10 li appender
11 li evaluator
12 h2 Glossary
13 table
14 md/glo-item( $append [hook-name] )
15 span Is an ittf command that declares a node branch that
16 + must be appended to a related '$hook [hook-name]' command in
17 + a mixed mTree brick.
18 md/glo-item( $hook [hook-name] )
19 span Is an ittf command that declares an insertion point in
20 + the tree structure of a mixed mTree brick. Node branches,
21 + children of a 'mix' command, declared with the
22 + '$append [hook-name]' command can be appended to the '$hook' node.
23 md/glo-item( $include [path] )
24 span Is an ittf command that invokes the inclusion of another mTree brick.
25 + An include command cannot have children nodes, and it is simply
26 + replaced by the included brick.
27 md/glo-item( ittf document )
28 span Ittf, short for Indented Text Tree Format, is the textual notation format of an mTree.
29 + An ittf document is a syntax tree, codified in a text document,
30 + where child nodes are indented to their parent.
31 + Every line is a node consisting of a name-value pair.
32 + The name is the first string of chars of the line and is separated
33 + from the value by a space or a tab.
34 + An ittf document is a template and when loaded for building an mTree
35 + we can pass a context object to the mTree loader.
36 + All nodes are templateable and composable. Even the root node may be a command node
37 + that invokes the mixup of its container.
38 + When parsed and nodified an ittf document become an mTree brick.
39 md/glo-item( jsWizzi )
40 span JsWizzi is a subset of the ECMA-262 javascript standard used by the wizzi factory
41 + for the buildup of mTrees.
42 + It is built on the quite efficent esprima parsing infrastructure and is run
43 + by a custom, sandboxed, javascript engine. See jsWizziRunner.
44 md/glo-item( jsWizziContext )
45 span The evaluation step of an mTree loading uses three types of value contexts.
46 ul
47 li One global context.
48 li One single node structure context, where the mTree is built.
49 li One value context for each mTree brick.
50 md/glo-item( jsWizziRunner )
51 span The javascript engine of an mTree buildup. It is run for expressions interpolation,
52 + template commands evaluation and mTree final buildup.
53 md/glo-item( mix command )
54 span Is an ittf command that invokes the mixup of another mTree brick.
55 + Every node with the node-name ending with an open paren is a mix command.
56 + A mix command may have children nodes, that may declare
57 + branches to be appended to hooks in the mixed mTree brick.
58 + See the $append and $hook command nodes.
59 md/glo-item( mTree )
60 span An in-memory tree data structure of name-valued nodes that is built loading and
61 + processing an ittf document
62 md/glo-item( mTree brick )
63 span A nodified ittf document.
64 + mTree bricks are the items that compose an mTree.
65 + They can mix (or include) other bricks and be mixed (or included).
66 + The same brick can be reused in many branches of the mTree,
67 + so a brick is loaded once and always cloned.
68 md/glo-item( - included mTree brick )
69 span An mTree brick included in an including mTree brick
70 + using the command <bold>$include [path]</bold>.
71 p Both the tree structure and the value context are included.
72 + Context values declared in the included nodes are created in
73 + the scope of the includer.
74 md/glo-item( - mixed mTree brick )
75 span An mTree brick mixed in a mixing mTree brick
76 + using the command <bold>[path]([params])</bold>.
77 p The tree structure is mixed but the value context remain distinct.
78 + Context values declared in the mixed nodes are created in
79 + the scope of the mixed mTree brick and do not interfere with the mixer.
80 md/glo-item( mTree loading )
81 span The creation of an mTree from an ittf document.
82 ul Loading steps
83 li line parsing (of a source ittf document)
84 li nodification (produces one mTree brick from every source ittf document)
85 li mix-composition (recursive on mixed and included mTree bricks)
86 li include-composition (recursive on mixed and included mTree bricks)
87 li append-resolution (on the composed mTree piece)
88 li evaluation (on the mixed and appended mTree piece)
89 md/glo-item( - line parsing )
90 span The text of the ittf document is parsed into name-valued lines,
91 + eliminating comments, resolving line continuations, detecting indentation
92 + and managing chars that interfere with variable interpolation.
93 md/glo-item( - nodification )
94 span The lines parsed in the previous step are transformed in a tree
95 + structure, an mTree brick, respecting the indentation of the source.
96 + One root node only is allowed.
97 md/glo-item( - mix-composition )
98 span The mTree brick, produced by the previous step, is traversed and
99 + all the 'mix commands' encountered are recursively resolved.
100 + The result is an mTree piece composed by one or many bricks.
101 md/glo-item( - include-composition )
102 span The mTree piece, produced by the previous step, is traversed and
103 + all the '$include [path]' commands encountered are recursively resolved.
104 + The recursion manages the mix-composition of included bricks too.
105 md/glo-item( - append resolution )
106 span The mTree piece resulting from composition is traversed again and
107 + child branches (of mix commands), declared with the '$append [hook-name]'
108 + command, are moved, replacing the related '$hook [hook-name]'
109 + command of the mixed mTree brick.
110 md/glo-item( - evaluation )
111 span The last step of an mTree loading. From the mTree piece produced
112 + by the previous steps is created a jsWizzi script that evaluates
113 + the template commands of its nodes and builds the final mTree.
114 md/glo-item( mTree buildup script )
115 span The jsWizzi script that, once executed, by the
116 + jsWizziRunner, will give as result the final mTree
117 + of the source ittf document.
118 md/glo-item( mTreeBuildUpScriptCoder)
119 span A module of the wizzi.mtree package that generates the
120 + mTree build up script.
121 md/glo-item( path resolution )
122 span Include and mix command nodes declare the path of the ittf document
123 + that must be mixed or included. At first the path to match is built
124 + joining the current folder path of the calling document and the name
125 + of the callee document. If this match fails, then the 't' folder rule is applied,
126 + starting from the current folder path and going up on the folder tree.
127 + See 't' folder.
128 md/glo-item( 't' folder )
129 span Folders named 't' have special rules for the path resolution
130 + of mixed and included ittf documents. In the folder structure
131 + of a wizzi factory package, ittf documents contained in a 't' folder,
132 + can be referenced with the same rules that apply to nodejs packages
133 + in 'node_modules' folders. They are searched up on the folder tree, until the
134 + relative path of the mixin or include call is matched or the path resolution fails.