suti

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.
 
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
--------

	suti -cfg ./suti.cfg -r templates/textfile.mst

	suti -r homepage.hmpl -p head.hmpl -p body.hmpl -gd meta.json -d posts/*

  see the examples/ directory in the suti repository for a cool example.

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
  - github.com/pelletier/go-toml
  - gopkg.in/yaml.v3
  - github.com/cbroglie/mustache

AUTHORS
-------

  - gearsix <gearsix@tuta.io>