1 $group
2 $
3 var sect = {
4 title: 'Implementation'
5 };
6 section( §)
7 p An artifact generator produces a buffer of text characters.
8 \b The production is driven by models contained in the
9 \b parameters passed to the generator.
10 p An artifact generator receives three parameters:
11 ittf-panel
12 ittf
13 func gen
14 { model
15 | api-ref wizzi-plugin.wizziModel
16 | POJO
17 { ctx
18 api-ref wizzi.artifact.genContext
19 callback
20 ul
21 li A model can be a Wizzi Model instance or a POJO,
22 \b and represent the main context of the artifact generation.
23 li An instance of the wizzi.artifact.genContext class that contains
24 ul
25 li An in-memory buffer where the generated text is written
26 \b sequentially using write and write line methods.
27 li A data context that may contain zero or many secondary
28 \b context models, Wizzi Models or POJO.
29 li Some helper functions for text indentation, interpolation
30 \b and error management.
31 li A callback function that a succesfull generation must call
32 \b passing, as a second parameter, an instance of the
33 \b wizzi.artifact.genContext with the text buffer containing
34 \b the generated artifact
35 p Artifact generations are write based, using the write statements
36 \b of the wizzi.artifact.genContext, or template based.
37 . doc-title-2
38 + Code generation by term rewriting
39 p The mTree loader, implemented by the wizzi-mtree.loader.loadMTree API, is
40 \b a powerfull model composer and transformer.
41 \b Model transformations can be
42 \b chained: an output mTree can become the input context for the next
43 \b mTree loading. A 'wzjob' model can orchestrate any number of cascading
44 \b transformations.
45 \b The models passed to the artifact generator are the final
46 \b models, ready for generating the textual artifact.
47 p A template based generation, that uses the mTree loader,
48 \b can be, indeed, more a code generation by term rewriting
49 \b than a textual code generation. When mTrees are loaded into Wizzi Models,
50 \b that can apply types and validations, and can programmatically modify the model,
51 \b we have a tool for efficiently enabling any extension of the target
52 \b language, easily implementing partial classes or any other modular
53 \b aspect or rewrite rule.
54 . doc-title-2
55 + Language schemas and language artifact generators
56 p Focusing on the generation of
57 \b the textual content of an artifact, we must treat of a class
58 \b of Wizzi Model types that is specific for the production
59 \b of code targeting the synthax of a programming languages (PL).
60 p A language schema defines a tree structure
61 \b that an associated language artifact generator can transform
62 \b in a targeting PL code. It can be viewd as a profile of a PL Grammar that
63 \b can be implemented partially,
64 \b with some of its symbols stereotyped. The schema developer should try
65 \b to find the optimal balance between ease of use and completeness and
66 \b define the proper approximation of the schema in respect to the PL grammar.
67 p Must be said that language schema is a concept. A language schema is
68 \b like any other wizzi schema and a language artifact is
69 \b like any other artifact generator. The production of specific tools for
70 \b creating language schemas and artifacts could be
71 \b undertaken in the future.
72 p The wizzi factory, that is generated by the wizzi factory,
73 \b uses some language schemas for its generations:
74 ul
75 li The `js` schema in the wizzi-js plugin.
76 li The `html`, `css` and `md` schemas in the wizzi-html plugin.
77 . doc-title-2
78 + Template based artifact generation
79 p Language schema Wizzi Models are template
80 \b formats for Wizzi factory template based artifact generations.
81 ittf-panel
82 title `js` ITTF Document
83 ittf
84 module
85 kind jsfile
86 class Horse
87 super Animal
88 ctor
89 param name
90 base name
91 m say
92 log 'Hiiii i am ', this.name
93 m create
94 static
95 param name
96 return
97 new Horse
98 @ name
99 p Almost every ittf node maps to a node type of the javascripts AST. And
100 \b ittf nodes can be template commands and can contain expressions.
101 . doc-title-2
102 + Example of template based implementation of
103 \b the wizzi-plugin.artifactGenerator API
104 p In this dummy example, a 'js' ITTF Document template,
105 \b named 'datalayer/adapters.js.ittf'
106 \b is transformed in the javascript textual code of a fictitious datalayer
107 \b adapter component.
108 p This example artifact generator makes use internaly of a 'js' language
109 \b artifact generator, named 'js/module'. The Wizzi Model that it receives as
110 \b first parameter, has been loaded in previous steps, and becomes
111 \b the mTreeBuilUpContext object for loading the mTree of the `js` ITTF Document template.
112 \b It must be a Wizzi Model of type 'rdbms' otherwise an error
113 \b is returned in the callback.
114 p The `js` source ITTF Document is loaded, and transformed in a textual artifact, calling
115 \b the 'loadModelAndGenerateArtifact' method of the
116 \b wizzi.WizziFactory class, exposed in the property 'wizziFactory'
117 \b of the 'ctx' parameter (an instance of the wizzi.artifact.genContext class).
118 ittf-panel
119 ittf
120 module
121 kind jsfile
122 var path = require('path')
123 var md = module.exports = {}
124 var myname = 'artifact rdbms.adapters.main';
125 set md.gen
126 function
127 { model
128 { ctx
129 callback
130 # check the model is a Wizzi Model of type 'rdbms'
131 if model.wzElement !== 'rdbms'
132 return
133 callback
134 _ctx.error
135 @ myname + " error: the model paramater should be an 'rdbms' Wizzi Model"
136 @ model
137 # build the artifact template path, it is a js ITTF Document in a sub folder
138 var ittfTemplatePath
139 _ path.join
140 @ __dirname
141 @ 'ittf'
142 @ 'datalayer'
143 @ 'adapters.js.ittf'
144 # call the wizzifactory method for loading a language Wizzi Model and
145 # generate a language artifact from it. Pass the input model in the
146 # mTreeBuildUpContext property of the request object argument.
147 # The 'js' schema of the template model is detected by its filename.
148 _ ctx.wizziFactory.loadModelAndGenerateArtifact
149 @ ittfTemplatePath
150 {
151 @ mTreeBuildUpContext model
152 @ 'js/module'
153 function
154 param err
155 param artifactText
156 if err
157 # invoke the callback on error, passing back the loadModelAndGenerateArtifact error
158 return
159 _ callback
160 err
161 # write the artifactText into the genContext buffer
162 _ ctx.write(artifactText)
163 # invoke the callback on success, passing back the genContext
164 _ callback(null, ctx)