diff --git a/latest/docs/dist/website/doxygen/latex/vs-templ_8hpp__dep__incl.pdf b/latest/docs/dist/website/doxygen/latex/vs-templ_8hpp__dep__incl.pdf
index bb8689a..a284683 100644
Binary files a/latest/docs/dist/website/doxygen/latex/vs-templ_8hpp__dep__incl.pdf and b/latest/docs/dist/website/doxygen/latex/vs-templ_8hpp__dep__incl.pdf differ
diff --git a/latest/docs/dist/website/doxygen/latex/vs-templ_8hpp__incl.pdf b/latest/docs/dist/website/doxygen/latex/vs-templ_8hpp__incl.pdf
index 0c97848..b6938f3 100644
Binary files a/latest/docs/dist/website/doxygen/latex/vs-templ_8hpp__incl.pdf and b/latest/docs/dist/website/doxygen/latex/vs-templ_8hpp__incl.pdf differ
diff --git a/latest/docs/index.html b/latest/docs/index.html
index ca8df13..bac13f5 100644
--- a/latest/docs/index.html
+++ b/latest/docs/index.html
@@ -164,5 +164,5 @@
 
 <!--
 MkDocs version : 1.6.1
-Build Date UTC : 2025-01-08 21:36:24.970817+00:00
+Build Date UTC : 2025-01-08 21:42:26.706968+00:00
 -->
diff --git a/latest/docs/releases/v0.3.15/index.html b/latest/docs/releases/v0.3.15/index.html
index 70e8358..63ce27f 100644
--- a/latest/docs/releases/v0.3.15/index.html
+++ b/latest/docs/releases/v0.3.15/index.html
@@ -109,7 +109,7 @@ <h2 id="v0315">v0.3.15<a class="headerlink" href="#v0315" title="Permanent link"
 <p>All done! The last <code>for</code> and <code>for-props</code> prop based commands have been completed.<br />
 With this development of functionality for <code>vs.templ</code> is done.</p>
 <p>There are minor features planned for the <code>v0.4.x</code> branch, but most will be documentation, better examples, formal XML schemas and testing infrastructure.<br />
-Once that is done we are going straight to <code>v.1</code> if there are no architectural problems being discovered in the meanwhile.</p>
+Once that is done we are going straight to <code>v1</code> if there are no architectural problems being discovered in the meanwhile.</p>
               
             </div>
           </div><footer>
