O-Stache

This is a simple adaptation of mustache style templates to structured data (as opposed to plain text/HTML). Of course, you can use mustache templates to generate structured data, but you lose the ability of JSON/YAML/etc. tools to easily validate it, and the ability to convert the template between different structured formats (e.g. JSON -> YAML -> HOCON -> ...).

It is currently at version 0.1 - there are some tests, it seems to work, but it hasn't yet been used in anger, it lacks documentation, and there are known sharp edges (e.g. see Errors below). Feedback welcome.

How it works

Refer to tests.json for a comprehensive view of how everything works.

The module exposes a render function of the form:

function render (template, parameters)

where template is some arbitrary structured data, and 'parameters' is an object containing values that can be addressed via the template.

The output of the function is the rendered structured data, and will be identical to the input template except where ((...)) is used. This is interpreted as an ostache command (cf mustache with {{...}} - we use ((...)) for better YAML compatibility).

Basic variable substitution

Any time ((variable)) is used, the variable is looked up in the parameters (or the current context) and inserted into the string or object. If parameters[variable] contains structured data, this structured data is retained only if the variable substitution is the only element in the string.

For example:

template:
  y: "((x))"
parameters:
  x: {z: 1}
result:
  y: {z: 1}

Or, inside a string:

template:
  y: "hello ((x))"
parameters:
  x: "world"
result:
  y: "hello world"

Unlike mustache, no HTML escaping is performed.

If one is referring to parameters inside a nested structure, '.' can be used as the separator (e.g. one could refer to x.z to obtain the value 1 in the first example above).

Conditional includes

...automatically look in outer scopes...

Loops

Defaults

Because users can provide arbitrary structured data, when constructing the template it is sometimes useful to provide 'default values'. This can be achieved in some cases by having the defaults at the top level of the object structure along with the conditional includes; for example:

Overrides (forbidden values)

... precedence tricks ...

Errors

Unlike ordinary mustache templates, it is possible to create templates that are unparseable, largely because of the possibility of generating incompatible types from multiple conditional includes (or if one has other fields in the base object). For instance:

parameters:
  x: true
  y: true
template:
  val: "hello"
  ((#x)):
    val2: "bye"
  ((#y)): "never"

Here, although the ((#x)) inclusion resolves to an object/map (e.g. one can add val2 to the top level fields), because the inclusion of ((#y)) resolves to a string, it is unclear how that should be 'added' to the object. The general rule is that if there is any non-object type here, that should be the only type. It would be valid to do:

parameters:
  y: true
template:
  ((#y)): "never"

which would simple evaluate to the string "never".

For the moment, these errors are simple assertion failures generated by the node 'assert' module. A better error handling scheme is planned.

Err, XSLT?

No comment.

Why are the tests in some weird json format?

The intent is to be able to use these tests to check the compliance of o-stache libraries implemented in other languages.

See also

• Googler's hyper-complex version of this: http://jsonnet.org/
• Mozillians' slightly less complex version of this: https://taskcluster.github.io/json-e/
• CloudFoundry's version abandoned due to complexity: https://github.com/mandelsoft/spiff
• Something that is really quite close to this (and if I had known...): https://selecttransform.github.io/site/

You can also use json query languages to build arbitrary structured outputs (i.e. they can generate templates where the parameters are the input, and the query is effectively the template). A non-exhaustive list:

• https://stedolan.github.io/jq/
• http://jmespath.org/
• http://goessner.net/articles/JsonPath/
• http://objectpath.org/