From 1fa9f95cacf9044ea69d6db65da293665e5ea014 Mon Sep 17 00:00:00 2001 From: karurochari Date: Sun, 29 Dec 2024 15:13:05 +0000 Subject: [PATCH] Improving docs --- README.md | 8 ++++--- TODO.md | 7 ------ docs/calc.md | 54 +++++++++++++++++++++++++----------------- docs/for-developers.md | 8 +++++-- mkdocs.yml | 2 +- 5 files changed, 44 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 8dee792..88b7387 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,11 @@ > [!WARNING] -> Migration and adaptation from the other repository is done. -> Documentation and missing features still ongoing. +> Some features are still missing, they are tracked in the [TODO](./TODO.md) file. +> Documentation is an ongoing effort. `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. +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. ## Examples diff --git a/TODO.md b/TODO.md index 16fa123..549e9ac 100644 --- a/TODO.md +++ b/TODO.md @@ -42,13 +42,6 @@ This is a list of commands which are currently supported: # Milestones -## `v0.3.0` - -- [x] At least feature parity with what it was before moving it out of `vs-fltk`. -- [x] Some degree of documentation. -- [x] Add support for `element.text()` & `element.name()` in query. -- [x] Replace the current split implementation with something requiring less allocations - ## `v0.3.5` - [x] At least feature parity with what it was before moving it out of `vs-fltk`. diff --git a/docs/calc.md b/docs/calc.md index 1cd9f68..e6bf222 100644 --- a/docs/calc.md +++ b/docs/calc.md @@ -2,52 +2,62 @@ title: Computing expressions --- -Tentative specs for the expressions used in: +Tentative specs for higher order expressions. +They extends the current expression by starting with `:`. Instead of being interpreted as usual, they represent the serialization of a program in reverse polish notation (RPN). +This is going to run, and the single element left out on stack will be taken as the final expression. -- `calc` -- its prop variant -- in filters within `for` -- maybe in `for-range`, replacing simple numbers. - -My plan is to add a stack-based language in polish notation, constrained to have only one root. -For example: +For example, assuming the environment had `i` set to `1`: ``` -add:2 int:2 [{var-a}/path~attribute] error add:2 [2] [3] +: `#name-` `{i}` concat.*` ``` -Compressed it would be something like: +will return an expression of type string embedding the value `name-1`. -``` -+ int[{var-a}/path~attribute]! - +[2][3] -``` +Type casting should be explicit, but some operations like `concat` might cast automatically. +The delimiters are needed, since some types of expressions like strings can contain spaces and other escaping characters. + +## Design + +### Why RPN? -Inside `[...]` there are path expressions. Type casting should be explicit. The delimiters are needed since expressions can contain spaces and other escaping characters. The reason for going with something like this are: - to avoid a complex parser for what will end up being a quite marginal feature - to avoid the arbitrary precedence rules usually associated to algebraic operator -- to be fast and easy to compile into native code via tcc +- to be fast and easy to compile into native code via tcc if so desired (but for now it is just going to be interpreted) + +### Possible extensions -I will probably allow braces, just for the sake of readability. At some point I might validate them if present just to highlight potential bugs. +I will probably allow braces, just for the sake of readability, and to avoid being explicit about the number of arguments a function should take. +At some point I might validate them if present just to highlight potential bugs. -Options for implementation: +### Options for implementation -- Add them to this repo directly. -- Build a schema based generator and use it. 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. +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. -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 lamba +### String operators + - `concat` `[container] cat`, simplified version of `V` where based on the type, the 0 is used as initial and the reducer is the natural `+` operation + +### Boolean operators + - `if` `[false] [true] [condition] ?` +### Common algebraic operators + - And all the typical math operations as usual diff --git a/docs/for-developers.md b/docs/for-developers.md index c847aa8..1b3c0c2 100644 --- a/docs/for-developers.md +++ b/docs/for-developers.md @@ -10,11 +10,15 @@ title: Information for developers To build, test and install it you can just use normal meson commands. -## Using it +## Embedding it -Right now this project is only available as a meson package. +Right now, this project 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. + +The CLI in `src/app` shows all that is needed to use `vs.templ` as a library. + ## Versioning At this time, this repository is only available as a [meson](https://mesonbuild.com/) package. diff --git a/mkdocs.yml b/mkdocs.yml index 431840b..0308f03 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,5 @@ site_name: vs.templ -repo_url: https://github.com/lazy-eggplant/vs-templ +repo_url: https://github.com/lazy-eggplant/vs.templ site_dir: dist/website/docs docs_dir: docs