dati

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

commit 0e53eec4b61dd0cd33ddf67502d60772bf470302
parent 8beaaea788c5529d0eb16b4f74cf7b5c50414376
Author: gearsix <gearsix@tuta.io>
Date:   Sat, 13 Mar 2021 13:19:46 +0000

moved suti.txt to doc/

Diffstat:
Adoc/suti.txt | 126+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Dsuti.txt | 127-------------------------------------------------------------------------------
2 files changed, 126 insertions(+), 127 deletions(-)

diff --git a/doc/suti.txt b/doc/suti.txt @@ -0,0 +1,125 @@ +NAME + suti - simple unified templating interface + +USAGE + suti [OPTIONS] + +DESCRIPTION + suti aims to provide a universal interface for executing data files, + written in any data-serialization language, against template files, + written in any templating languages. + Ideally suti will support any language you want to use. + + suti works by using various libraries that do all the hard work to + parse data and template files passed to it. It generates a data + structure of all the passed data files combined (a super-data + structure) and executes that structure against a set of root template + files. + The used 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 + -r path, -root path + path of template file to execute against. + + -p path..., -partial path... + path of (multiple) template files that are called upon by at least one + root template. If a directory is passed then all files within that + directory will (recursively) be loaded. + + -gd path..., -global-data 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, -data-key name + set the name of the key used for the generated array of data (default: + "data") + + -sd attribute, -sort-data attribute + The file attribute to order data files by. If no value is provided, the data + will be provided in the order it's loaded. + Accepted values: "filename", "modified". + A suffix can be appended to each value to set the sort order: "-asc" (for + ascending), "-desc" (for descending). If not specified, this defaults to + "-asc". + -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). For example (a config file in + toml): + + root="~/templates/blog.mst" + partial="~/templates/blog/" + gd="./blog.json" + data="./posts/" + dk="posts" + +DATA + suti generates a single super-structure of all the data files passed to it. + This super-structure is executed against each "root" template. + + The super-structure generated by suti will only have 1 definite key: "data" + (or the value of the "data-key" option). This key will overwrite any "global + data" keys in the root of the super-structure. Its value will be an array, + where each element is the resulting data structure of each parsed "data" + file. + + Parsed "global data" will be written to the root of the super-structure and + into the root of each "data" array object. If a key within one of these + objects conflicts with one of the "global data" keys, then that + "global data" key will not be written to the object. + +TEMPLATES + All "root" template 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. + + All "parital" templates will be parsed into any "root" templates that have a + file extension that match the same templating language. + +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/ + + These are the currently supported templating languages, used for files + passed in the "root" and "partial" arguments. + + - 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 + // TODO + +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. + + - The Go standard library is used for parsing JSON, .tmpl/.gotmpl, .hmpl/.gohmpl + // ... + +SEE ALSO + suti-lib(1) + +AUTHORS + - gearsix <gearsix@tuta.io> +\ No newline at end of file diff --git a/suti.txt b/suti.txt @@ -1,127 +0,0 @@ -// FIRST-DRAFT - -NAME - suti - simple unified templating interface - -USAGE - suti [OPTIONS] - -DESCRIPTION - suti aims to provide a universal interface for executing data files, - written in any data-serialization language, against template files, - written in any templating languages. - Ideally suti will support any language you want to use. - - suti works by using various libraries that do all the hard work to - parse data and template files passed to it. It generates a data - structure of all the passed data files combined (a super-data - structure) and executes that structure against a set of root template - files. - The used 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 - -r path, -root path - path of template file to execute against. - - -p path..., -partial path... - path of (multiple) template files that are called upon by at least one - root template. If a directory is passed then all files within that - directory will (recursively) be loaded. - - -gd path..., -global-data 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, -data-key name - set the name of the key used for the generated array of data (default: - "data") - - -sd attribute, -sort-data attribute - The file attribute to order data files by. If no value is provided, the data - will be provided in the order it's loaded. - Accepted values: "filename", "modified". - A suffix can be appended to each value to set the sort order: "-asc" (for - ascending), "-desc" (for descending). If not specified, this defaults to - "-asc". - -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). For example (a config file in - toml): - - root="~/templates/blog.mst" - partial="~/templates/blog/" - gd="./blog.json" - data="./posts/" - dk="posts" - -DATA - suti generates a single super-structure of all the data files passed to it. - This super-structure is executed against each "root" template. - - The super-structure generated by suti will only have 1 definite key: "data" - (or the value of the "data-key" option). This key will overwrite any "global - data" keys in the root of the super-structure. Its value will be an array, - where each element is the resulting data structure of each parsed "data" - file. - - Parsed "global data" will be written to the root of the super-structure and - into the root of each "data" array object. If a key within one of these - objects conflicts with one of the "global data" keys, then that - "global data" key will not be written to the object. - -TEMPLATES - All "root" template 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. - - All "parital" templates will be parsed into any "root" templates that have a - file extension that match the same templating language. - -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/ - - These are the currently supported templating languages, used for files - passed in the "root" and "partial" arguments. - - - 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 - // TODO - -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. - - - The Go standard library is used for parsing JSON, .tmpl/.gotmpl, .hmpl/.gohmpl - // ... - -SEE ALSO - suti-lib(1) - -AUTHORS - - gearsix <gearsix@tuta.io>