Wizzi is a general purpose artifact generator for apps components (mobile, web, desktop) and documents (html, pdf, word, presentation, ecc..).
In Wizzi a software artifact is a data structure that can be generated processing data structures. Its inputs are tree data structures ( mTrees ) in a textual format ( ITTF documents ).
It is a tool for the development environment, with no runtime.
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. Programs are data produced by programmers and tools.
Wizzi is a tool for composing data structures. It aims at those tasks, in the development process, where programming can be driven by data.
In Wizzi, human friendly representations of data drive artifact generations. Wizzi uses a simple indented text format and a template processor for composing tree data structures.
Domain specific schemas ( Wizzi Schemas ) can be applied to the composed nodes, creating typed objects used as contexts in artifact generations or in new data compositions.
1 html 2 body 3 ul 4 li 5 a The Wizzi Factory 6 href https://stfnbssl.github.io/wizzi
ITTF stands for Indented Text Tree Format, a human-friendly text format for representing a tree data structure of node names and values.
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.
ITTF Document files can include or mix others ITTF Document files, thereon an ITTF Document may consist of one main document and many fragment documents.
Mixed fragments can receive parameters and my have hook nodes where to append child nodes of the merger document.
1 html 2 body 3 $include footer
The root node can be a mix node.
1 layout( Welcome to my site ) 2 $append appbar 3 ul 4 $foreach item in menulist 5 li 6 a ${item.name} 7 href ${item.path} 8 . wrapper 9 . content
1 html 2 head 3 body 4 header 5 $hook appbar 6 section 7 $hook
1 li 2 $params text, href 3 a ${text} 4 href ${href}
Included fragments are inserted as is and cannot receive parameters.
1 div License MIT 2 span copy Stefano Bassoli.
An ITTF document must have extension '.ittf' and the extension must be preceded by '.' plus the name of the Wizzi Schema that typifies the document. For eample `index.js.ittf`.
An ITTF Document is a scripteable template and can be merged and interpolated with context data.
1 ... 2 ul 3 $foreach item in site.TopMenu.items 4 li 5 a ${item.label} 6 href ${item.url}
Nodes whose name is a template command are called template nodes. Any other node is said a semantic node and must be defined by an element or attribute of a Wizzi Schema.
JsWizzi is the script engine used for templating ITTF Documents.
Scripts can be used to manipulate node structure and to interpolate node names and values.
1 ... 2 div 3 $ var i = 0 4 $while i < 5 5 p Hello number ${i} 6 $ i++
JsWizzi is a customized subset of the ECMA-262 javascript standard, sandboxed, and tailored for ITTF processing. It is built on the babel parser and is run by a custom javascript engine (
JsWizziRunner
).
The ITTF Processor executes the template nodes and interpolates the semantic node names and values of an ITTF Document. The result of an ITTF Process is a tree data structure of semantic nodes only, that must have a single root node, and is loaded in a javascript object named `mTree`.
A Wizzi Schema apply a type to an mTree. It is a definition of a tree data structure inspired by XML Schemas. It declares element types, attributes and relations between elements.
It can declare element methods to perform data manipulations or extractions.
From each Wizzi Schema can be generated its own Wizzi Model DOM (see below).
A Wizzi Schema is itself described by an ITTF Document of type `wfschema`, implemented in the `wizzi-core` 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
From schemas Wizzi can generate javascript code that loads, validates, manipulates and retrieves the data of an mTree.
Instances of Wizzi Model DOMS, called Wizzi Model instances (see below), can be passed to ITTF Processors, model transformers and artifact generators as context objects.
A generated Wizzi Model DOM is a javascript module that can contain autogenerated and user defined methods. Autogenerated methods perform loading and validation. User defined methods can traverse, filter and manipulate data.
Artifact generators in most cases target imperative programming languages (PLs).
A Language Wizzi Schema describes an ITTF Document that an artifact generator can transform in a PL code file.
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 Wizzi Language Schema is not to map a PL grammar but to make pieces of code templeatable and interpolable when convenient.
Wizzi is entirely coded using the `js` Language Wizzi Schema implemented by the `wizzi-js` core 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 instance is an instance of a Wizzi Model DOM that has been loaded with the mTree (tree data structure) of a processed ITTF Document.
Wizzi Model instances act as context objects during ITTF document processing, model transformations and artifact generations.
Wizzi Models are described by Wizzi Schemas in terms of elements, attributes, methods and relations. An element is a classifier and a relation is a relationship between elements.
Model transformations can be applied to Wizzi Model instances before using them as context objects.
A model trasformer is an API exported by a plugin and must respect the Wizzi Plugin interface. Its internal implementation is free. Usually the implementor is a javascript program that receives a Wizzi Model instance, and optionally one or more context objects, as input, and returns a transformed model or a new POJO object.
A model transformation can be declared in a Wizzi Job or executed invoking a method of the Wizzi API.
An artifact generation transforms one or more context objects, usually Wizzi Model instances or JSON documents, into a software artifact.
An artifact generator is an API exported by a plugin and must respect the Wizzi Plugin interface. Its implementation is free and usually the implementor is a javascript program that receives in input context objects 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 API.
The execution of a Wizzi Job is the main operation of the Wizzi software 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.
The core Wizzi Schema '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
Wizzi is made of a few kernel modules and an ecosystem of plugins.
A plugin implements one or more Wizzi Schema and their generation components:
A Wizzi Plugin must have a standard folder structure and must export the createFactoryPlugin method in its entry point. See Wizzi Plugins
All the operations of the Wizzi Factory can be executed programmaticaly instantiating a WizziFactory object and executing its methods.
The Wizzi command line interface (CLI) is used to perform basic functionality, such as executing a Wizzi Production, creating a new Wizzi Package based on a starter, wizzifying an existing artifact or a folder of artifacts.
The Wizzi CLI is available via npm and should be installed globally.
The store system of Wizzi is virtualized. When instantiating a
WizziFactory
instance you can select the Store Kind. Virtual Store Systems are implemented by the wizzi-repo
core package. Available store kinds are:
filesystem
(default),
mongodb
and
json
.