We did yet another fork of cbroglie/mustache because it does not appear to be maintained, and we need features that various forks implemented, but none gather them all:
- Custom lookup: if data implements the CustomLookup interface, its Lookup function is called to lookup a name, with the information of how the variable is used in the template. The former interface, without the usage information, is still supported as LegacyCustomLookup.
This implementation powers our rendering server Redner.
➜ ~ go install github.com/orus-io/mustache/cmd/mustache@latest
➜ ~ mustache
Usage:
mustache [data] template [flags]
Examples:
$ mustache data.yml template.mustache
$ cat data.yml | mustache template.mustache
$ mustache --layout wrapper.mustache data template.mustache
$ mustache --overide over.yml data.yml template.mustache
Flags:
-h, --help help for mustache
--layout a file to use as the layout template
--override a data.yml file whose definitions supercede data.yml
➜ ~This library is an implementation of the Mustache template language in Go.
mustache/spec contains the formal standard for Mustache, and it is included as a submodule (using v1.2.1) for testing compliance. All of the tests pass (big thanks to kei10in), with the exception of the null interpolation tests added in v1.2.1. There is experimental support for a subset of the optional lambda functionality (thanks to fromhut). The optional inheritance functionality has not been implemented.
For more information about mustache, check out the mustache project page or the mustache manual.
Also check out some example mustache files.
To install the CLI, run go install github.com/orus-io/mustache/cmd/mustache@latest. To use it in a program, run go get github.com/orus-io/mustache and use import "github.com/orus-io/mustache".
There are four main methods in this package:
Render(data string, context ...interface{}) (string, error)
RenderFile(filename string, context ...interface{}) (string, error)
ParseString(data string) (*Template, error)
ParseFile(filename string) (*Template, error)There are also two additional methods for using layouts (explained below); as well as several more that can provide a custom Partial retrieval.
The Render method takes a string and a data source, which is generally a map or struct, and returns the output string. If the template file contains an error, the return value is a description of the error. There's a similar method, RenderFile, which takes a filename as an argument and uses that for the template contents.
data, err := mustache.Render("hello {{c}}", map[string]string{"c": "world"})If you're planning to render the same template multiple times, you do it efficiently by compiling the template first:
tmpl, _ := mustache.ParseString("hello {{c}}")
var buf bytes.Buffer
for i := 0; i < 10; i++ {
tmpl.FRender(&buf, map[string]string{"c": "world"})
}For more example usage, please see mustache_test.go
mustache.go follows the official mustache HTML escaping rules. That is, if you enclose a variable with two curly brackets, {{var}}, the contents are HTML-escaped. For instance, strings like 5 > 2 are converted to 5 > 2. To use raw characters, use three curly brackets {{{var}}}.
It is a common pattern to include a template file as a "wrapper" for other templates. The wrapper may include a header and a footer, for instance. Mustache.go supports this pattern with the following two methods:
RenderInLayout(data string, layout string, context ...interface{}) (string, error)
RenderFileInLayout(filename string, layoutFile string, context ...interface{}) (string, error)The layout file must have a variable called {{content}}. For example, given the following files:
layout.html.mustache:
<html>
<head><title>Hi</title></head>
<body>
{{{content}}}
</body>
</html>template.html.mustache:
<h1>Hello World!</h1>A call to RenderFileInLayout("template.html.mustache", "layout.html.mustache", nil) will produce:
<html>
<head><title>Hi</title></head>
<body>
<h1>Hello World!</h1>
</body>
</html>Mustache.go has been extended to support a user-defined repository for mustache partials, instead of the default of requiring file-based templates.
Several new top-level functions have been introduced to take advantage of this:
func RenderPartials(data string, partials PartialProvider, context ...interface{}) (string, error)
func RenderInLayoutPartials(data string, layoutData string, partials PartialProvider, context ...interface{}) (string, error)
func ParseStringPartials(data string, partials PartialProvider) (*Template, error)
func ParseFilePartials(filename string, partials PartialProvider) (*Template, error)A PartialProvider is any object that responds to Get(string) (*Template,error), and two examples are provided- a FileProvider that
recreates the old behavior (and is indeed used internally for backwards
compatibility); and a StaticProvider alias for a map[string]string. Using
either of these is simple:
fp := &FileProvider{
Paths: []string{ "", "/opt/mustache", "templates/" },
Extensions: []string{ "", ".stache", ".mustache" },
}
tmpl, err := ParseStringPartials("This partial is loaded from a file: {{>foo}}", fp)
sp := StaticProvider(map[string]string{
"foo": "{{>bar}}",
"bar": "some data",
})
tmpl, err := ParseStringPartials("This partial is loaded from a map: {{>foo}}", sp)When a variable of a template is looked up in a context that implements the
CustomLookup interface, the Lookup method is called with the name of the
variable and the way it is used in the template:
type CustomLookup interface {
Lookup(name string, usage LookupUsage) (reflect.Value, error)
}The possible usages are:
UsageVariable: the variable is interpolated in a simple tag ({{name}})UsageSection: the variable is used as a section ({{#name}})UsageInvertedSection: the variable is used as an inverted section ({{^name}})UsagePathLead: the variable is a non-final element of a dotted name ({{name.sub}})
In a dotted name such as {{a.b.c}}, a and b are looked up with
UsagePathLead, and c with the usage of its tag (UsageVariable here, or
UsageSection for {{#a.b.c}}).
If Lookup returns an invalid reflect.Value, the lookup continues with the
default resolution (methods, struct fields and map keys), then with the parent
contexts.
The former version of the interface, which does not know the usage, is still supported:
type LegacyCustomLookup interface {
Lookup(name string) (reflect.Value, error)
}Mustache.go supports calling methods on objects, but you have to be aware of Go's limitations. For example, lets's say you have the following type:
type Person struct {
FirstName string
LastName string
}
func (p *Person) Name1() string {
return p.FirstName + " " + p.LastName
}
func (p Person) Name2() string {
return p.FirstName + " " + p.LastName
}While they appear to be identical methods, Name1 has a pointer receiver, and Name2 has a value receiver. Objects of type Person(non-pointer) can only access Name2, while objects of type *Person(person) can access both. This is by design in the Go language.
So if you write the following:
mustache.Render("{{Name1}}", Person{"John", "Smith"})It'll be blank. You either have to use &Person{"John", "Smith"}, or call Name2
- Variables
- Comments
- Change delimiter
- Sections (boolean, enumerable, and inverted)
- Partials