Skip to content

Latest commit

 

History

History
63 lines (50 loc) · 2.94 KB

README.md

File metadata and controls

63 lines (50 loc) · 2.94 KB
Raw

The repository at https://github.com/mustache/spec is the formal standard for Mustache. It defines both normal usage and edge-case behavior for libraries parsing the Mustache templating language (or a superset thereof).

The specification is developed as a series of YAML files, under the specs directory.

Versioning

This specification is being semantically versioned. Roughly described, major version changes will always represent backwards incompatible changes, minor version changes will always represent new language features and will be backwards compatible, and patch ('tiny') version changes will always be bug fixes. For the purposes of semantic versioning, the public API is the contents of the specs directory and the algorithm for testing against it.

Mustache implementations SHOULD report the most recent version of the spec (major and minor version numbers). If an implementation has support for any optional modules, they SHOULD indicate so with a remark attached to the version number (e.g. "vX.Y, including lambdas" or "v.X.Y+λ"). It is RECOMMENDED that implementations not supporting at least v1.0.0 of this spec refer to themselves as "Mustache-like", or "Mustache-inspired".

Alternate Formats

Since YAML is a reasonably complex format that not every language has good tools for working with, we also provide JSON versions of the specs on a best-effort basis.

These should be identical to the YAML specifications, but if you find the need to regenerate them, they can be trivially rebuilt by invoking rake build.

It is also worth noting that some specifications (notably, the lambda module) rely on YAML "tags" to denote special types of data (e.g. source code). Since JSON offers no way to denote this, a special key ("__tag__") is injected with the name of the tag as its value. See TESTING.md for more information about handling tagged data.

Optional Modules

Specification files beginning with a tilde (~) describe optional modules. As a guideline, a module may be a candidate for optionality when:

  • It does not affect the core syntax of the language.
  • It does not significantly affect the output of rendered templates.
  • It concerns implementation language features or data types that are not common to or core in every targeted language.
  • The lack of support by an implementation does not diminish the usage of Mustache in the target language.

As an example, the lambda module is primarily concerned with the handling of a particular data type (code). This is a type of data that may be difficult to support in some languages, and users of those languages will not see the lack as an 'inconsistency' between implementations.

Support for specific pragmas or syntax extensions, however, are best managed outside this core specification, as adjunct specifications.

Implementors are strongly encouraged to support any and all modules they are reasonably capable of supporting.