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:
| M | src/suti.go | | | 20 | +++++++++++--------- |
| M | suti.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
