The Wizzi Factory is a general purpose and language agnostic artifact generator.
It is model driven and regard software as a data structure that is generated processing data structures. Its inputs and outputs are printable and human readable streams of characters.
It is an open tool for the development environment, with no runtime.
Nowadays computing has advanced tremendously thank to many new open and interoperable tools and programming languages.
Computing handles data structures and is itself described by data. A program source is a human friendly representation of an Abstract Syntax Tree (AST), a data structure that represents its computations. Programming is a combination of data produced by programmers and tools.
The Wizzi Factory is a new tool for describing and composing data structures. It is aimed at those tasks, in the development process, where programming can be driven by data.
In the Wizzi Factory human friendly representations of data drive model transformations and code generations. The Wizzi Factory uses a minimal and universal text format and a template processor for composing tree data structures.
After composition, domain specific schematas can be applied to data nodes, creating dynamic models that become context objects for code generations or cascading new data compositions.
ITTF documents are the source files of the Wizzi Factory. ITTF stands for Indented Text Tree Format, a human-friendly text format for representing a tree data structure of node names and values.
1 html 2 body 3 ul 4 li 5 a The Wizzi Factory 6 href https://wizzifactory.github.io
Every line is a node consisting of a name-value pair. The name is the first string of chars of the line and is separated from the value by a space or a tab.
Child nodes are indented to their parent.
An ITTF document can include or merge others ITTF documents.
1 html 2 body 3 $include footer
The root node can be a mixer or includer.
1 ${dollar}append appbar 2 ul undefined 3 ${dollar}foreach item in menulist 4 li 5 a ${dollar}{item.name} 6 href ${dollar}{item.path}
An ITTF document is a template and can be merged and interpolated with context data.
1 ul 2 $foreach item in site.TopMenu.items 3 li 4 a ${item.label} 5 href ${item.url}
Scripts can be used to manipulate nodes.
1 div 2 $ var i = 0 3 $while i < 5 4 p Hello number ${i} 5 $ i++
1 html 2 $params title 3 head 4 title ${title} 5 body 6 header 7 h1 ${title} 8 $hook appbar 9 section 10 $hook
1 li 2 $params text, href 3 a ${text} 4 href ${href}
1 div License MIT 2 span copy Stefano Bassoli.
The template engine of the wizzi factory uses a customized subset of the ECMA-262 javascript standard, sandboxed, and tailored for ITTF processing. JsWizzi is built on the esprima parser and is run by a custom javascript engine (JsWizziRunner).
A document may have semantic and template nodes. Semantic nodes, that can contain interpolation variables, are the document data. Template nodes drive the document composition and its merging with context data and disappear in the final tree structure. The ITTF Processor is agnostic about the content of semantic nodes. It processes template nodes and interpolates semantic node names and values. The result of an ITTF process is a tree data structure of semantic nodes that must have a single root node.
The tree data structure resulting from an ITTF processing is a javascript object named `mTree`.
Documents become usefull when they target a specific domain. Domain specific schemas can be applied to the result of an ITTF processing, see Wizzi Schemas. The name of the Wizzi Schema that is applyed to an ITTF Document is said to be the type of the document. An ITTF document of type `js` is a document designed to be validated by the `js` Wizzi Schema.
Each development team may create its own document types or use those already availables, see Wizzi Plugins.
An ITTF document must have extension '.ittf' and the extension must be preceded by '.' the name of the Wizzi Schema that describes the document or by '.ittf' again if the document is not typed.
A Wizzi schema is a data definition of the nodes of a tree data structure inspired by XML Schemas. It declares element types, attributes and their relations.
It can declare element methods to perform manipulations or extractions.
A Wizzi Schema is used to generate the javascript code of a Wizzi model DOM, an object model that can load, validate, manipulate and retrieve the data of a processed ITTF Document.
A Wizzi Model DOM can contain autogenerated and user defined methods. Autogenerated methods perform validations and initializations. User methods can traverse, filter and manipulate the model data.
Each Wizzi schema generates its own Wizzi Model DOM.
A Wizzi Schema is itself described by an ITTF Document of type `wfschema`, implemented in the `wizzi-core` plugin.
1 wfschema rdbms 2 require inflect 3 e catalog 4 r table/s 5 e table 6 r column/s 7 r index/es 8 m getPluralName 9 return inflect.pluralize(this.wzName) 10 e column 11 a type 12 a caption 13 a defaultValue 14 tag default 15 e index 16 a primary 17 type boolean 18 a unique 19 type boolean 20 r column/s
The most part of artifact generators targets imperative programming languages (PLs). The Wizzi Factory apply the power of ITTF Processing to PLs also.
A language Wizzi Schema describes a tree data structure that an artifact generator can transform targeting the syntax of a PL grammar.
It can be viewd as a profile of a PL grammar that is implemented partially, with some of its symbols stereotyped.
The schema developer should try to find the optimal balance between convenience and completeness and define the proper approximation of the schema in respect to the PL grammar. The purpose of a language schema is not to map a PL grammar but to make pieces of code templeatable and computable when convenient.
The Wizzi Factory is entirely coded using the `js` Wizzi Schema implemented by the `wizzi-js` plugin.
1 module 2 kind jsfile 3 class Horse 4 super Animal 5 ctor 6 param name 7 base name 8 m say 9 log 'Hiiii i am ' + this.name 10 m create 11 static 12 param name 13 return 14 new Horse 15 @ name
A Wizzi Model is an instance of a Wizzi Model DOM that has been loaded with the tree data structure resulting from a processed ITTF Document.
Wizzi models act as context objects during ITTF document processing, model transformations and artifact generations.
Wizzi models are described in terms of elements, attributes, methods and relations. An element is a classifier and a relation is a relationship between elements.
Sometimes models require manipulations for special purposes. Model transformers can be applied to Wizzi Models every time a Wizzi Model is used as a context object.
A model trasformer is an API exported by a plugin and must respect the plugin interface. Its internal implementation is free. Usually the implementor is a javascript program that receives in input a Wizzi Model and returns a transformed model or a POJO object.
A model transformation can be declared in a Wizzi Job or executed invoking a method of the Wizzi Factory API.
An artifact generator transforms a context object, usually a Wizzi model, into a software artifact.
Software artifacts are text streams that may consist of imperative code targeting a programming language or declarative data structures (JSON, XML, YAML, … et cetera).
An artifact generator is an API exported by a plugin and must respect the plugin interface. Its implementation is free and usually the implementor is a javascript program that receives in input a Wizzi Model and returns the text of the generated artifact.
An artifact generation can be declared in a Wizzi Job or executed invoking a method of the Wizzi Factory API.
The execution of a Wizzi job is the main operation of the Wizzi Factory.
A Wizzi Job is an ITTF document that declares how to load context models, execute model transformations, generate artifacts and persist them in their destination paths.
A core Wizzi schema of the Wizzi Factory (wfJob) describes the types of a Wizzi Job declaration.
1 wfjob wizzi-docs-concepts 2 $ 3 var models_folder = path.join(__dirname, 'models'); 4 var html_folder = path.join(__dirname, 'html'); 5 var dest_folder = "c:/my/wizzi/v5/github/wizzifactory.github.io"; 6 models-base-folder ${models_folder} 7 model concepts 8 src concepts.docs.ittf 9 schema docs 10 line html 11 cwd-folder ${html_folder} 12 model-ref concepts 13 transformer docs/preprint 14 production 15 dest-folder ${dest_folder} 16 line-ref html
The Wizzi Factory is made of a few kernel modules and an ecosystem of plugins.
A plugin implements one or more Wizzi schemas and their generation components:
It must have a standard folder structure and must export the createFactoryPlugin method in its entry point.
Ittf documents represent code as a tree data structure to make source code templeatable and computable when convenient. They are normally edited by programmers but sometimeswould be usefull the translation of existing code into an ITTF document type and thenadd template nodes and scripts.
Some Wizzi schemas of the default Wizzi Factory plugins have a related wizzifier tool that translates PL code into an ITTF Document of its type.
See the Wizzifiers documentation for more details.