diff --git a/latest/docs/search/search_index.json b/latest/docs/search/search_index.json
index 0ec0fe2..c72b4b6 100644
--- a/latest/docs/search/search_index.json
+++ b/latest/docs/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Warning Some features are still missing, and are tracked on the repo . Documentation is an ongoing effort, so you will not find everything well described. Contributions to make them better are very welcome. vs-templ is a simple preprocessor for XML files. It can be used to statically generate new files from a template definition and a data source. Static templates can be seen as extremely simple programs serialized in XML which are interpreted by this preprocessor. They consume input data (also XML) to generated output XML.","title":"Home"},{"location":"faq/","text":"Why not XSLT? # vs-templ was first developed in the context of vs to express static, yet parametric, components. While the XML ecosystem is often reliant on XSLT as a preprocessor, this option was quickly dismissed in the parent project for several reasons: The rest of the vs is based on pugixml . The only lightweight 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 was excessive & 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 vs.templ its own XSLT-ish preprocessor. Still, nothing about its semantics or syntax is directly tied to vs , so I am distributing it as a separate package, hoping it can reach a wider adoption. Why not handlebars or mustache # That class of templating solutions cannot understand XML. As such, the resulting generation can be unsound. Is there a SAX implementation? # No, there is not. Some features don\u2019t strictly require a DOM, but they don\u2019t really translate well in terms of a pull parser. The memory peak usage would not be much better either for many reasonable templates, so there is no real incentive to implement this preprocessor based on a different backend for now. Still, if you want to do so you are very welcome! Can we support other input formats for the dataset? # In theory, it would be possible for data to be expressed in other formats (eg. JSON) as well, but at the moment this is not a supported feature and is not likely going to be in scope for quite a while. However, a native integration of SQLite to use it as data-source is almost surely going to happen at some point.","title":"FAQ"},{"location":"faq/#why-not-xslt","text":"vs-templ was first developed in the context of vs to express static, yet parametric, components. While the XML ecosystem is often reliant on XSLT as a preprocessor, this option was quickly dismissed in the parent project for several reasons: The rest of the vs is based on pugixml . The only lightweight 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 was excessive & 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 vs.templ its own XSLT-ish preprocessor. Still, nothing about its semantics or syntax is directly tied to vs , so I am distributing it as a separate package, hoping it can reach a wider adoption.","title":"Why not XSLT?"},{"location":"faq/#why-not-handlebars-or-mustache","text":"That class of templating solutions cannot understand XML. As such, the resulting generation can be unsound.","title":"Why not handlebars or mustache"},{"location":"faq/#is-there-a-sax-implementation","text":"No, there is not. Some features don\u2019t strictly require a DOM, but they don\u2019t really translate well in terms of a pull parser. The memory peak usage would not be much better either for many reasonable templates, so there is no real incentive to implement this preprocessor based on a different backend for now. Still, if you want to do so you are very welcome!","title":"Is there a SAX implementation?"},{"location":"faq/#can-we-support-other-input-formats-for-the-dataset","text":"In theory, it would be possible for data to be expressed in other formats (eg. JSON) as well, but at the moment this is not a supported feature and is not likely going to be in scope for quite a while. However, a native integration of SQLite to use it as data-source is almost surely going to happen at some point.","title":"Can we support other input formats for the dataset?"},{"location":"for-developers/","text":"Building # A modern C++ toolchain supporting C++20 meson as the build system of choice pandoc (optional) if you want to generate the documentation/man pages gperf (optional) if you want to regenerate the command dispatchers not in use right now, when frozen will be removed this is its replacement. valgrind (optional) to run some tests To build, test and install it you can just use normal meson commands like. meson setup build meson compile -C build meson install -C build Embedding it # At this time, this repository is only available as a meson package. I might consider adding cmake later on to gain a wider compatibility. If pugixml is already provided as a dependency in the main project, that will be used. vs.templ requires you implement some features downstream to support all features. If not provided, the library will still be usable, but the command tags include and data will not work as expected. The CLI in src/app shows everything that is needed to use vs.templ as a library. C bindings # At this time, no C bindings are provided since all my downstream project don\u2019t need them, and pugixml is C++ only. Still, the public interface is quite thin, so they can be easily introduced if so desired. Versioning # Releases are tagged on the repo, with master as the main development branch. Semantic versioning will be followed after v1.0.0 . Before that, any release can and will have breaking changes. Versions ending with an odd revision number are meant for proper for releases, while even numbers are only for in-dev stages.","title":"Information for developers"},{"location":"for-developers/#building","text":"A modern C++ toolchain supporting C++20 meson as the build system of choice pandoc (optional) if you want to generate the documentation/man pages gperf (optional) if you want to regenerate the command dispatchers not in use right now, when frozen will be removed this is its replacement. valgrind (optional) to run some tests To build, test and install it you can just use normal meson commands like. meson setup build meson compile -C build meson install -C build","title":"Building"},{"location":"for-developers/#embedding-it","text":"At this time, this repository is only available as a meson package. I might consider adding cmake later on to gain a wider compatibility. If pugixml is already provided as a dependency in the main project, that will be used. vs.templ requires you implement some features downstream to support all features. If not provided, the library will still be usable, but the command tags include and data will not work as expected. The CLI in src/app shows everything that is needed to use vs.templ as a library.","title":"Embedding it"},{"location":"for-developers/#c-bindings","text":"At this time, no C bindings are provided since all my downstream project don\u2019t need them, and pugixml is C++ only. Still, the public interface is quite thin, so they can be easily introduced if so desired.","title":"C bindings"},{"location":"for-developers/#versioning","text":"Releases are tagged on the repo, with master as the main development branch. Semantic versioning will be followed after v1.0.0 . Before that, any release can and will have breaking changes. Versions ending with an odd revision number are meant for proper for releases, while even numbers are only for in-dev stages.","title":"Versioning"},{"location":"manual/","text":"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. CLI # vs.tmpl <template-file> <data-file> [namespace=`s:`] Unlike its usage in vs.fltk, template must be specified on its own, as it cannot be inferred. There is also an alternative format: vs.tmpl [namespace=`s:`] with both files added via pipes, like vs.tmpl <(cat template.xml) <(cat data.xml) Syntax quick reference # vs.templ uses special elements and attributes to determine the actions to be performed by the preprocessor. They are scoped under the namespace s , or any custom defined one. This man page only covers a quick syntax reference. If you are looking for the full specs, please check the official repository . TODO: write cheat sheet of syntax here.","title":"User Manual"},{"location":"manual/#cli","text":"vs.tmpl <template-file> <data-file> [namespace=`s:`] Unlike its usage in vs.fltk, template must be specified on its own, as it cannot be inferred. There is also an alternative format: vs.tmpl [namespace=`s:`] with both files added via pipes, like vs.tmpl <(cat template.xml) <(cat data.xml)","title":"CLI"},{"location":"manual/#syntax-quick-reference","text":"vs.templ uses special elements and attributes to determine the actions to be performed by the preprocessor. They are scoped under the namespace s , or any custom defined one. This man page only covers a quick syntax reference. If you are looking for the full specs, please check the official repository . TODO: write cheat sheet of syntax here.","title":"Syntax quick reference"},{"location":"repl-vm/","text":"Tentative specs for higher order expressions to add some degree of freedom in calculations. They are still interpreted as expression, starting with : . The content of the expression represent the serialization of a program in reverse polish notation (RPN). The VM is going to run it, and the only element left on stack is taken as the final expression value. For example, assuming the environment had i set to 1 : : `{i}` `#name-` cat:*` will return an expression of type string embedding the value name-1 . Type casting must generally be explicit, but some operators might have automatic casting to simplify code. The delimiters are needed, since some types of expressions like strings can contain spaces and other escaping characters. The character | should never be used as it interfere with the serialization of tuples used by vs.templ . Escaping sequences are defined for ` and | as well. Design # Why RPN? # Several reasons: to avoid a complex parser for what will end up being a quite marginal feature it avoids the arbitrary precedence rules usually associated with algebraic operator to be fast and easy to compile into native code if so desired (but for now a vm is all we need) Possible extensions # I will probably allow braces as NOP operators, just as syntax sugar to improve readability. At some point they could get validated in LSP, so that potential bugs are highlit. Options for implementation # Assumption: these programs are very short. As such their source is not read in streaming, but it is all resident in memory while compiling. This allows the usage of string_views and the buffer itself in place of allocating too many temporary objects in memory. Hence, processing these expressions should be very memory efficient. Add the vm to this repo directly. Build a generic vm library for which specific instances can be generated downstream of a schema. This way it is easier to build different backends and integrate fast dispatching via perfect minimal hashing functions. Find a library already implementing this design and use that. no success in that Operators # Array operators # count [expr] # , count the dimensionality of expression returning a 1-dimensional scalar number reduce [initial] [reducer] [container] V , reduces to a 1-dimensional object each element of the container starting from the initial expression (sum, join etc) filter [container] F , filters elements out of a container map [expr] [container] M , maps container based on a lambda Generic # dup duplicate the last element on stack nop no operation rem remove last n elements from stack swap swap the two top elements eval (probably I will not expose this one) expose a nested repl vm load load variable on stack from the environment map store (probably I will not expose this one) store variable form stack to the environment map log to log errors/warning etc somewhere String operators # cat [container] cat , simplified version of V where based on the type, the 0 is used as initial and the reducer is the natural + operation join to join together strings on the stack with the first string. rcat like cat but in reverse order rjoin like join but in reverse order esc escape number to string literal Boolean operators # Boolean types are not directly supported. They are just integers with extra semantic. if [false] [true] [condition] ? and or not as expected (they are bitwise) xor nor nand as expected (they are bitwise). true false to load those values in stack. Comparison operators # eq neq bg bge lt lte for integers & floats For strings we have at least three criteria, which is making these operations harder to handle Typical comparison based on lexicographic comparison Dot comparison, introduced by vs to handle nesting Natural comparison, where for example $20<100$ Common algebraic operators # And all the typical math operations as usual + - * / mod (and mnemonic versions too) pow log count.0 & count.1 Cast # as.str as.int as.float Special # PIPE and APOS to escape | and ``` respectively ( & ) as nop just to enable formatting in expression (not enforced, but the LSP might check) rem to tag the prior tag as comment (remove the last element from stack)","title":"Computing expressions"},{"location":"repl-vm/#design","text":"","title":"Design"},{"location":"repl-vm/#why-rpn","text":"Several reasons: to avoid a complex parser for what will end up being a quite marginal feature it avoids the arbitrary precedence rules usually associated with algebraic operator to be fast and easy to compile into native code if so desired (but for now a vm is all we need)","title":"Why RPN?"},{"location":"repl-vm/#possible-extensions","text":"I will probably allow braces as NOP operators, just as syntax sugar to improve readability. At some point they could get validated in LSP, so that potential bugs are highlit.","title":"Possible extensions"},{"location":"repl-vm/#options-for-implementation","text":"Assumption: these programs are very short. As such their source is not read in streaming, but it is all resident in memory while compiling. This allows the usage of string_views and the buffer itself in place of allocating too many temporary objects in memory. Hence, processing these expressions should be very memory efficient. Add the vm to this repo directly. Build a generic vm library for which specific instances can be generated downstream of a schema. This way it is easier to build different backends and integrate fast dispatching via perfect minimal hashing functions. Find a library already implementing this design and use that. no success in that","title":"Options for implementation"},{"location":"repl-vm/#operators","text":"","title":"Operators"},{"location":"repl-vm/#array-operators","text":"count [expr] # , count the dimensionality of expression returning a 1-dimensional scalar number reduce [initial] [reducer] [container] V , reduces to a 1-dimensional object each element of the container starting from the initial expression (sum, join etc) filter [container] F , filters elements out of a container map [expr] [container] M , maps container based on a lambda","title":"Array operators"},{"location":"repl-vm/#generic","text":"dup duplicate the last element on stack nop no operation rem remove last n elements from stack swap swap the two top elements eval (probably I will not expose this one) expose a nested repl vm load load variable on stack from the environment map store (probably I will not expose this one) store variable form stack to the environment map log to log errors/warning etc somewhere","title":"Generic"},{"location":"repl-vm/#string-operators","text":"cat [container] cat , simplified version of V where based on the type, the 0 is used as initial and the reducer is the natural + operation join to join together strings on the stack with the first string. rcat like cat but in reverse order rjoin like join but in reverse order esc escape number to string literal","title":"String operators"},{"location":"repl-vm/#boolean-operators","text":"Boolean types are not directly supported. They are just integers with extra semantic. if [false] [true] [condition] ? and or not as expected (they are bitwise) xor nor nand as expected (they are bitwise). true false to load those values in stack.","title":"Boolean operators"},{"location":"repl-vm/#comparison-operators","text":"eq neq bg bge lt lte for integers & floats For strings we have at least three criteria, which is making these operations harder to handle Typical comparison based on lexicographic comparison Dot comparison, introduced by vs to handle nesting Natural comparison, where for example $20<100$","title":"Comparison operators"},{"location":"repl-vm/#common-algebraic-operators","text":"And all the typical math operations as usual + - * / mod (and mnemonic versions too) pow log count.0 & count.1","title":"Common algebraic operators"},{"location":"repl-vm/#cast","text":"as.str as.int as.float","title":"Cast"},{"location":"repl-vm/#special","text":"PIPE and APOS to escape | and ``` respectively ( & ) as nop just to enable formatting in expression (not enforced, but the LSP might check) rem to tag the prior tag as comment (remove the last element from stack)","title":"Special"},{"location":"syntax/","text":"Warning This documentation reflects the expected functionality for v0.5.0. Some features are still missing, progress is tracked in the repository and on the todo file in root. vs.templ uses special elements and attributes to define which actions the preprocessor should perform. These XML entities are scoped under the namespace s by default, but the user can set up a custom one as well. Please, notice that pugixml on which vs.templ is based does not have a full understanding of XML and namespaces are not covered. As such, they only operate as fancy prefixes at this scale. Expressions # Several of the attributes introduced by vs.templ accept expressions and not just simple literal values. Expression can are used to access elements and attributes of the data XML, in addition to represent native types like integers or strings. Their definition and usage is purposefully restricted to prevent arbitrary code to be run. A full list of feasible expression types: Empty expression, generally representing errors String, automatically assigned from expressions starting with # (the prefix # is skipped and not part of the final string) Integers (base 10), automatically assigned from expressions starting with a digit, + , - or . Floating point numbers, like integers but always ending with f Paths, of which three forms exists: those starting with $ . This special symbol is used to mark the nearest recorded node from the data XML being visited, or root if none. Paths with arbitrary prefix {var-name} where var-name is searched for and resolved from the symbols\u2019 stack. They can only appear as the first token. Absolute paths starting from the root, with prefix / . Path expressions will continue with one or more tokens / -terminated representing the tag name being visited. If terminated with ~prop-name the relevant attribute is selected. There are also two special meta-properties which can be accessed this way: Special access to the property ~!txt to get the node text. Special access to the element\u2019s name via ~!tag Finally, there are stack meta-expressions, starting with : . Those are run by a stack VM and can be sparingly used to perform more complex tasks. They return a single expression in one of the other real types. The full specifications of these meta-expressions can be found here . For most scenarios, only a minor subset is going to be useful, like some basic integer maths, comparisons and cat to merge strings. No further combination or format is allowed in expression. Else, their parsing will fail. However, the preprocessor should not generally throw exceptions, only emit error or warning logs. Examples # Using the following XML file as reference: <hello> <world attribute-a=\"value-0\"> text-0 </world> <!-- The second one will never be visited with paths like /hello/world/--> <world attribute-a=\"value-1\"> text-1 </world> </hello> /hello/world/ is the list of children for the first world element in hello /hello/world~attribute-a is evaluated as value-0 /hello/world~!txt is evaluated as text-0 Assuming a for cycle in /hello/ , its children will be navigated and $~attribute-a will be resolved in value-0 and value-1 . Operators for elements # Element operators or tag operators are special elements either acting on their children or they use them as default value in case of failure. There are several to control flow or add content to the final document. value # To introduce the result of a (meta) expression in the tree. Integers and floats are automatically serialized before adding them to the page. strings are just appended. attributes are interpreted as strings. nodes are added as subtree. value accepts an expression src as argument, by default set to $ . If the expression fails, its body will be used instead. Examples # <s:value src=\":...\">This fails, so this text will be used</s:value> <s:value src=\": `1` `2` +\">Since the operation is ok and returns `3` as integer, this text will not show up</s:value> element # This command is usedto generate a new element whose type is by an expression passed via the attribute s:type (this one is specifically namespaced). Any other property and child will be preserved. In case of failure, the tag is dropped. Examples # <s:element s:type=\"#tag-name\" prop-1=\"Hello\">Content</s:element> <s:element s:type=\":\" prop-1=\"Hello\">This will not be shown as the expression is not valid</s:element> for-range # tag is the name of the symbol where the current value will be stored. If empty the default $ is used. from starting value. to final value. step step of increment. It can be negative. If so to<from must hold true. Infinite cycles are detected before execution, in which case no step will run. Unlike other for variants, there is no header, footer or empty child. Anything inside a for-range is interpreted as item . Example # <s:for-range tag=\"i\" from=\"0\" to=\"10\" step=\"1\"> <s:for-range tag=\"j\" from=\"0\" to=\": `{i}`\" step=\"1\"> <s:value src=\": `{j}` `{i}` mul\" /> </s:for-range> </s:for-range> for & for-props # To iterate over children and props of an element respectively. Aside from that, they mostly share the same interface. tag : the name of the symbol hosting the current XML node pointer. If empty, its default is $ in : must be specified and is a path expression filter : as an expression in the internal custom language . sort-by : (only available for for ) list of | separated path expressions. Elements will be sorted giving priority from left to right order-by : order preference for each field in the sort-by or the only one implicit for for-props . Each entry is a pair type:comparator with type either ASC , DESC or RANDOM . If not provided, comparator is assumed to be the default one. As an alternative comparator we could have a one using . to separate values in tokens, and order them token by token. limit : maximum number of entries to be iterated. If 0 all of them will be considered, if positive that or the maximum number, if negative all but that number if possible o no content. offset : offset from start (of the filtered and ordered list of children) Both for & for-props support the following list of children. You can use as many instances of the same type as you want, they will be applied to the final document in the order they appear. header : shown at the top of a non-empty container footer : shown at the bottom of a non-empty container empty : shown if a container is empty item : the main body error : shown if it was not possible to retrieve items (because of an error in the path for example; in case of empty lists empty is used) The symbol [tag].c gets loaded with the entry number we are iterating over, so that it is possible to count which one we are at. For for-props there are also [tag].k and [tag].v for key and value of the prop. [tag] by default is $ . test & case # To perform conditional cut and paste in the final tree based on simple matches between a reference expression and some values. Inside the body of test we have one or more case . Attributes for case : continue default is false . If true it continues checking and executing even after a match. Else it will break. when an expression to compare against. The order of case elements is important and determines the overall flow. log # Optional argument type set to: notify when something should be logged, but there is no fault or suspicious behaviour ongoing. ok for tasks completed successfully error when a condition prevents this activity from succeeding, but the situation is recoverable warning when something can complete, but it is suspicious. panic when an error triggered, and the situation cannot be recovered Panic does not mean exceptions. For example, the evaluation of an expression might panic, but this problem is not propagated. It just means that there is no way to recover it, and downstream code will have to live with its failure. Error means that there is a capability recognized when it was raised for the system to rectify this issue. For example the inclusion of a file which does not exist can adopt the content of the include tag as fallback. include # Important The full behaviour of this function is determined by downstream integration. Add in place the file defined in src . If not found, it uses the content inside include . External files will have their root removed when included. File loading for a single include instance appearing in code is only done once, even if in a cycle. Later requests will show the same content as before. src is just a static string, not an expression. This is because the evaluation of the file must be statically resolved. The functionality of include is not provided by vs.templ and requires downstream integration. As such is no caching provided by vs.templ ; if you need that, you will have to implement it as part of the load function passed to the preprocessor constructor. Similarly, circular dependencies are not tested. It is up to you to use a load function which ensures they will not occur. The CLI shipping with this library has a very limited implementation which will load files as XML with normal fs paths. Examples # <s:include src=\"component.xml\"> <h1>Placeholder title</h1> <p>This will be used if the import fails. Leave empty if not needed</p> </s:include> data # Important The full behaviour of this function is determined by downstream integration. This command loads a data source in memory, and exposes it via a tag name. Any property which is not src and tag will be exposed to the supplier function for parametrization. Data retrieval is not part of vs.templ , so it is up to the downstream implementation to handle it as desired. The CLI shipping with the library will not handle complex features like filtering, sorting etc. The src passed is just being used as a regular fs path. Operators for properties # xxx are used as tags to identify groups under which multiple attributes should be used. for.SUB-ATTR.xxx & for-props.SUB-ATTR.xxx # As prop, attribute variants of for and for-props . They add attributes/values to the node they are defined within. value.xxx # As for the element version, to introduce the value of an expression as value of a prop xxx . prop.xxx # To generate new property whose name and value are determined by the pair passed as value. Examples # <tag s:prop.0=\"#hello|#world\" s:prop.1=\"#hallo|#Welt\"/> when # To test if the current element should be shown, if and only if the expression is true .","title":"Full Syntax reference"},{"location":"syntax/#expressions","text":"Several of the attributes introduced by vs.templ accept expressions and not just simple literal values. Expression can are used to access elements and attributes of the data XML, in addition to represent native types like integers or strings. Their definition and usage is purposefully restricted to prevent arbitrary code to be run. A full list of feasible expression types: Empty expression, generally representing errors String, automatically assigned from expressions starting with # (the prefix # is skipped and not part of the final string) Integers (base 10), automatically assigned from expressions starting with a digit, + , - or . Floating point numbers, like integers but always ending with f Paths, of which three forms exists: those starting with $ . This special symbol is used to mark the nearest recorded node from the data XML being visited, or root if none. Paths with arbitrary prefix {var-name} where var-name is searched for and resolved from the symbols\u2019 stack. They can only appear as the first token. Absolute paths starting from the root, with prefix / . Path expressions will continue with one or more tokens / -terminated representing the tag name being visited. If terminated with ~prop-name the relevant attribute is selected. There are also two special meta-properties which can be accessed this way: Special access to the property ~!txt to get the node text. Special access to the element\u2019s name via ~!tag Finally, there are stack meta-expressions, starting with : . Those are run by a stack VM and can be sparingly used to perform more complex tasks. They return a single expression in one of the other real types. The full specifications of these meta-expressions can be found here . For most scenarios, only a minor subset is going to be useful, like some basic integer maths, comparisons and cat to merge strings. No further combination or format is allowed in expression. Else, their parsing will fail. However, the preprocessor should not generally throw exceptions, only emit error or warning logs.","title":"Expressions"},{"location":"syntax/#examples","text":"Using the following XML file as reference: <hello> <world attribute-a=\"value-0\"> text-0 </world> <!-- The second one will never be visited with paths like /hello/world/--> <world attribute-a=\"value-1\"> text-1 </world> </hello> /hello/world/ is the list of children for the first world element in hello /hello/world~attribute-a is evaluated as value-0 /hello/world~!txt is evaluated as text-0 Assuming a for cycle in /hello/ , its children will be navigated and $~attribute-a will be resolved in value-0 and value-1 .","title":"Examples"},{"location":"syntax/#operators-for-elements","text":"Element operators or tag operators are special elements either acting on their children or they use them as default value in case of failure. There are several to control flow or add content to the final document.","title":"Operators for elements"},{"location":"syntax/#value","text":"To introduce the result of a (meta) expression in the tree. Integers and floats are automatically serialized before adding them to the page. strings are just appended. attributes are interpreted as strings. nodes are added as subtree. value accepts an expression src as argument, by default set to $ . If the expression fails, its body will be used instead.","title":"value"},{"location":"syntax/#examples_1","text":"<s:value src=\":...\">This fails, so this text will be used</s:value> <s:value src=\": `1` `2` +\">Since the operation is ok and returns `3` as integer, this text will not show up</s:value>","title":"Examples"},{"location":"syntax/#element","text":"This command is usedto generate a new element whose type is by an expression passed via the attribute s:type (this one is specifically namespaced). Any other property and child will be preserved. In case of failure, the tag is dropped.","title":"element"},{"location":"syntax/#examples_2","text":"<s:element s:type=\"#tag-name\" prop-1=\"Hello\">Content</s:element> <s:element s:type=\":\" prop-1=\"Hello\">This will not be shown as the expression is not valid</s:element>","title":"Examples"},{"location":"syntax/#for-range","text":"tag is the name of the symbol where the current value will be stored. If empty the default $ is used. from starting value. to final value. step step of increment. It can be negative. If so to<from must hold true. Infinite cycles are detected before execution, in which case no step will run. Unlike other for variants, there is no header, footer or empty child. Anything inside a for-range is interpreted as item .","title":"for-range"},{"location":"syntax/#example","text":"<s:for-range tag=\"i\" from=\"0\" to=\"10\" step=\"1\"> <s:for-range tag=\"j\" from=\"0\" to=\": `{i}`\" step=\"1\"> <s:value src=\": `{j}` `{i}` mul\" /> </s:for-range> </s:for-range>","title":"Example"},{"location":"syntax/#for-for-props","text":"To iterate over children and props of an element respectively. Aside from that, they mostly share the same interface. tag : the name of the symbol hosting the current XML node pointer. If empty, its default is $ in : must be specified and is a path expression filter : as an expression in the internal custom language . sort-by : (only available for for ) list of | separated path expressions. Elements will be sorted giving priority from left to right order-by : order preference for each field in the sort-by or the only one implicit for for-props . Each entry is a pair type:comparator with type either ASC , DESC or RANDOM . If not provided, comparator is assumed to be the default one. As an alternative comparator we could have a one using . to separate values in tokens, and order them token by token. limit : maximum number of entries to be iterated. If 0 all of them will be considered, if positive that or the maximum number, if negative all but that number if possible o no content. offset : offset from start (of the filtered and ordered list of children) Both for & for-props support the following list of children. You can use as many instances of the same type as you want, they will be applied to the final document in the order they appear. header : shown at the top of a non-empty container footer : shown at the bottom of a non-empty container empty : shown if a container is empty item : the main body error : shown if it was not possible to retrieve items (because of an error in the path for example; in case of empty lists empty is used) The symbol [tag].c gets loaded with the entry number we are iterating over, so that it is possible to count which one we are at. For for-props there are also [tag].k and [tag].v for key and value of the prop. [tag] by default is $ .","title":"for &amp; for-props"},{"location":"syntax/#test-case","text":"To perform conditional cut and paste in the final tree based on simple matches between a reference expression and some values. Inside the body of test we have one or more case . Attributes for case : continue default is false . If true it continues checking and executing even after a match. Else it will break. when an expression to compare against. The order of case elements is important and determines the overall flow.","title":"test &amp; case"},{"location":"syntax/#log","text":"Optional argument type set to: notify when something should be logged, but there is no fault or suspicious behaviour ongoing. ok for tasks completed successfully error when a condition prevents this activity from succeeding, but the situation is recoverable warning when something can complete, but it is suspicious. panic when an error triggered, and the situation cannot be recovered Panic does not mean exceptions. For example, the evaluation of an expression might panic, but this problem is not propagated. It just means that there is no way to recover it, and downstream code will have to live with its failure. Error means that there is a capability recognized when it was raised for the system to rectify this issue. For example the inclusion of a file which does not exist can adopt the content of the include tag as fallback.","title":"log"},{"location":"syntax/#include","text":"Important The full behaviour of this function is determined by downstream integration. Add in place the file defined in src . If not found, it uses the content inside include . External files will have their root removed when included. File loading for a single include instance appearing in code is only done once, even if in a cycle. Later requests will show the same content as before. src is just a static string, not an expression. This is because the evaluation of the file must be statically resolved. The functionality of include is not provided by vs.templ and requires downstream integration. As such is no caching provided by vs.templ ; if you need that, you will have to implement it as part of the load function passed to the preprocessor constructor. Similarly, circular dependencies are not tested. It is up to you to use a load function which ensures they will not occur. The CLI shipping with this library has a very limited implementation which will load files as XML with normal fs paths.","title":"include"},{"location":"syntax/#examples_3","text":"<s:include src=\"component.xml\"> <h1>Placeholder title</h1> <p>This will be used if the import fails. Leave empty if not needed</p> </s:include>","title":"Examples"},{"location":"syntax/#data","text":"Important The full behaviour of this function is determined by downstream integration. This command loads a data source in memory, and exposes it via a tag name. Any property which is not src and tag will be exposed to the supplier function for parametrization. Data retrieval is not part of vs.templ , so it is up to the downstream implementation to handle it as desired. The CLI shipping with the library will not handle complex features like filtering, sorting etc. The src passed is just being used as a regular fs path.","title":"data"},{"location":"syntax/#operators-for-properties","text":"xxx are used as tags to identify groups under which multiple attributes should be used.","title":"Operators for properties"},{"location":"syntax/#forsub-attrxxx-for-propssub-attrxxx","text":"As prop, attribute variants of for and for-props . They add attributes/values to the node they are defined within.","title":"for.SUB-ATTR.xxx &amp; for-props.SUB-ATTR.xxx"},{"location":"syntax/#valuexxx","text":"As for the element version, to introduce the value of an expression as value of a prop xxx .","title":"value.xxx"},{"location":"syntax/#propxxx","text":"To generate new property whose name and value are determined by the pair passed as value.","title":"prop.xxx"},{"location":"syntax/#examples_4","text":"<tag s:prop.0=\"#hello|#world\" s:prop.1=\"#hallo|#Welt\"/>","title":"Examples"},{"location":"syntax/#when","text":"To test if the current element should be shown, if and only if the expression is true .","title":"when"},{"location":"releases/v0.3.11/","text":"v0.3.11 # There has been much more progress than anticipated, and most features needed to reach v0.4.1 have been filled in already. This release is to make sure vs can properly use the newly supported syntax in its code and examples. Subsequent milestones have been rescheduled, and next new branch v0.4.x will be mostly for consolidation, documentation and to incrementally improve the quality of code. As such, I am splitting this release here, leaving the two leftover commands for v0.3.13 . New features # Introduced include to load more template files. Please, notice that checks to avoid circular dependencies are to be performed externally. All the remaining prop-based commands. value prop for for-prop Loading the environment of a preprocessor is now possible via load_env . Improved handling of some expressions making them less verbose. Better (and colourful) logging! Bug fixing # Fixed several broken maths operations like * . Breaking changes # The interface of preprocessor was changed once again to support the XML loader function. Minimal changes are expected downstream, based on your prior usage.","title":"V0.3.11"},{"location":"releases/v0.3.11/#v0311","text":"There has been much more progress than anticipated, and most features needed to reach v0.4.1 have been filled in already. This release is to make sure vs can properly use the newly supported syntax in its code and examples. Subsequent milestones have been rescheduled, and next new branch v0.4.x will be mostly for consolidation, documentation and to incrementally improve the quality of code. As such, I am splitting this release here, leaving the two leftover commands for v0.3.13 .","title":"v0.3.11"},{"location":"releases/v0.3.11/#new-features","text":"Introduced include to load more template files. Please, notice that checks to avoid circular dependencies are to be performed externally. All the remaining prop-based commands. value prop for for-prop Loading the environment of a preprocessor is now possible via load_env . Improved handling of some expressions making them less verbose. Better (and colourful) logging!","title":"New features"},{"location":"releases/v0.3.11/#bug-fixing","text":"Fixed several broken maths operations like * .","title":"Bug fixing"},{"location":"releases/v0.3.11/#breaking-changes","text":"The interface of preprocessor was changed once again to support the XML loader function. Minimal changes are expected downstream, based on your prior usage.","title":"Breaking changes"},{"location":"releases/v0.3.13/","text":"v0.3.13 # A new intermediate release before moving to v0.4.x . Surprisingly, whatever was originally scheduled for v0.3.13 has been delayed again, and other features took the spot! So, yeah, the attribute version of for-props and for are yet to come (at least they are covered in the examples). The revised plan is for the two missing commands to be in v0.3.15 , and then we move straight to the new minor. At that point the development here will slow down as all core features made their way in the codebase. I will be resuming work on vs.fltk . New features # data command has been added to introduce external data sources in the template. random order support in order-by for for loops. Stable random ordering depending on a seed number. Examples! LOTS OF EXAMPLEEES! And improved tests. We now have the most blazingly fast web server based on vs.templ (according to source myself)! Bug fixes # test/case fixed to match the intended specs. Fixed behaviour of for-prop tag command to ensure good symbols are provided in the loop scope. Fixed handling of floating point numbers in expressions. Breaking changes # Reverted and fixed src in for cycles to in as it initially was. Changed the preprocessor interface to introduce the new loadfn (the name has been recycled from before, the older loadfn is now includefn )","title":"V0.3.13"},{"location":"releases/v0.3.13/#v0313","text":"A new intermediate release before moving to v0.4.x . Surprisingly, whatever was originally scheduled for v0.3.13 has been delayed again, and other features took the spot! So, yeah, the attribute version of for-props and for are yet to come (at least they are covered in the examples). The revised plan is for the two missing commands to be in v0.3.15 , and then we move straight to the new minor. At that point the development here will slow down as all core features made their way in the codebase. I will be resuming work on vs.fltk .","title":"v0.3.13"},{"location":"releases/v0.3.13/#new-features","text":"data command has been added to introduce external data sources in the template. random order support in order-by for for loops. Stable random ordering depending on a seed number. Examples! LOTS OF EXAMPLEEES! And improved tests. We now have the most blazingly fast web server based on vs.templ (according to source myself)!","title":"New features"},{"location":"releases/v0.3.13/#bug-fixes","text":"test/case fixed to match the intended specs. Fixed behaviour of for-prop tag command to ensure good symbols are provided in the loop scope. Fixed handling of floating point numbers in expressions.","title":"Bug fixes"},{"location":"releases/v0.3.13/#breaking-changes","text":"Reverted and fixed src in for cycles to in as it initially was. Changed the preprocessor interface to introduce the new loadfn (the name has been recycled from before, the older loadfn is now includefn )","title":"Breaking changes"},{"location":"releases/v0.3.15/","text":"v0.3.15 # All done! The last for and for-props prop based commands have been completed. With this development of functionality for vs.templ is done. There are minor features planned for the v0.4.x branch, but most will be documentation, better examples, formal XML schemas and testing infrastructure. Once that is done we are going straight to v.1 if there are no architectural problems being discovered in the meanwhile.","title":"V0.3.15"},{"location":"releases/v0.3.15/#v0315","text":"All done! The last for and for-props prop based commands have been completed. With this development of functionality for vs.templ is done. There are minor features planned for the v0.4.x branch, but most will be documentation, better examples, formal XML schemas and testing infrastructure. Once that is done we are going straight to v.1 if there are no architectural problems being discovered in the meanwhile.","title":"v0.3.15"},{"location":"releases/v0.3.5/","text":"v0.3.5 # Technical release, only for the sake of fully testing workflows. At least feature parity with what it was its split from vs-fltk . Some degree of documentation. Add support for element.text() & element.name() in query. Replace the current split implementation with something requiring less allocations man page generation via meson (not great, but I\u2019ll take it). Initial setup for the test-suite. Add actual support of dot comparison in strings (to be tested). Functional CLI needed. Install scripts working (testing needed).","title":"V0.3.5"},{"location":"releases/v0.3.5/#v035","text":"Technical release, only for the sake of fully testing workflows. At least feature parity with what it was its split from vs-fltk . Some degree of documentation. Add support for element.text() & element.name() in query. Replace the current split implementation with something requiring less allocations man page generation via meson (not great, but I\u2019ll take it). Initial setup for the test-suite. Add actual support of dot comparison in strings (to be tested). Functional CLI needed. Install scripts working (testing needed).","title":"v0.3.5"},{"location":"releases/v0.3.7/","text":"v0.3.7 # This release brings many new features which further expand the capabilities of vs.templ : Introduced a more robust logging infrastructure at all levels. Now errors and warnings are better logged. Introduced log tag Introduced meta-expressions with their RPN virtual machine to support more complex evaluations. A good number of operators have been implemented so far, with most of the architectural bits ironed out. Introduced filter for loops now that we have meta-expressions. A significantly improved documentation. Initial work to support prop-based commands. The in attribute for cycles has been removed in favour of src to make it more consistent. No further breaking change is expected from v0.3.5 for templates, but the public interface itself has. You might need to slightly refactor current code, and provide an explicit logging function. Next release is expected to be the very last for v0.3.x.","title":"V0.3.7"},{"location":"releases/v0.3.7/#v037","text":"This release brings many new features which further expand the capabilities of vs.templ : Introduced a more robust logging infrastructure at all levels. Now errors and warnings are better logged. Introduced log tag Introduced meta-expressions with their RPN virtual machine to support more complex evaluations. A good number of operators have been implemented so far, with most of the architectural bits ironed out. Introduced filter for loops now that we have meta-expressions. A significantly improved documentation. Initial work to support prop-based commands. The in attribute for cycles has been removed in favour of src to make it more consistent. No further breaking change is expected from v0.3.5 for templates, but the public interface itself has. You might need to slightly refactor current code, and provide an explicit logging function. Next release is expected to be the very last for v0.3.x.","title":"v0.3.7"},{"location":"releases/v0.3.9/","text":"v0.3.9 # Just a quick corrective version over v0.3.7 to fix the behaviour of several untested features, like the newly added filters of for loops. This release also introduces few more meta-expression operators to allow escaping, and a realistic example emitting HTML to complement the rest of the docs. New features # when as a prop command for the conditional rendering of the owner. Breaking changes # sort-by and order-by will now use | in place , to split multiple options. when / is fully replaced. The older syntax was dreadful but necessary without the RPN virtual machine, but now that we have\u2026 say hello to test / case .","title":"V0.3.9"},{"location":"releases/v0.3.9/#v039","text":"Just a quick corrective version over v0.3.7 to fix the behaviour of several untested features, like the newly added filters of for loops. This release also introduces few more meta-expression operators to allow escaping, and a realistic example emitting HTML to complement the rest of the docs.","title":"v0.3.9"},{"location":"releases/v0.3.9/#new-features","text":"when as a prop command for the conditional rendering of the owner.","title":"New features"},{"location":"releases/v0.3.9/#breaking-changes","text":"sort-by and order-by will now use | in place , to split multiple options. when / is fully replaced. The older syntax was dreadful but necessary without the RPN virtual machine, but now that we have\u2026 say hello to test / case .","title":"Breaking changes"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Warning Some features are still missing, and are tracked on the repo . Documentation is an ongoing effort, so you will not find everything well described. Contributions to make them better are very welcome. vs-templ is a simple preprocessor for XML files. It can be used to statically generate new files from a template definition and a data source. Static templates can be seen as extremely simple programs serialized in XML which are interpreted by this preprocessor. They consume input data (also XML) to generated output XML.","title":"Home"},{"location":"faq/","text":"Why not XSLT? # vs-templ was first developed in the context of vs to express static, yet parametric, components. While the XML ecosystem is often reliant on XSLT as a preprocessor, this option was quickly dismissed in the parent project for several reasons: The rest of the vs is based on pugixml . The only lightweight 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 was excessive & 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 vs.templ its own XSLT-ish preprocessor. Still, nothing about its semantics or syntax is directly tied to vs , so I am distributing it as a separate package, hoping it can reach a wider adoption. Why not handlebars or mustache # That class of templating solutions cannot understand XML. As such, the resulting generation can be unsound. Is there a SAX implementation? # No, there is not. Some features don\u2019t strictly require a DOM, but they don\u2019t really translate well in terms of a pull parser. The memory peak usage would not be much better either for many reasonable templates, so there is no real incentive to implement this preprocessor based on a different backend for now. Still, if you want to do so you are very welcome! Can we support other input formats for the dataset? # In theory, it would be possible for data to be expressed in other formats (eg. JSON) as well, but at the moment this is not a supported feature and is not likely going to be in scope for quite a while. However, a native integration of SQLite to use it as data-source is almost surely going to happen at some point.","title":"FAQ"},{"location":"faq/#why-not-xslt","text":"vs-templ was first developed in the context of vs to express static, yet parametric, components. While the XML ecosystem is often reliant on XSLT as a preprocessor, this option was quickly dismissed in the parent project for several reasons: The rest of the vs is based on pugixml . The only lightweight 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 was excessive & 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 vs.templ its own XSLT-ish preprocessor. Still, nothing about its semantics or syntax is directly tied to vs , so I am distributing it as a separate package, hoping it can reach a wider adoption.","title":"Why not XSLT?"},{"location":"faq/#why-not-handlebars-or-mustache","text":"That class of templating solutions cannot understand XML. As such, the resulting generation can be unsound.","title":"Why not handlebars or mustache"},{"location":"faq/#is-there-a-sax-implementation","text":"No, there is not. Some features don\u2019t strictly require a DOM, but they don\u2019t really translate well in terms of a pull parser. The memory peak usage would not be much better either for many reasonable templates, so there is no real incentive to implement this preprocessor based on a different backend for now. Still, if you want to do so you are very welcome!","title":"Is there a SAX implementation?"},{"location":"faq/#can-we-support-other-input-formats-for-the-dataset","text":"In theory, it would be possible for data to be expressed in other formats (eg. JSON) as well, but at the moment this is not a supported feature and is not likely going to be in scope for quite a while. However, a native integration of SQLite to use it as data-source is almost surely going to happen at some point.","title":"Can we support other input formats for the dataset?"},{"location":"for-developers/","text":"Building # A modern C++ toolchain supporting C++20 meson as the build system of choice pandoc (optional) if you want to generate the documentation/man pages gperf (optional) if you want to regenerate the command dispatchers not in use right now, when frozen will be removed this is its replacement. valgrind (optional) to run some tests To build, test and install it you can just use normal meson commands like. meson setup build meson compile -C build meson install -C build Embedding it # At this time, this repository is only available as a meson package. I might consider adding cmake later on to gain a wider compatibility. If pugixml is already provided as a dependency in the main project, that will be used. vs.templ requires you implement some features downstream to support all features. If not provided, the library will still be usable, but the command tags include and data will not work as expected. The CLI in src/app shows everything that is needed to use vs.templ as a library. C bindings # At this time, no C bindings are provided since all my downstream project don\u2019t need them, and pugixml is C++ only. Still, the public interface is quite thin, so they can be easily introduced if so desired. Versioning # Releases are tagged on the repo, with master as the main development branch. Semantic versioning will be followed after v1.0.0 . Before that, any release can and will have breaking changes. Versions ending with an odd revision number are meant for proper for releases, while even numbers are only for in-dev stages.","title":"Information for developers"},{"location":"for-developers/#building","text":"A modern C++ toolchain supporting C++20 meson as the build system of choice pandoc (optional) if you want to generate the documentation/man pages gperf (optional) if you want to regenerate the command dispatchers not in use right now, when frozen will be removed this is its replacement. valgrind (optional) to run some tests To build, test and install it you can just use normal meson commands like. meson setup build meson compile -C build meson install -C build","title":"Building"},{"location":"for-developers/#embedding-it","text":"At this time, this repository is only available as a meson package. I might consider adding cmake later on to gain a wider compatibility. If pugixml is already provided as a dependency in the main project, that will be used. vs.templ requires you implement some features downstream to support all features. If not provided, the library will still be usable, but the command tags include and data will not work as expected. The CLI in src/app shows everything that is needed to use vs.templ as a library.","title":"Embedding it"},{"location":"for-developers/#c-bindings","text":"At this time, no C bindings are provided since all my downstream project don\u2019t need them, and pugixml is C++ only. Still, the public interface is quite thin, so they can be easily introduced if so desired.","title":"C bindings"},{"location":"for-developers/#versioning","text":"Releases are tagged on the repo, with master as the main development branch. Semantic versioning will be followed after v1.0.0 . Before that, any release can and will have breaking changes. Versions ending with an odd revision number are meant for proper for releases, while even numbers are only for in-dev stages.","title":"Versioning"},{"location":"manual/","text":"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. CLI # vs.tmpl <template-file> <data-file> [namespace=`s:`] Unlike its usage in vs.fltk, template must be specified on its own, as it cannot be inferred. There is also an alternative format: vs.tmpl [namespace=`s:`] with both files added via pipes, like vs.tmpl <(cat template.xml) <(cat data.xml) Syntax quick reference # vs.templ uses special elements and attributes to determine the actions to be performed by the preprocessor. They are scoped under the namespace s , or any custom defined one. This man page only covers a quick syntax reference. If you are looking for the full specs, please check the official repository . TODO: write cheat sheet of syntax here.","title":"User Manual"},{"location":"manual/#cli","text":"vs.tmpl <template-file> <data-file> [namespace=`s:`] Unlike its usage in vs.fltk, template must be specified on its own, as it cannot be inferred. There is also an alternative format: vs.tmpl [namespace=`s:`] with both files added via pipes, like vs.tmpl <(cat template.xml) <(cat data.xml)","title":"CLI"},{"location":"manual/#syntax-quick-reference","text":"vs.templ uses special elements and attributes to determine the actions to be performed by the preprocessor. They are scoped under the namespace s , or any custom defined one. This man page only covers a quick syntax reference. If you are looking for the full specs, please check the official repository . TODO: write cheat sheet of syntax here.","title":"Syntax quick reference"},{"location":"repl-vm/","text":"Tentative specs for higher order expressions to add some degree of freedom in calculations. They are still interpreted as expression, starting with : . The content of the expression represent the serialization of a program in reverse polish notation (RPN). The VM is going to run it, and the only element left on stack is taken as the final expression value. For example, assuming the environment had i set to 1 : : `{i}` `#name-` cat:*` will return an expression of type string embedding the value name-1 . Type casting must generally be explicit, but some operators might have automatic casting to simplify code. The delimiters are needed, since some types of expressions like strings can contain spaces and other escaping characters. The character | should never be used as it interfere with the serialization of tuples used by vs.templ . Escaping sequences are defined for ` and | as well. Design # Why RPN? # Several reasons: to avoid a complex parser for what will end up being a quite marginal feature it avoids the arbitrary precedence rules usually associated with algebraic operator to be fast and easy to compile into native code if so desired (but for now a vm is all we need) Possible extensions # I will probably allow braces as NOP operators, just as syntax sugar to improve readability. At some point they could get validated in LSP, so that potential bugs are highlit. Options for implementation # Assumption: these programs are very short. As such their source is not read in streaming, but it is all resident in memory while compiling. This allows the usage of string_views and the buffer itself in place of allocating too many temporary objects in memory. Hence, processing these expressions should be very memory efficient. Add the vm to this repo directly. Build a generic vm library for which specific instances can be generated downstream of a schema. This way it is easier to build different backends and integrate fast dispatching via perfect minimal hashing functions. Find a library already implementing this design and use that. no success in that Operators # Array operators # count [expr] # , count the dimensionality of expression returning a 1-dimensional scalar number reduce [initial] [reducer] [container] V , reduces to a 1-dimensional object each element of the container starting from the initial expression (sum, join etc) filter [container] F , filters elements out of a container map [expr] [container] M , maps container based on a lambda Generic # dup duplicate the last element on stack nop no operation rem remove last n elements from stack swap swap the two top elements eval (probably I will not expose this one) expose a nested repl vm load load variable on stack from the environment map store (probably I will not expose this one) store variable form stack to the environment map log to log errors/warning etc somewhere String operators # cat [container] cat , simplified version of V where based on the type, the 0 is used as initial and the reducer is the natural + operation join to join together strings on the stack with the first string. rcat like cat but in reverse order rjoin like join but in reverse order esc escape number to string literal Boolean operators # Boolean types are not directly supported. They are just integers with extra semantic. if [false] [true] [condition] ? and or not as expected (they are bitwise) xor nor nand as expected (they are bitwise). true false to load those values in stack. Comparison operators # eq neq bg bge lt lte for integers & floats For strings we have at least three criteria, which is making these operations harder to handle Typical comparison based on lexicographic comparison Dot comparison, introduced by vs to handle nesting Natural comparison, where for example $20<100$ Common algebraic operators # And all the typical math operations as usual + - * / mod (and mnemonic versions too) pow log count.0 & count.1 Cast # as.str as.int as.float Special # PIPE and APOS to escape | and ``` respectively ( & ) as nop just to enable formatting in expression (not enforced, but the LSP might check) rem to tag the prior tag as comment (remove the last element from stack)","title":"Computing expressions"},{"location":"repl-vm/#design","text":"","title":"Design"},{"location":"repl-vm/#why-rpn","text":"Several reasons: to avoid a complex parser for what will end up being a quite marginal feature it avoids the arbitrary precedence rules usually associated with algebraic operator to be fast and easy to compile into native code if so desired (but for now a vm is all we need)","title":"Why RPN?"},{"location":"repl-vm/#possible-extensions","text":"I will probably allow braces as NOP operators, just as syntax sugar to improve readability. At some point they could get validated in LSP, so that potential bugs are highlit.","title":"Possible extensions"},{"location":"repl-vm/#options-for-implementation","text":"Assumption: these programs are very short. As such their source is not read in streaming, but it is all resident in memory while compiling. This allows the usage of string_views and the buffer itself in place of allocating too many temporary objects in memory. Hence, processing these expressions should be very memory efficient. Add the vm to this repo directly. Build a generic vm library for which specific instances can be generated downstream of a schema. This way it is easier to build different backends and integrate fast dispatching via perfect minimal hashing functions. Find a library already implementing this design and use that. no success in that","title":"Options for implementation"},{"location":"repl-vm/#operators","text":"","title":"Operators"},{"location":"repl-vm/#array-operators","text":"count [expr] # , count the dimensionality of expression returning a 1-dimensional scalar number reduce [initial] [reducer] [container] V , reduces to a 1-dimensional object each element of the container starting from the initial expression (sum, join etc) filter [container] F , filters elements out of a container map [expr] [container] M , maps container based on a lambda","title":"Array operators"},{"location":"repl-vm/#generic","text":"dup duplicate the last element on stack nop no operation rem remove last n elements from stack swap swap the two top elements eval (probably I will not expose this one) expose a nested repl vm load load variable on stack from the environment map store (probably I will not expose this one) store variable form stack to the environment map log to log errors/warning etc somewhere","title":"Generic"},{"location":"repl-vm/#string-operators","text":"cat [container] cat , simplified version of V where based on the type, the 0 is used as initial and the reducer is the natural + operation join to join together strings on the stack with the first string. rcat like cat but in reverse order rjoin like join but in reverse order esc escape number to string literal","title":"String operators"},{"location":"repl-vm/#boolean-operators","text":"Boolean types are not directly supported. They are just integers with extra semantic. if [false] [true] [condition] ? and or not as expected (they are bitwise) xor nor nand as expected (they are bitwise). true false to load those values in stack.","title":"Boolean operators"},{"location":"repl-vm/#comparison-operators","text":"eq neq bg bge lt lte for integers & floats For strings we have at least three criteria, which is making these operations harder to handle Typical comparison based on lexicographic comparison Dot comparison, introduced by vs to handle nesting Natural comparison, where for example $20<100$","title":"Comparison operators"},{"location":"repl-vm/#common-algebraic-operators","text":"And all the typical math operations as usual + - * / mod (and mnemonic versions too) pow log count.0 & count.1","title":"Common algebraic operators"},{"location":"repl-vm/#cast","text":"as.str as.int as.float","title":"Cast"},{"location":"repl-vm/#special","text":"PIPE and APOS to escape | and ``` respectively ( & ) as nop just to enable formatting in expression (not enforced, but the LSP might check) rem to tag the prior tag as comment (remove the last element from stack)","title":"Special"},{"location":"syntax/","text":"Warning This documentation reflects the expected functionality for v0.5.0. Some features are still missing, progress is tracked in the repository and on the todo file in root. vs.templ uses special elements and attributes to define which actions the preprocessor should perform. These XML entities are scoped under the namespace s by default, but the user can set up a custom one as well. Please, notice that pugixml on which vs.templ is based does not have a full understanding of XML and namespaces are not covered. As such, they only operate as fancy prefixes at this scale. Expressions # Several of the attributes introduced by vs.templ accept expressions and not just simple literal values. Expression can are used to access elements and attributes of the data XML, in addition to represent native types like integers or strings. Their definition and usage is purposefully restricted to prevent arbitrary code to be run. A full list of feasible expression types: Empty expression, generally representing errors String, automatically assigned from expressions starting with # (the prefix # is skipped and not part of the final string) Integers (base 10), automatically assigned from expressions starting with a digit, + , - or . Floating point numbers, like integers but always ending with f Paths, of which three forms exists: those starting with $ . This special symbol is used to mark the nearest recorded node from the data XML being visited, or root if none. Paths with arbitrary prefix {var-name} where var-name is searched for and resolved from the symbols\u2019 stack. They can only appear as the first token. Absolute paths starting from the root, with prefix / . Path expressions will continue with one or more tokens / -terminated representing the tag name being visited. If terminated with ~prop-name the relevant attribute is selected. There are also two special meta-properties which can be accessed this way: Special access to the property ~!txt to get the node text. Special access to the element\u2019s name via ~!tag Finally, there are stack meta-expressions, starting with : . Those are run by a stack VM and can be sparingly used to perform more complex tasks. They return a single expression in one of the other real types. The full specifications of these meta-expressions can be found here . For most scenarios, only a minor subset is going to be useful, like some basic integer maths, comparisons and cat to merge strings. No further combination or format is allowed in expression. Else, their parsing will fail. However, the preprocessor should not generally throw exceptions, only emit error or warning logs. Examples # Using the following XML file as reference: <hello> <world attribute-a=\"value-0\"> text-0 </world> <!-- The second one will never be visited with paths like /hello/world/--> <world attribute-a=\"value-1\"> text-1 </world> </hello> /hello/world/ is the list of children for the first world element in hello /hello/world~attribute-a is evaluated as value-0 /hello/world~!txt is evaluated as text-0 Assuming a for cycle in /hello/ , its children will be navigated and $~attribute-a will be resolved in value-0 and value-1 . Operators for elements # Element operators or tag operators are special elements either acting on their children or they use them as default value in case of failure. There are several to control flow or add content to the final document. value # To introduce the result of a (meta) expression in the tree. Integers and floats are automatically serialized before adding them to the page. strings are just appended. attributes are interpreted as strings. nodes are added as subtree. value accepts an expression src as argument, by default set to $ . If the expression fails, its body will be used instead. Examples # <s:value src=\":...\">This fails, so this text will be used</s:value> <s:value src=\": `1` `2` +\">Since the operation is ok and returns `3` as integer, this text will not show up</s:value> element # This command is usedto generate a new element whose type is by an expression passed via the attribute s:type (this one is specifically namespaced). Any other property and child will be preserved. In case of failure, the tag is dropped. Examples # <s:element s:type=\"#tag-name\" prop-1=\"Hello\">Content</s:element> <s:element s:type=\":\" prop-1=\"Hello\">This will not be shown as the expression is not valid</s:element> for-range # tag is the name of the symbol where the current value will be stored. If empty the default $ is used. from starting value. to final value. step step of increment. It can be negative. If so to<from must hold true. Infinite cycles are detected before execution, in which case no step will run. Unlike other for variants, there is no header, footer or empty child. Anything inside a for-range is interpreted as item . Example # <s:for-range tag=\"i\" from=\"0\" to=\"10\" step=\"1\"> <s:for-range tag=\"j\" from=\"0\" to=\": `{i}`\" step=\"1\"> <s:value src=\": `{j}` `{i}` mul\" /> </s:for-range> </s:for-range> for & for-props # To iterate over children and props of an element respectively. Aside from that, they mostly share the same interface. tag : the name of the symbol hosting the current XML node pointer. If empty, its default is $ in : must be specified and is a path expression filter : as an expression in the internal custom language . sort-by : (only available for for ) list of | separated path expressions. Elements will be sorted giving priority from left to right order-by : order preference for each field in the sort-by or the only one implicit for for-props . Each entry is a pair type:comparator with type either ASC , DESC or RANDOM . If not provided, comparator is assumed to be the default one. As an alternative comparator we could have a one using . to separate values in tokens, and order them token by token. limit : maximum number of entries to be iterated. If 0 all of them will be considered, if positive that or the maximum number, if negative all but that number if possible o no content. offset : offset from start (of the filtered and ordered list of children) Both for & for-props support the following list of children. You can use as many instances of the same type as you want, they will be applied to the final document in the order they appear. header : shown at the top of a non-empty container footer : shown at the bottom of a non-empty container empty : shown if a container is empty item : the main body error : shown if it was not possible to retrieve items (because of an error in the path for example; in case of empty lists empty is used) The symbol [tag].c gets loaded with the entry number we are iterating over, so that it is possible to count which one we are at. For for-props there are also [tag].k and [tag].v for key and value of the prop. [tag] by default is $ . test & case # To perform conditional cut and paste in the final tree based on simple matches between a reference expression and some values. Inside the body of test we have one or more case . Attributes for case : continue default is false . If true it continues checking and executing even after a match. Else it will break. when an expression to compare against. The order of case elements is important and determines the overall flow. log # Optional argument type set to: notify when something should be logged, but there is no fault or suspicious behaviour ongoing. ok for tasks completed successfully error when a condition prevents this activity from succeeding, but the situation is recoverable warning when something can complete, but it is suspicious. panic when an error triggered, and the situation cannot be recovered Panic does not mean exceptions. For example, the evaluation of an expression might panic, but this problem is not propagated. It just means that there is no way to recover it, and downstream code will have to live with its failure. Error means that there is a capability recognized when it was raised for the system to rectify this issue. For example the inclusion of a file which does not exist can adopt the content of the include tag as fallback. include # Important The full behaviour of this function is determined by downstream integration. Add in place the file defined in src . If not found, it uses the content inside include . External files will have their root removed when included. File loading for a single include instance appearing in code is only done once, even if in a cycle. Later requests will show the same content as before. src is just a static string, not an expression. This is because the evaluation of the file must be statically resolved. The functionality of include is not provided by vs.templ and requires downstream integration. As such is no caching provided by vs.templ ; if you need that, you will have to implement it as part of the load function passed to the preprocessor constructor. Similarly, circular dependencies are not tested. It is up to you to use a load function which ensures they will not occur. The CLI shipping with this library has a very limited implementation which will load files as XML with normal fs paths. Examples # <s:include src=\"component.xml\"> <h1>Placeholder title</h1> <p>This will be used if the import fails. Leave empty if not needed</p> </s:include> data # Important The full behaviour of this function is determined by downstream integration. This command loads a data source in memory, and exposes it via a tag name. Any property which is not src and tag will be exposed to the supplier function for parametrization. Data retrieval is not part of vs.templ , so it is up to the downstream implementation to handle it as desired. The CLI shipping with the library will not handle complex features like filtering, sorting etc. The src passed is just being used as a regular fs path. Operators for properties # xxx are used as tags to identify groups under which multiple attributes should be used. for.SUB-ATTR.xxx & for-props.SUB-ATTR.xxx # As prop, attribute variants of for and for-props . They add attributes/values to the node they are defined within. value.xxx # As for the element version, to introduce the value of an expression as value of a prop xxx . prop.xxx # To generate new property whose name and value are determined by the pair passed as value. Examples # <tag s:prop.0=\"#hello|#world\" s:prop.1=\"#hallo|#Welt\"/> when # To test if the current element should be shown, if and only if the expression is true .","title":"Full Syntax reference"},{"location":"syntax/#expressions","text":"Several of the attributes introduced by vs.templ accept expressions and not just simple literal values. Expression can are used to access elements and attributes of the data XML, in addition to represent native types like integers or strings. Their definition and usage is purposefully restricted to prevent arbitrary code to be run. A full list of feasible expression types: Empty expression, generally representing errors String, automatically assigned from expressions starting with # (the prefix # is skipped and not part of the final string) Integers (base 10), automatically assigned from expressions starting with a digit, + , - or . Floating point numbers, like integers but always ending with f Paths, of which three forms exists: those starting with $ . This special symbol is used to mark the nearest recorded node from the data XML being visited, or root if none. Paths with arbitrary prefix {var-name} where var-name is searched for and resolved from the symbols\u2019 stack. They can only appear as the first token. Absolute paths starting from the root, with prefix / . Path expressions will continue with one or more tokens / -terminated representing the tag name being visited. If terminated with ~prop-name the relevant attribute is selected. There are also two special meta-properties which can be accessed this way: Special access to the property ~!txt to get the node text. Special access to the element\u2019s name via ~!tag Finally, there are stack meta-expressions, starting with : . Those are run by a stack VM and can be sparingly used to perform more complex tasks. They return a single expression in one of the other real types. The full specifications of these meta-expressions can be found here . For most scenarios, only a minor subset is going to be useful, like some basic integer maths, comparisons and cat to merge strings. No further combination or format is allowed in expression. Else, their parsing will fail. However, the preprocessor should not generally throw exceptions, only emit error or warning logs.","title":"Expressions"},{"location":"syntax/#examples","text":"Using the following XML file as reference: <hello> <world attribute-a=\"value-0\"> text-0 </world> <!-- The second one will never be visited with paths like /hello/world/--> <world attribute-a=\"value-1\"> text-1 </world> </hello> /hello/world/ is the list of children for the first world element in hello /hello/world~attribute-a is evaluated as value-0 /hello/world~!txt is evaluated as text-0 Assuming a for cycle in /hello/ , its children will be navigated and $~attribute-a will be resolved in value-0 and value-1 .","title":"Examples"},{"location":"syntax/#operators-for-elements","text":"Element operators or tag operators are special elements either acting on their children or they use them as default value in case of failure. There are several to control flow or add content to the final document.","title":"Operators for elements"},{"location":"syntax/#value","text":"To introduce the result of a (meta) expression in the tree. Integers and floats are automatically serialized before adding them to the page. strings are just appended. attributes are interpreted as strings. nodes are added as subtree. value accepts an expression src as argument, by default set to $ . If the expression fails, its body will be used instead.","title":"value"},{"location":"syntax/#examples_1","text":"<s:value src=\":...\">This fails, so this text will be used</s:value> <s:value src=\": `1` `2` +\">Since the operation is ok and returns `3` as integer, this text will not show up</s:value>","title":"Examples"},{"location":"syntax/#element","text":"This command is usedto generate a new element whose type is by an expression passed via the attribute s:type (this one is specifically namespaced). Any other property and child will be preserved. In case of failure, the tag is dropped.","title":"element"},{"location":"syntax/#examples_2","text":"<s:element s:type=\"#tag-name\" prop-1=\"Hello\">Content</s:element> <s:element s:type=\":\" prop-1=\"Hello\">This will not be shown as the expression is not valid</s:element>","title":"Examples"},{"location":"syntax/#for-range","text":"tag is the name of the symbol where the current value will be stored. If empty the default $ is used. from starting value. to final value. step step of increment. It can be negative. If so to<from must hold true. Infinite cycles are detected before execution, in which case no step will run. Unlike other for variants, there is no header, footer or empty child. Anything inside a for-range is interpreted as item .","title":"for-range"},{"location":"syntax/#example","text":"<s:for-range tag=\"i\" from=\"0\" to=\"10\" step=\"1\"> <s:for-range tag=\"j\" from=\"0\" to=\": `{i}`\" step=\"1\"> <s:value src=\": `{j}` `{i}` mul\" /> </s:for-range> </s:for-range>","title":"Example"},{"location":"syntax/#for-for-props","text":"To iterate over children and props of an element respectively. Aside from that, they mostly share the same interface. tag : the name of the symbol hosting the current XML node pointer. If empty, its default is $ in : must be specified and is a path expression filter : as an expression in the internal custom language . sort-by : (only available for for ) list of | separated path expressions. Elements will be sorted giving priority from left to right order-by : order preference for each field in the sort-by or the only one implicit for for-props . Each entry is a pair type:comparator with type either ASC , DESC or RANDOM . If not provided, comparator is assumed to be the default one. As an alternative comparator we could have a one using . to separate values in tokens, and order them token by token. limit : maximum number of entries to be iterated. If 0 all of them will be considered, if positive that or the maximum number, if negative all but that number if possible o no content. offset : offset from start (of the filtered and ordered list of children) Both for & for-props support the following list of children. You can use as many instances of the same type as you want, they will be applied to the final document in the order they appear. header : shown at the top of a non-empty container footer : shown at the bottom of a non-empty container empty : shown if a container is empty item : the main body error : shown if it was not possible to retrieve items (because of an error in the path for example; in case of empty lists empty is used) The symbol [tag].c gets loaded with the entry number we are iterating over, so that it is possible to count which one we are at. For for-props there are also [tag].k and [tag].v for key and value of the prop. [tag] by default is $ .","title":"for &amp; for-props"},{"location":"syntax/#test-case","text":"To perform conditional cut and paste in the final tree based on simple matches between a reference expression and some values. Inside the body of test we have one or more case . Attributes for case : continue default is false . If true it continues checking and executing even after a match. Else it will break. when an expression to compare against. The order of case elements is important and determines the overall flow.","title":"test &amp; case"},{"location":"syntax/#log","text":"Optional argument type set to: notify when something should be logged, but there is no fault or suspicious behaviour ongoing. ok for tasks completed successfully error when a condition prevents this activity from succeeding, but the situation is recoverable warning when something can complete, but it is suspicious. panic when an error triggered, and the situation cannot be recovered Panic does not mean exceptions. For example, the evaluation of an expression might panic, but this problem is not propagated. It just means that there is no way to recover it, and downstream code will have to live with its failure. Error means that there is a capability recognized when it was raised for the system to rectify this issue. For example the inclusion of a file which does not exist can adopt the content of the include tag as fallback.","title":"log"},{"location":"syntax/#include","text":"Important The full behaviour of this function is determined by downstream integration. Add in place the file defined in src . If not found, it uses the content inside include . External files will have their root removed when included. File loading for a single include instance appearing in code is only done once, even if in a cycle. Later requests will show the same content as before. src is just a static string, not an expression. This is because the evaluation of the file must be statically resolved. The functionality of include is not provided by vs.templ and requires downstream integration. As such is no caching provided by vs.templ ; if you need that, you will have to implement it as part of the load function passed to the preprocessor constructor. Similarly, circular dependencies are not tested. It is up to you to use a load function which ensures they will not occur. The CLI shipping with this library has a very limited implementation which will load files as XML with normal fs paths.","title":"include"},{"location":"syntax/#examples_3","text":"<s:include src=\"component.xml\"> <h1>Placeholder title</h1> <p>This will be used if the import fails. Leave empty if not needed</p> </s:include>","title":"Examples"},{"location":"syntax/#data","text":"Important The full behaviour of this function is determined by downstream integration. This command loads a data source in memory, and exposes it via a tag name. Any property which is not src and tag will be exposed to the supplier function for parametrization. Data retrieval is not part of vs.templ , so it is up to the downstream implementation to handle it as desired. The CLI shipping with the library will not handle complex features like filtering, sorting etc. The src passed is just being used as a regular fs path.","title":"data"},{"location":"syntax/#operators-for-properties","text":"xxx are used as tags to identify groups under which multiple attributes should be used.","title":"Operators for properties"},{"location":"syntax/#forsub-attrxxx-for-propssub-attrxxx","text":"As prop, attribute variants of for and for-props . They add attributes/values to the node they are defined within.","title":"for.SUB-ATTR.xxx &amp; for-props.SUB-ATTR.xxx"},{"location":"syntax/#valuexxx","text":"As for the element version, to introduce the value of an expression as value of a prop xxx .","title":"value.xxx"},{"location":"syntax/#propxxx","text":"To generate new property whose name and value are determined by the pair passed as value.","title":"prop.xxx"},{"location":"syntax/#examples_4","text":"<tag s:prop.0=\"#hello|#world\" s:prop.1=\"#hallo|#Welt\"/>","title":"Examples"},{"location":"syntax/#when","text":"To test if the current element should be shown, if and only if the expression is true .","title":"when"},{"location":"releases/v0.3.11/","text":"v0.3.11 # There has been much more progress than anticipated, and most features needed to reach v0.4.1 have been filled in already. This release is to make sure vs can properly use the newly supported syntax in its code and examples. Subsequent milestones have been rescheduled, and next new branch v0.4.x will be mostly for consolidation, documentation and to incrementally improve the quality of code. As such, I am splitting this release here, leaving the two leftover commands for v0.3.13 . New features # Introduced include to load more template files. Please, notice that checks to avoid circular dependencies are to be performed externally. All the remaining prop-based commands. value prop for for-prop Loading the environment of a preprocessor is now possible via load_env . Improved handling of some expressions making them less verbose. Better (and colourful) logging! Bug fixing # Fixed several broken maths operations like * . Breaking changes # The interface of preprocessor was changed once again to support the XML loader function. Minimal changes are expected downstream, based on your prior usage.","title":"V0.3.11"},{"location":"releases/v0.3.11/#v0311","text":"There has been much more progress than anticipated, and most features needed to reach v0.4.1 have been filled in already. This release is to make sure vs can properly use the newly supported syntax in its code and examples. Subsequent milestones have been rescheduled, and next new branch v0.4.x will be mostly for consolidation, documentation and to incrementally improve the quality of code. As such, I am splitting this release here, leaving the two leftover commands for v0.3.13 .","title":"v0.3.11"},{"location":"releases/v0.3.11/#new-features","text":"Introduced include to load more template files. Please, notice that checks to avoid circular dependencies are to be performed externally. All the remaining prop-based commands. value prop for for-prop Loading the environment of a preprocessor is now possible via load_env . Improved handling of some expressions making them less verbose. Better (and colourful) logging!","title":"New features"},{"location":"releases/v0.3.11/#bug-fixing","text":"Fixed several broken maths operations like * .","title":"Bug fixing"},{"location":"releases/v0.3.11/#breaking-changes","text":"The interface of preprocessor was changed once again to support the XML loader function. Minimal changes are expected downstream, based on your prior usage.","title":"Breaking changes"},{"location":"releases/v0.3.13/","text":"v0.3.13 # A new intermediate release before moving to v0.4.x . Surprisingly, whatever was originally scheduled for v0.3.13 has been delayed again, and other features took the spot! So, yeah, the attribute version of for-props and for are yet to come (at least they are covered in the examples). The revised plan is for the two missing commands to be in v0.3.15 , and then we move straight to the new minor. At that point the development here will slow down as all core features made their way in the codebase. I will be resuming work on vs.fltk . New features # data command has been added to introduce external data sources in the template. random order support in order-by for for loops. Stable random ordering depending on a seed number. Examples! LOTS OF EXAMPLEEES! And improved tests. We now have the most blazingly fast web server based on vs.templ (according to source myself)! Bug fixes # test/case fixed to match the intended specs. Fixed behaviour of for-prop tag command to ensure good symbols are provided in the loop scope. Fixed handling of floating point numbers in expressions. Breaking changes # Reverted and fixed src in for cycles to in as it initially was. Changed the preprocessor interface to introduce the new loadfn (the name has been recycled from before, the older loadfn is now includefn )","title":"V0.3.13"},{"location":"releases/v0.3.13/#v0313","text":"A new intermediate release before moving to v0.4.x . Surprisingly, whatever was originally scheduled for v0.3.13 has been delayed again, and other features took the spot! So, yeah, the attribute version of for-props and for are yet to come (at least they are covered in the examples). The revised plan is for the two missing commands to be in v0.3.15 , and then we move straight to the new minor. At that point the development here will slow down as all core features made their way in the codebase. I will be resuming work on vs.fltk .","title":"v0.3.13"},{"location":"releases/v0.3.13/#new-features","text":"data command has been added to introduce external data sources in the template. random order support in order-by for for loops. Stable random ordering depending on a seed number. Examples! LOTS OF EXAMPLEEES! And improved tests. We now have the most blazingly fast web server based on vs.templ (according to source myself)!","title":"New features"},{"location":"releases/v0.3.13/#bug-fixes","text":"test/case fixed to match the intended specs. Fixed behaviour of for-prop tag command to ensure good symbols are provided in the loop scope. Fixed handling of floating point numbers in expressions.","title":"Bug fixes"},{"location":"releases/v0.3.13/#breaking-changes","text":"Reverted and fixed src in for cycles to in as it initially was. Changed the preprocessor interface to introduce the new loadfn (the name has been recycled from before, the older loadfn is now includefn )","title":"Breaking changes"},{"location":"releases/v0.3.15/","text":"v0.3.15 # All done! The last for and for-props prop based commands have been completed. With this development of functionality for vs.templ is done. There are minor features planned for the v0.4.x branch, but most will be documentation, better examples, formal XML schemas and testing infrastructure. Once that is done we are going straight to v1 if there are no architectural problems being discovered in the meanwhile.","title":"V0.3.15"},{"location":"releases/v0.3.15/#v0315","text":"All done! The last for and for-props prop based commands have been completed. With this development of functionality for vs.templ is done. There are minor features planned for the v0.4.x branch, but most will be documentation, better examples, formal XML schemas and testing infrastructure. Once that is done we are going straight to v1 if there are no architectural problems being discovered in the meanwhile.","title":"v0.3.15"},{"location":"releases/v0.3.5/","text":"v0.3.5 # Technical release, only for the sake of fully testing workflows. At least feature parity with what it was its split from vs-fltk . Some degree of documentation. Add support for element.text() & element.name() in query. Replace the current split implementation with something requiring less allocations man page generation via meson (not great, but I\u2019ll take it). Initial setup for the test-suite. Add actual support of dot comparison in strings (to be tested). Functional CLI needed. Install scripts working (testing needed).","title":"V0.3.5"},{"location":"releases/v0.3.5/#v035","text":"Technical release, only for the sake of fully testing workflows. At least feature parity with what it was its split from vs-fltk . Some degree of documentation. Add support for element.text() & element.name() in query. Replace the current split implementation with something requiring less allocations man page generation via meson (not great, but I\u2019ll take it). Initial setup for the test-suite. Add actual support of dot comparison in strings (to be tested). Functional CLI needed. Install scripts working (testing needed).","title":"v0.3.5"},{"location":"releases/v0.3.7/","text":"v0.3.7 # This release brings many new features which further expand the capabilities of vs.templ : Introduced a more robust logging infrastructure at all levels. Now errors and warnings are better logged. Introduced log tag Introduced meta-expressions with their RPN virtual machine to support more complex evaluations. A good number of operators have been implemented so far, with most of the architectural bits ironed out. Introduced filter for loops now that we have meta-expressions. A significantly improved documentation. Initial work to support prop-based commands. The in attribute for cycles has been removed in favour of src to make it more consistent. No further breaking change is expected from v0.3.5 for templates, but the public interface itself has. You might need to slightly refactor current code, and provide an explicit logging function. Next release is expected to be the very last for v0.3.x.","title":"V0.3.7"},{"location":"releases/v0.3.7/#v037","text":"This release brings many new features which further expand the capabilities of vs.templ : Introduced a more robust logging infrastructure at all levels. Now errors and warnings are better logged. Introduced log tag Introduced meta-expressions with their RPN virtual machine to support more complex evaluations. A good number of operators have been implemented so far, with most of the architectural bits ironed out. Introduced filter for loops now that we have meta-expressions. A significantly improved documentation. Initial work to support prop-based commands. The in attribute for cycles has been removed in favour of src to make it more consistent. No further breaking change is expected from v0.3.5 for templates, but the public interface itself has. You might need to slightly refactor current code, and provide an explicit logging function. Next release is expected to be the very last for v0.3.x.","title":"v0.3.7"},{"location":"releases/v0.3.9/","text":"v0.3.9 # Just a quick corrective version over v0.3.7 to fix the behaviour of several untested features, like the newly added filters of for loops. This release also introduces few more meta-expression operators to allow escaping, and a realistic example emitting HTML to complement the rest of the docs. New features # when as a prop command for the conditional rendering of the owner. Breaking changes # sort-by and order-by will now use | in place , to split multiple options. when / is fully replaced. The older syntax was dreadful but necessary without the RPN virtual machine, but now that we have\u2026 say hello to test / case .","title":"V0.3.9"},{"location":"releases/v0.3.9/#v039","text":"Just a quick corrective version over v0.3.7 to fix the behaviour of several untested features, like the newly added filters of for loops. This release also introduces few more meta-expression operators to allow escaping, and a realistic example emitting HTML to complement the rest of the docs.","title":"v0.3.9"},{"location":"releases/v0.3.9/#new-features","text":"when as a prop command for the conditional rendering of the owner.","title":"New features"},{"location":"releases/v0.3.9/#breaking-changes","text":"sort-by and order-by will now use | in place , to split multiple options. when / is fully replaced. The older syntax was dreadful but necessary without the RPN virtual machine, but now that we have\u2026 say hello to test / case .","title":"Breaking changes"}]}
\ No newline at end of file
diff --git a/latest/doxygen/latex/vs-templ_8hpp__dep__incl.pdf b/latest/doxygen/latex/vs-templ_8hpp__dep__incl.pdf
index bb8689a..a284683 100644
Binary files a/latest/doxygen/latex/vs-templ_8hpp__dep__incl.pdf and b/latest/doxygen/latex/vs-templ_8hpp__dep__incl.pdf differ
diff --git a/latest/doxygen/latex/vs-templ_8hpp__incl.pdf b/latest/doxygen/latex/vs-templ_8hpp__incl.pdf
index 0c97848..b6938f3 100644
Binary files a/latest/doxygen/latex/vs-templ_8hpp__incl.pdf and b/latest/doxygen/latex/vs-templ_8hpp__incl.pdf differ
diff --git a/latest/wasm-demo.html b/latest/wasm-demo.html
new file mode 100644
index 0000000..96f651d
--- /dev/null
+++ b/latest/wasm-demo.html
@@ -0,0 +1,41 @@
+<html>
+
+<head>
+</head>
+
+<body>
+    <h1>This demo is being implemented!</h1>
+    <p>
+        It actually works, but if you don't plan on working via the web console there is not much to see :D.<br />
+        Please come back later :)
+    </p>
+    <script type="module">
+        import { WASI, File, OpenFile, ConsoleStdout, PreopenDirectory } from "https://unpkg.com/@bjorn3/browser_wasi_shim@0.3.0/dist";
+
+        let args = ["bin", "template.xml", "data.xml"];
+        let env = ["FOO=bar"];
+        let fds = [
+            new OpenFile(new File([])), // stdin
+            ConsoleStdout.lineBuffered(msg => console.log(`[WASI stdout] ${msg}`)),
+            ConsoleStdout.lineBuffered(msg => console.warn(`[WASI stderr] ${msg}`)),
+            new PreopenDirectory(".", [
+                ["data.xml", new File(new TextEncoder("utf-8").encode(`<a></a>`))],
+                ["template.xml", new File(new TextEncoder("utf-8").encode(`<b></b>`))],
+            ]),
+        ];
+        let wasi = new WASI(args, env, fds);
+        console.log(wasi)
+        const data = new Uint8Array(await (await fetch("https://github.com/lazy-eggplant/vs.templ/releases/latest/download/vs.templ.js")).arrayBuffer())
+
+        const res = new Response(data, { headers: [["Content-Type", "application/wasm"]] })
+        const module = new WebAssembly.Module(data);
+        const instance = new WebAssembly.Instance(module, {
+            "wasi_snapshot_preview1": wasi.wasiImport
+        });
+        console.log(instance);
+        //console.log(instance.exports.process("<a></a>", "<b></b>"));
+        wasi.start(instance);
+    </script>
+</body>
+
+</html>
\ No newline at end of file