dati

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

README (5167B)


      1 
      2 dati
      3 ====
      4 
      5 data and template interface
      6  
      7 USAGE
      8 -----
      9 
     10   dati [OPTIONS]
     11 
     12 DESCRIPTION
     13 -----------
     14 
     15   dati aims to provide a universal interface for executing data files,
     16   written in any data-serialization language, against template files,
     17   written in any templating languages.
     18   Ideally dati will support any language you want to use.
     19  
     20   dati works by using various libraries that do all the hard work to
     21   parse data and template files passed to it. It generates a data
     22   structure of all the passed data files combined (a super-data
     23   structure) and executes that structure against a set of root template
     24   files.
     25   The used libraries are listed below for credit/reference.
     26   
     27   dati can also be imported as a golang package to be used as a library.
     28  
     29 OPTIONS
     30 -------
     31 
     32   - `-r path`, `-root path` = path of template file to execute against.
     33   - `-p path...`, `-partial path...`= path of (multiple) template files that are
     34   called upon by at least one root template.
     35     - If a directory is passed then all files within that directory will
     36     (recursively) be loaded.
     37   - `-gd path...`, `-global-data path...` = path of (multiple) data files to load
     38   as "global data". If a directory is passed then all files within that directory
     39   will (recursively) be loaded.
     40   - `-d path...`, `-data path...` = path of (multiple) data files to load as
     41   "data". If a directory is passed then all files within that directory will
     42   (recursively) be loaded.
     43   - `-dk name`, `-data-key name` = set the name of the key used for the generated
     44   array of data (default: "data")
     45   - `-sd attribute`, `-sort-data attribute` = The file attribute to order data
     46   files by. If no value is provided, the data will be provided in the order it's
     47   loaded.
     48     - Accepted values: "filename", "modified".
     49     - A suffix can be appended to each value to set the sort order: "-asc" (for
     50     ascending), "-desc" (for descending). If not specified, this defaults to
     51     "-asc".
     52   - `-cfg file`, `-config file` = A data file to provide default values for the
     53   above options (see CONFIG).
     54 
     55 CONFIG
     56 ------
     57 
     58   It's possible you'll want to set the same options if you run dati multiple
     59   times for the same project. This can be done by creating a file (written as
     60   a data file) and passing the filepath to the -cfg argument.
     61   
     62   The key names for the options set in the config file must match the name of
     63   the argument option to set (long or short). For example (a config file in
     64   toml):
     65 
     66 	root="~/templates/blog.mst"
     67 	partial="~/templates/blog/"
     68 	gd="./blog.json"
     69 	data="./posts/"
     70 	dk="posts"
     71 
     72 DATA
     73 ----
     74 
     75   dati generates a single super-structure of all the data files passed to it.
     76   This super-structure is executed against each "root" template.
     77 
     78   The super-structure generated by dati will only have 1 definite key: "data"
     79   (or the value of the "data-key" option). This key will overwrite any "global
     80   data" keys in the root of the super-structure. Its value will be an array,
     81   where each element is the resulting data structure of each parsed "data"
     82   file.
     83  
     84   Parsed "global data" will be written to the root of the super-structure and
     85   into the root of each "data" array object. If a key within one of these
     86   objects conflicts with one of the "global data" keys, then that
     87   "global data" key will not be written to the object.
     88 
     89 TEMPLATES
     90 ---------
     91 
     92   All "root" template files passed to dati that have a file extension matching
     93   one of the supported templating languages will be parsed and executed
     94   against the super-structure generated by dati.
     95 
     96   All "parital" templates will be parsed into any "root" templates that have a
     97   file extension that match the same templating language.
     98 
     99 SUPPORTED LANGUAGES
    100 -------------------
    101 
    102   Below is a list of the supported data-serialisation languages, used for
    103   "data" and "global data" files.
    104 
    105   - JSON (.json), see https://json.org/
    106   - YAML (.yaml), see https://yamllint.com/
    107   - TOML (.toml), see https://toml.io/
    108 
    109   These are the currently supported templating languages, used for files
    110   passed in the "root" and "partial" arguments.
    111 
    112   - mustache (.mu, .mustache), see https://mustache.github.io/
    113   - golang text/template (.tmpl, .gotmpl), see https://golang.org/pkg/text/template/
    114   - golang html/template (.hmpl, .gohmpl), see https://golang.org/pkg/html/template/
    115     - note that this and text/template are almost interchangable, with the
    116     exception that html/template will produce "HTML output safe against code
    117     injection".
    118   - statix (.stx .statix), see https://gist.github.com/plugnburn/c2f7cc3807e8934b179e
    119 
    120 EXAMPLES
    121 --------
    122 
    123 	dati -cfg ./dati.cfg -r templates/textfile.mst
    124 
    125 	dati -r homepage.hmpl -p head.hmpl -p body.hmpl -gd meta.json -d posts/*
    126 
    127   see the examples/ directory in the dati repository for a cool example.
    128 
    129 LIBRARIES
    130 ---------
    131 
    132   As stated above, all of these libraries do the hard work, dati just combines
    133   it all together - so thanks to the authors. Also here for reference.
    134 
    135   - The Go standard library is used for parsing JSON, .tmpl/.gotmpl, .hmpl/.gohmpl
    136   - github.com/pelletier/go-toml
    137   - gopkg.in/yaml.v3
    138   - github.com/cbroglie/mustache
    139 
    140 AUTHORS
    141 -------
    142 
    143   - gearsix <gearsix@tuta.io>