commit b3704811c668b1efe8ba3c9f866fcfcf07aabf88
parent 802cafa6d4dd7fbcc0017e6b371c2a40c8faf7b9
Author: gearsix <gearsix@tuta.io>
Date: Mon, 28 Aug 2023 19:13:54 +0100
Overhaul to README docs; update to the `-h` for the dati binary.
Diffstat:
| M | CHANGELOG.md | | | 10 | +++++++++- |
| M | README.md | | | 179 | ++++++++++++++++++++++++------------------------------------------------------- |
| M | TODO.md | | | 11 | ++--------- |
| A | cmd/README.md | | | 111 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | cmd/dati.go | | | 2 | -- |
5 files changed, 176 insertions(+), 137 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,12 @@
-# CHANGELOG
+
+## v1.4.1
+
+- Overhaul to the repo README documentation to make it a lot more clear
+- Minor update to the `-h` for the dati binary
+
+## v1.4.0
+
+- Now using 'hmpl' instead of 'htmpl' for golang html/template files
## v1.3.0
diff --git a/README.md b/README.md
@@ -1,150 +1,79 @@
-dati
-====
-
-data and template interface
-
-USAGE
------
-
- dati [OPTIONS]
-
-DESCRIPTION
------------
-
- dati 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 dati will support any language you want to use.
-
- dati 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.
-
- dati can also be imported as a golang package to be used as a library.
-
-OPTIONS
--------
-
- - **-r**, **-root** *PATH*<br/>
- Path of the root template file to execute against.
-
- - **-p**, **-partial** *PATH ...*<br/>
- 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**, **-global-data** *PATH ...*<br/>
- 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.
-
- - **-dk**, **-data-key** *NAME*<br/>
- Set the name of the key used for the generated array of data. The
- default *data key* is "data".
-
- - **-sd**, **-sort-data** *ATTRIBUTE*<br/>
- 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** **-config** *FILE*<br/>
- A data file to provide default values for the above options (CONFIG).
-
-CONFIG
-------
-
- It's possible you'll want to set the same options if you run dati 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
+DATI
----
- dati generates a single super-structure of all the data files passed to it.
- This super-structure is executed against each "root" template.
+**data and template interface**
+
+dati provides a unified interface for parsing data and templates.
+Ideally it will support all data and template languages, if it doesn't
+support one you want submit a PR or contact the developer.
+
+It can be used as a *Golang library* or an *executable tool*, although
+it was built as a library first but works well in both forms.
+
+**dati library**
- The super-structure generated by dati 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.
+The library is incredibly useful if you want to easily parse data and
+template languages without learning different interface / data
+structures for every library used for each supported language.
-TEMPLATES
----------
+For documentation on the dati library:
+[pkg.go.dev/notabug.org/gearsix/dati](https://pkg.go.dev/notabug.org/gearsix/dati#section-documentation)
+or
+`go doc -all` in the directory of the *dati* repo
- All "root" template files passed to dati that have a file extension matching
- one of the supported templating languages will be parsed and executed
- against the super-structure generated by dati.
+**dati binary**
- All "parital" templates will be parsed into any "root" templates that have a
- file extension that match the same templating language.
+The binary is intended to showcase what the library is useful for and
+be example of how to use it in your own software.
+It works perfectly well as a data-template executioner too though.
+It can parse data files and execute the parsed structure against
+templates with ease.
-SUPPORTED FORMATS / LANGUAGES
+View [cmd/README.md](./cmd/README.md) to see documentation on using the dati binary.
+
+View [cmd/dati.go](./cmd/dati.go) to view the source of the binary and see how the
+dati library can be used.
+
+
+supported formats / languages
-----------------------------
- Below is a list of the supported data-serialisation languages, used for
- "data" and "global data" files.
+**supported data languages**
- - JSON (.json), see https://json.org/
- - YAML (.yaml), see https://yamllint.com/
- - TOML (.toml), see https://toml.io/
+Below is a list of the supported languages for data-serialisation.
- These are the currently supported templating languages, used for files
- passed in the "root" and "partial" arguments.
+- JSON (*.json*) see [https://json.org/](https://json.org/)
+- YAML (*.yaml*) see [yamllint.com/](https://yamllint.com/)
+- TOML (*.toml*) see [toml.io/](https://toml.io/)
- - 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 -->
+**supported template language**
-EXAMPLES
---------
+These are the currently supported templating languages.
- dati -cfg ./dati.cfg -r templates/textfile.mst
+- mustache (*.mu*, *.mustache*) see [mustache.github.io/](https://mustache.github.io/)
+- golang text/template (*.tmpl*, *.gotmpl*) see [golang.org/pkg/text/template/](https://golang.org/pkg/text/template/)
+- golang html/template (*.hmpl*, *.gohmpl*) see [golang.org/pkg/html/template](/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 -->
- dati -r homepage.hmpl -p head.hmpl -p body.hmpl -gd meta.json -d posts/*
- see the examples/ directory in the dati repository for a cool example.
+acknowledgments
+---------------
-LIBRARIES
----------
+All of these libraries do the hard work, dati just combines them
+together - so thanks to the authors. Also here for reference.
- As stated above, all of these libraries do the hard work, dati 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
- - 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>
+- gearsix
diff --git a/TODO.md b/TODO.md
@@ -16,13 +16,6 @@ Aim to make api conformative
- rename Read* -> Decode*
- rename Write* -> Encode*
- remove file.go ? not used anymore
-
-**v1.3.0**
-
-/ add WriteData
-/ add WriteDataFile
-x add WriteTemplate
- / see (*Template).Execute
-x add WriteTemplateFile
- / see (*Template).ExecuteToFile
+ - add statix support
+ - add *a lot* more language support
diff --git a/cmd/README.md b/cmd/README.md
@@ -0,0 +1,111 @@
+
+DATI
+----
+
+```
+dati [OPTIONS]
+```
+
+DATA
+----
+
+Data is a file written in any data language (e.g. JSON or YAML), a list of
+supported languages can be seen in the README for the dati library.
+These files provide *key=value* data.
+
+dati generates a single data structure of all data contained within parsed
+data files.
+This super-structure is passed to each "root" template, where *value* data
+is accessed using the *key* strings.
+
+The data structure generated by dati will only have 1 absolute key: `"data"`
+(can be renamed using the **-dk**/**-data-key** option).
+This key will overwrite any other root key of the same name.
+Its value will be an array, where each element is the *key=value* data
+parsed one of the "data" files.
+
+Parsed "global data" will be written to the root of the data structure
+and into the root for each element of the "data" array.
+If a key within one of these objects conflicts with one of the keys in the
+"global data", then the "global data" key is ignored.
+
+
+TEMPLATES
+---------
+
+All "root" template files passed to dati that have a file extension matching
+one of the supported templating languages will be parsed and executed
+against the generated data structure.
+
+All "parital" templates will be parsed into any "root" templates that have a
+file extension that match the same templating language.
+
+
+OPTIONS
+-------
+
+- **-r**, **-root** *PATH*<br>
+Path of the root template file to execute against.
+
+- **-p**, **-partial** *PATH ...*<br>
+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**, **-global-data** *PATH ...*<br>
+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**, **-data** *PATH ...*<br>
+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**, **-data-key** *NAME*<br>
+Set the name of the key used for the generated array of data. The
+default *data key* is "data".
+
+- **-sd**, **-sort-data** *ATTRIBUTE*<br>
+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** **-config** *FILE*<br>
+A data file to provide default values for the above options (CONFIG).
+
+
+CONFIG
+------
+
+You might want to use the same options if you run dati multiple times
+for the same project. This can be done by creating 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"
+```
+
+EXAMPLES
+--------
+
+```
+dati -cfg ./dati.cfg -r templates/textfile.mst
+
+dati -r homepage.hmpl -p head.hmpl -p body.hmpl -gd meta.json -d posts/*
+```
+
+see the examples/ directory in the dati repository for a cool example.
+
diff --git a/cmd/dati.go b/cmd/dati.go
@@ -162,8 +162,6 @@ func help() {
A data file to provide default values for the above options (see CONFIG).
`)
-
- fmt.Println("See doc/dati.txt for further details")
}
// custom arg parser because golang.org/pkg/flag doesn't support list args
