dati

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

commit 98705b58667c14f53b298606582bb1f34e67eef9
parent 9aed9631e29c0d17768c8b36f3143ee80c2eec36
Author: gearsix <gearsix@tuta.io>
Date:   Tue, 16 Feb 2021 15:16:58 +0000

modified the argument names; updated suti.txt

- added the "root" template argument; added RootPaths to Options
- tidied up suti.txt more

Diffstat:
Msrc/suti.go | 20+++++++++++---------
Msuti.txt | 109++++++++++++++++++++++++++++++++++++++++++-------------------------------------
2 files changed, 69 insertions(+), 60 deletions(-)

diff --git a/src/suti.go b/src/suti.go @@ -6,12 +6,13 @@ import ( ) type Options struct { - TemplatePaths []string - GlobalDataPaths []string - DataPaths []string - DataKey string - SortData string - ConfigFile string + RootPaths []string + PartialPaths []string + GlobalDataPaths []string + DataPaths []string + DataKey string + SortData string + ConfigFile string } var options Options @@ -55,9 +56,10 @@ func parseArgs(args []string) (o Options) { } // set valid any flags that don't take arguments here - - } else if flag == "t" || flag == "template" { - o.TemplatePaths = append(o.TemplatePaths, arg) + } else if flag == "r" || flag == "root" { + o.RootPaths = append(o.RootPaths, arg) + } else if flag == "p" || flag == "partial" { + o.PartialPaths = append(o.PartialPaths, arg) } else if flag == "gd" || flag == "globaldata" { o.GlobalDataPaths = append(o.GlobalDataPaths, arg) } else if flag == "d" || flag == "data" { diff --git a/suti.txt b/suti.txt @@ -7,25 +7,32 @@ 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 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 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 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. + 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... + -r path..., -root 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... + -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. @@ -33,19 +40,19 @@ OPTIONS 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 + -dk name, -data-key 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. + -sd attribute, -sort-data attribute + The file attribute to order data files by. + 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 "filename-desc". -cfg file, -config file - A data file to provide default values for the above options (see CONFIG) + 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 @@ -53,43 +60,49 @@ CONFIG 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. + 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 - (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). + 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 "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. + (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. - "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. + 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 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 + 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. + "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: + 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/ @@ -99,19 +112,13 @@ SUPPORTED LANGUAGES - 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 + // 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