Skip to content

Latest commit

 

History

History
70 lines (54 loc) · 2.91 KB

README.md

File metadata and controls

70 lines (54 loc) · 2.91 KB
Raw

Warning

Migration and adaptation from the other repository is done.
Documentation and missing features still ongoing.

vs-templ is a simple preprocessor for XML files. It can be used statically generate new files from a template definition.
Static templates can be seen as extremely simple programs which are interpreted by this preprocessor. They consume input data also formatted as XML, and generate some output XML file. In theory, it is possible for data to be expressed in other formats (eg. JSON) as well, but at the moment this is not a supported feature.

vs-templ was first developed in the context of vs to express parametric components.
While the XML ecosystem is often reliant on XSLT as a preprocessor, this option was quickly dismissed for several reasons:

  • The rest of the vs project is based on pugixml. The only XSLT 1.0 implementation which is decently licensed is libxslt based on libxml2.
    Because of that, a trivial integration would have been quite wasteful: an additional serialization and parsing stage is needed to move the tree structure between libraries.
  • The scope of XSLT, even in its very first version is too wide & its syntax just verbose. This is mostly a result of xpath being too powerful of a tool.
  • At some point vs will come with dynamic native components, and the idea is for them to match in syntax and behaviour the extended tags introduced by this preprocessor. A custom implementation is the only way to ensure a seamless integration between the two.

Hence, vs vendors its own XSLT-ish preprocessor. Still, nothing about its semantics or syntax is directly tied to vs. For this reason it is distributed as a separate package, hoping it can reach a wider adoption.

Examples

Simple for cycle

<items>
    <item prop-a="Value 1">Text A</item>
    <item prop-a="Value 2">Text B</item>
    <item prop-a="Value 3">Text C</item>
</items>

and

<ul>
<s:for in="$/items/" sort-by="$~prop-a" order-by="desc">
    <s:item>
        <li><s:value src="$~prop-a"/>: <s:value src="$~!txt"/></li>
    </s:item>
</s:for>
</ul>

results in

<ul>
    <li>Value 3: Text C</li>
    <li>Value 2: Text B</li>
    <li>Value 1: Text A</li>
</ul>

Usage

The functionality of this template builder is exposed as a library which can be used for static or dynamic linking.
A self-contained CLI utility is also provided as a frontend.

As a library

If you want to integrate vs-templ in your own application or contribute to its development, this is where to start.

Via its CLI

vs.tmpl <template-file> <data-file> [namespace=`s:`]

There is also an alternative format:

vs.tmpl [namespace=`s:`]

Syntax

Details about the supported syntax are covered in a dedicated page