Adding tests, improving docs & aligning them to actual specs.

KaruroChori · KaruroChori · commit b5d9f867abb2 · 2025-01-22T14:35:52.000Z
diff --git a/README.md b/README.md
@@ -51,9 +51,9 @@ This preprocessor can be used in one of two ways:
 
 ### As a library
 
-`vs.templ` is specifically intended to be embedded in other applications.  
+_vs.templ_ is specifically intended to be embedded in other applications.  
 You can use it either as a dynamic or a static library.  
-If you want to integrate `vs.templ` in your own codebase, [this](./docs/for-developers.md) is where to start.
+If you want to integrate _vs.templ_ in your own codebase, [this](./docs/for-developers.md) is where to start.
 
 ### Via its CLI
 
@@ -73,7 +73,7 @@ with both files added via pipes, like `vs.tmpl <(cat template.xml) <(cat data.xm
 
 #### vs.templ.js
 
-If you don't want to install `vs.templ`, it can be used standalone if you have a compatible WASM runtime on your system.  
+If you don't want to install _vs.templ_, it can be used standalone if you have a compatible WASM runtime on your system.  
 WASM builds are attached to releases.
 
 ```bash
@@ -84,16 +84,19 @@ bun run ./vs.templ.js [...]
 
 ```bash
 meson setup build
+#In a real world context you might want something more complex, like:
+#meson setup -Db_lto=true -Db_thinlto_cache=true -Db_lto_mode=thin --reconfigure build/ --buildtype=release
+
 meson install -C build
 ```
 
 This works on most systems.  
 Still, to ensure expected behaviour, I highly suggest a dry run by setting `DESTDIR` somewhere safe.
 
-## Projects using `vs.templ`
+## Projects using _vs.templ_
 
