data and template interface
git clone git://git.gearsix.net/dati
Log | Files | Refs | Atom | README | LICENSE

commit 8014ab9d4ff4f4467668c0e3318327bcc7ef6633
Author: gearsix <gearsix@tuta.io>
Date:   Wed, 10 Feb 2021 20:47:10 +0000

git init; added man1 .txt spec

Asuti.txt | 121+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 121 insertions(+), 0 deletions(-)

diff --git a/suti.txt b/suti.txt @@ -0,0 +1,121 @@ +// FIRST-DRAFT + +NAME + suti - simple unified templating interface + +USAGE + suti [OPTIONS] + +DESCRIPTION + suti aims to provide a universal interface for executing data (written in + any supported data-serialisation language) against any template file + (written in any of the supported templating languages). Ideally suti + supports any language you want to use. + + suti works by using various libraries that do all the hard work to generate + a data structure of your combined data files and then executes that + structure against a set of templates, generated by parsing the passed + template files. These libraries are listed below for credit/reference. + + suti can also be imported as a golang package to be used as a library. See + suti-lib for details. + +OPTIONS + -t path..., -template path... + path of (multiple) template files to execute against. If a directory is + passed then all files within that directory will (recursively) be loaded. + + -gd path..., -globaldata path... + path of (multiple) data files to load as "global data". If a directory is + passed then all files within that directory will (recursively) be loaded. + + -d path..., -data path... + path of (multiple) data files to load as "data". If a directory is passed + then all files within that directory will (recursively) be loaded. + + -dk name, -datakey name + set the name of the key used for the generated array of data (default: + "data") + + -sd attribute, -sortdata attribute + The attribute to set the order to load data files. Accepted values: + "filename", "modified". (default: "filename"). A suffix can be appended + to each value to set the sort order: "-asc" (for ascending), "-desc" + (for descending). By default, the sort order will be descending. See + EXAMPLES. + + -cfg file, -config file + A data file to provide default values for the above options (see CONFIG) + +CONFIG + It's possible you'll want to set the same options if you run suti multiple + times for the same project. This can be done by creating a file (written as + a data file) and passing the filepath to the -cfg argument. + + The key names for the options set in the config file must match the name of + the argument option to set (long or short), see EXAMPLES. + +DATA + suti generates a single super-structure of all the data files passed to it + (that have a recognised data file extension). This array will be sorted by + the value of the "sortdata" option. The super-structure is executed + against each root template (see TEMPLATES). + + The super-structure generated by suti will only have 1 definite key: "data" + (or the value of the "datakey" option). This key will overwrite any global + keys in the root of the super-structure and its value will be an array, + where each element is the data structure parsed from each data file passed + in the "data" option. + + "global data" passed to suti will be parsed to the root of the + super-structure and also into each object of the generated "data" array. + These keys will be overwritten if they overlap with any keys in the "data" + structures or by the set "datakey" value in the root of the generated + super-structure. + +TEMPLATES + All files passed to suti that have a file extension matching one of the + supported templating languages will be parsed and executed against the + super-structure generated by suti. A "root template" is defined as any + templates that are not called in by another template as a "partial". + + // discuss combining templates of different languages ? - see how impl. works out first + +SUPPORTED LANGUAGES + Below is a list of the supported data-serialisation languages, used for + "data" and "global data" files. + + - JSON (.json), see https://json.org/ + - YAML (.yaml), see https://yamllint.com/ + - TOML (.toml), see https://toml.io/ + + templating languages: + - mustache (.mu, .mustache), see https://mustache.github.io/ + - golang text/template (.tmpl, .gotmpl), see https://golang.org/pkg/text/template/ + - golang html/template (.hmpl, .gohmpl), see https://golang.org/pkg/html/template/ + - note that this and text/template are almost interchangable, with the + exception that html/template will produce "HTML output safe against code + injection". + - statix (.stx .statix), see https://gist.github.com/plugnburn/c2f7cc3807e8934b179e + +EXAMPLES + Writing a config file is very simple, here's one called "suti.toml": + + template="~/templates/blog.mst" + d="./blogs/cat-memes/" + sd="modified-desc" + dk="content" + + // TODO more + +LIBRARIES + As stated above, all of these libraries do the hard work, suti just combines + it all together - so thanks to the authors. Also here for reference. + + // ... + +SEE ALSO + suti-lib(1) + +AUTHORS + - gearsix <gearsix@tuta.io>