-- [vs](https://github.com/KaruroChori/vs-fltk) the parent project from which `vs.templ` derived.
-- [vs.http](https://github.com/lazy-eggplant/vs.http) an HTTP server built around `vs.templ`.
+- [vs](https://github.com/KaruroChori/vs-fltk) the parent project from which _vs.templ_ derived.
+- [vs.http](https://github.com/lazy-eggplant/vs.http) an HTTP server built around _vs.templ_.
 
 ## Why?
 
diff --git a/TODO.md b/TODO.md
@@ -4,13 +4,13 @@
 
 - [ ] Rework the mechanisms used in `order-by` and fill missing comparisons in the RPN
   - [ ] Extend `order-by` to support explicit types for comparison (extremely optional)
-  - [ ] Support for string natural order (111 > 22).
-- [ ] In the UI for the demo, add a loader as the first boot is quite slow
-- [ ] Fill in the docs at least of the public interface
+  - [x] Support for string natural order (111 > 22).
 
 ## `v0.4.5`
 
 - [ ] Properly show ctx information while logging
+- [ ] In the UI for the demo, add a loader as the first boot is quite slow
+- [ ] Fill in the docs at least of the public interface
 
 ## `v0.4.x`
 
diff --git a/dist/wasm-demo/README.md b/dist/wasm-demo/README.md
@@ -1,2 +1,2 @@
-Just the wasm demo for `vs.templ`.  
+Just the wasm demo for _vs.templ_.  
 Examples and `vs.templ.js` must be copied as part of the CI before building it.
diff --git a/docs/faq.md b/docs/faq.md
@@ -12,7 +12,7 @@ While the XML ecosystem is often reliant on XSLT as a preprocessor, this option
 - 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.  
+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](https://handlebarsjs.com/) or [mustache](https://mustache.github.io/)?
@@ -32,4 +32,4 @@ That way, there is no need to load the entire data source in memory as it would
 
 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.  
 For the time being, you can offer external data sources of whatever type by implementing the optional `loadfn` downstream.  
-This allows `vs.templ` to indirectly work with any data source you desire.
+This allows _vs.templ_ to indirectly work with any data source you desire.
diff --git a/docs/for-developers.md b/docs/for-developers.md
@@ -25,9 +25,9 @@ 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.  
+_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.
+The CLI in `src/app` shows everything that is needed to use _vs.templ_ as a library.
 
 ### C bindings
 
diff --git a/docs/manual.md b/docs/manual.md
@@ -26,7 +26,7 @@ with both files added via pipes, like `vs.tmpl <(cat template.xml) <(cat data.xm
 
 ## Syntax quick reference
 
-`vs.templ` uses special elements and attributes to determine the actions to be performed by the preprocessor.  
+_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](https://github.com/KaruroChori/vs-templ).
diff --git a/docs/ordering.md b/docs/ordering.md
@@ -22,7 +22,9 @@ Nodes should not be directly compared. Doing so is not illegal, just nonsensical
 
 ### Nodes
 
-Nodes should not be directly compared. Doing so is not illegal, just nonsensical and UB. A more precise semantic for this case might be introduced later on.
+Nodes should not be directly compared.  
+Doing so is not illegal, just nonsensical and UB.  
+A more precise semantic for this case might be introduced later on.
 
 ### Attributes
 
@@ -42,8 +44,7 @@ Comparison as expected from any basic math class.
 
 ### Strings
 
-Strings are by far the most complex to handle as multiple criteria are possible.  
-Strings 
+Strings are by far the most complex to handle as multiple criteria are possible.
 
 #### Encoding ordering
 
@@ -57,4 +58,4 @@ Based on the binary representation of UTF-8 encoding.
 
 For symbols in the Latin alphabet this is more or less equivalent to the encoding ordering.  
 However, different languages have totally different customary approaches, and are not often based on alphabets.  
-Basically any criteria rooted in linguistic arguments goes in here.
+Basically any criteria rooted in linguistic arguments goes in here.
diff --git a/docs/releases/v0.3.13.md b/docs/releases/v0.3.13.md
@@ -13,7 +13,7 @@ I will be resuming work on `vs.fltk`.
 - `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](https://github.com/lazy-eggplant/vs.http) based on `vs.templ` (according to source myself)!
+- We now have the [most blazingly fast web server](https://github.com/lazy-eggplant/vs.http) based on _vs.templ_ (according to source myself)!
 
 ### Bug fixes
 
diff --git a/docs/releases/v0.3.15.md b/docs/releases/v0.3.15.md
@@ -1,7 +1,7 @@
 ## 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.
+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.
diff --git a/docs/releases/v0.3.7.md b/docs/releases/v0.3.7.md
@@ -1,6 +1,6 @@
 ## v0.3.7
 
-This release brings many new features which further expand the capabilities of `vs.templ`:
+This release brings many new features which further expand the capabilities of _vs.templ_:
 
 - [x] Introduced a more robust logging infrastructure at all levels. Now errors and warnings are better logged.
   - [x] Introduced `log` tag
diff --git a/docs/repl-vm.md b/docs/repl-vm.md
@@ -21,7 +21,7 @@ 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`.  
+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
diff --git a/docs/syntax.md b/docs/syntax.md
@@ -5,26 +5,27 @@ title: Full Syntax reference
 > [!WARNING]  
 > While all core features have been implemented, documentation efforts are still ongoing.
 
-`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.
+_vs.templ_ uses special elements and attributes to define actions for the preprocessor to perform.  
+These XML entities are scoped with the prefix determined by the URI _vs.templ_. Conventionally, the prefix used is `s`, but users can set up their own.  
+Please, notice that _pugixml_, on which _vs.templ_ is based, does not have a full understanding of XML, and namespaces are in the list of features not covered.  
+As such, this preprocessor will not really perform any actual validation, if not for its own prefix.
 
 ## 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.
+Most of the attributes introduced by _vs.templ_ accept expressions, and not just simple literal values.
+Expression can are used to access elements and attributes from the data source, or they can represent native types like _integers_, _floats_ and _strings_.  
+Their definition and usage is purposefully restricted, to prevent the execution of arbitrary code.  
+This is a full list of all expression types:
+
+- **Empty** expression, a pseudo-value often used to represent 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 few forms exists:
   - Paths with arbitrary prefix `{var-name}` where `var-name`is searched for and resolved from the symbols' stack. They can only appear as the first token.
+  - Those starting with `$`. This special symbol is used to mark the nearest recorded node from the data XML being visited, or root if none. It is a shorthand for `{$}`.
   - Absolute paths starting from the root, with prefix `/`.
+  - Paths starting with `~`, an attribute rooted on `{$}`.
 
 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.
@@ -40,7 +41,7 @@ The full specifications of these meta-expressions can be found [here](repl-vm.md
 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.
+However, the preprocessor will not generally throw exceptions, the preferred mechanism is to emit log messages and continue.
 
 ### Examples
 
@@ -63,7 +64,7 @@ Using the following XML file as reference:
 - `/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-based operators
 
 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.
@@ -124,7 +125,7 @@ Infinite cycles are detected before execution, in which case no step will run. U
 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 `$`
+- `tag`: the name of the symbol hosting the current XML node pointer. If left empty, its default is assumed to be `$`
 - `in`: must be specified and is a path expression
 - `filter`: as an expression in the internal [custom language](./calc.md).
 - `sort-by`: (only available for `for`) list of `|` separated path expressions. Elements will be sorted giving priority from left to right
@@ -181,8 +182,8 @@ Add in place the file defined in `src`. If not found, it uses the content inside
 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.  
+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.
@@ -203,12 +204,12 @@ The CLI shipping with this library has a very limited implementation which will
 
 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.
+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
+## Property-based operators
 
 `xxx` are used as tags to identify groups under which multiple attributes should be used.
 
diff --git a/test/cases/for.tag.xml b/test/cases/for.tag.xml
@@ -2,6 +2,12 @@
 <test xmlns:s="vs.templ">
     <data>
         <items>
+            <section-0>
+                <item prop-a="b.c01.d2">Text A</item>
+                <item prop-a="aa.c0.2">Text B</item>
+                <item prop-a="cc.c1.2">Text C</item>
+                <item prop-a="b.c2.d2">Text D</item>
+            </section-0>
             <section-a>
                 <item prop-a="Value 1">Text A</item>
                 <item prop-a="Value 2">Text B</item>
@@ -17,6 +23,14 @@
 
     <template>
         <document>
+            <h1>Section 0</h1>
+            <ul>
+                <s:for in="$/items/section-0/" sort-by="~prop-a" order-by=".desc">
+                    <s:item>
+                        <li><s:value src="$~prop-a" />: <s:value src="$~!txt" /></li>
+                    </s:item>
+                </s:for>
+            </ul>
             <h1>Section A</h1>
             <ul>
                 <s:for in="$/items/section-a/" sort-by="~prop-a" order-by="desc">
@@ -61,6 +75,13 @@
 
     <expects>
         <document>
+            <h1>Section 0</h1>
+            <ul>
+                <li>cc.c1.2: Text C</li>
+                <li>b.c2.d2: Text D</li>
+                <li>b.c01.d2: Text A</li>
+                <li>aa.c0.2: Text B</li>
+            </ul>
             <h1>Section A</h1>
             <ul>
                 <li>Value 3: Text C</li>
diff --git a/test/cases/when.prop.xml b/test/cases/when.prop.xml
@@ -7,12 +7,14 @@
         <identity>
             <h1 s:when=": false"></h1>
             <h2 s:when=": true"></h2>
+            <h1 s:when=": true" s:when.attr1=": true" s:when.attr2=": false"></h1>
         </identity>
     </template>
 
     <expects>
         <identity>
             <h2></h2>
+            <h1 attr1=""></h1>
         </identity>
     </expects>
 </test>

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`		-Just the wasm demo for `vs.templ`.
	`1`	`+Just the wasm demo for _vs.templ_.`
`2`	`2`	Examples and `vs.templ.js` must be copied as part of the CI before building it.