mustache

README

Mustache template engine for Go

---

Why a fork?

I forked cbroglie/mustache because it does not appear to be maintained, and I wanted to add the following functionality:

• Add support for JSON and plain text escaping modes (for example, for templating e-mail, or JSON messages for Slack notifications).
• Add a previously submitted patch for lambda support.
• Add a fluent API.

I also wanted to clear up some security holes, including two found by fuzzing.

The goal is for this to be a robust, performant, standards-compliant Mustache template engine for Go, and for it to be safe to allow end users to supply templates. Extensions to the templating language are generally not desired. If you want more than Mustache offers, consider a Handlebars implementation such as Mario.

---

CLI overview

% go get github.com/RumbleDiscovery/mustache/...
% 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
%

---

Package overview

This library is an implementation of the Mustache template language in Go.

Mustache spec compliance

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. The optional inheritance and lambda support has not been fully implemented.

---

Documentation

For more information about mustache, check out the mustache project page or the mustache manual.

Also check out some example mustache files.

---

Installation

To install mustache.go, simply run go get github.com/RumbleDiscovery/mustache/.... To use it in a program, use import "github.com/RumbleDiscovery/mustache"

---

Usage

Starting with version 2, a fluent API is provided, and compilation and rendering of templates is performed as separate steps, with separate error returns. This makes it easier to distinguish between syntactically invalid templates, and errors at render time.

First, use mustache.New() to obtain a Compiler. You can then set options on the compiler:

cmpl := mustache.New()
cmpl.WithErrors(true)
cmpl.WithPartials(&FileProvider{
	Paths: []string{"/app/templates"},
	Extensions: []string{".html", ".mustache"}
})
cmpl.WithEscapeMode(mustache.EscapeHTML)

Then you can use the compiler you've configured to compile your template(s):

tmpl1, err := cmpl.CompileString("This is {{mustache}}")
tmpl2, err := cmpl.CompileFile("main.mustache")

Finally, you can render the compiled templates using any number of contextual data objects, generally expected to be map[string]interface{} or a struct:

output, err := tmpl1.Render(map[string]string{"mustache":"awesome!"})

The compiler options can be chained together:

tmpl, err := mustache.New().WithErrors(true).CompileString("This is {{mustache}}")

There are also two additional methods for using layouts (explained below); as well as several more that can provide a custom Partial retrieval.

Unlike in the v1 API, the defaults for the compiler are intended to be safe, with no partial support -- you have to provide a PartialProvider explicitly if you want to use partials. So by default you get:

• No partials
• No errors when data is missing from the context
• HTML escaping

There are no longer functions to render a template without compiling to a *Template object. The engine always compiles even if you throw the template away when you're done with it, so there's no speed benefit to having a non-compiling option.

For more example usage, please see mustache_test.go

---

Escaping

By default, 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}}}.

This implementation of Mustache also allows you to run the engine in JSON mode, in which case the standard JSON quoting rules are used. To do this, use .WithEscapeMode(mustache.JSON) to set the escape mode on the compiler. Note that the JSON escaping rules are different from the rules used by Go's text/template.JSEscape, and do not guarantee that the JSON will be safe to include as part of an HTML page.

A third mode of mustache.Raw allows the use of Mustache templates to generate plain text, such as e-mail messages and console application help text.

---

Layouts

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 method:

(contentTemplate *Template) RenderInLayout(layoutTemplate *Template, context ...interface{}) (string, error)

The layout 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>

...and suitable code to load and compile them:

template, _ := mustache.New().CompileFile("template.html.mustache")
layout, _ := mustache.New().CompileFile("layout.html.mustache")

A call to template.RenderInLayout(layout) will produce:

<html>
<head><title>Hi</title></head>
<body>
<h1>Hello World!</h1>
</body>
</html>

---

Custom PartialProvider

Mustache supports user-defined repositories for mustache partials.

A PartialProvider is any object that responds to Get(string) (*Template,error), and two examples are provided -- a FileProvider that loads files from disk, 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 := mustache.New().WithPartials(fp).CompileString("This partial is loaded from a file: {{>foo}}")

sp := StaticProvider(map[string]string{
  "foo": "{{>bar}}",
  "bar": "some data",
})

tmpl, err := mustache.New().WithPartials(sp).CompileString("This partial is loaded from a map: {{>foo}}", sp)

---

A note about method receivers

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:

tmpl.Render("{{Name1}}", Person{"John", "Smith"})

It'll be blank. You either have to use &Person{"John", "Smith"}, or call Name2

Supported features

• Variables
• Comments
• Change delimiter
• Sections (boolean, enumerable, and inverted)
• Partials
• Lambdas
• HTML, JSON or plain text output

Documentation

Index

• Constants
• func JSONEscape(dest io.Writer, data string) error
• type Compiler
  • func New() *Compiler
  • func (r *Compiler) CompileFile(filename string) (*Template, error)
  • func (r *Compiler) CompileString(data string) (*Template, error)
  • func (r *Compiler) WithErrors(b bool) *Compiler
  • func (r *Compiler) WithEscapeMode(m EscapeMode) *Compiler
  • func (r *Compiler) WithPartials(pp PartialProvider) *Compiler
• type EscapeMode
• type FileProvider
  • func (fp *FileProvider) Get(name string) (string, error)
• type PartialProvider
• type RenderFn
• type StaticProvider
  • func (sp *StaticProvider) Get(name string) (string, error)
• type Tag
• type TagType
  • func (t TagType) String() string
• type Template
  • func (tmpl *Template) FRenderInLayout(out io.Writer, layout *Template, context ...interface{}) error
  • func (tmpl *Template) Frender(out io.Writer, context ...interface{}) error
  • func (tmpl *Template) Render(context ...interface{}) (string, error)
  • func (tmpl *Template) RenderInLayout(layout *Template, context ...interface{}) (string, error)
  • func (tmpl *Template) Tags() []Tag

Constants

const (
	SkipWhitespaceTagTypes = "#^/<>=!"
)

Skip all whitespaces apeared after these types of tags until end of line if the line only contains a tag and whitespaces.

Functions

func JSONEscape

func JSONEscape(dest io.Writer, data string) error

Types

type Compiler

type Compiler struct {
	// contains filtered or unexported fields
}

func New

func New() *Compiler

func (*Compiler) CompileFile

func (r *Compiler) CompileFile(filename string) (*Template, error)

CompileFile compiles a Mustache template from a file.

func (*Compiler) CompileString

func (r *Compiler) CompileString(data string) (*Template, error)

CompileString compiles a Mustache template from a string.

func (*Compiler) WithErrors

func (r *Compiler) WithErrors(b bool) *Compiler

WithErrors enables errors when there is a missing data object referred to by the template, a missing partial, or a missing partial provider to handle a partial. Otherwise, errors are ignored and result in empty strings in the output.

func (*Compiler) WithEscapeMode

func (r *Compiler) WithEscapeMode(m EscapeMode) *Compiler

WithEscapeMode sets the output mode to either HTML, JSON or raw (plain text). The default is HTML.

func (*Compiler) WithPartials

func (r *Compiler) WithPartials(pp PartialProvider) *Compiler

WithPartials adds a partial provider and enables support for partials.

type EscapeMode

type EscapeMode int

EscapeMode indicates what sort of escaping to perform in template output. EscapeHTML is the default, and assumes the template is producing HTML. EscapeJSON switches to JSON escaping, for use cases such as generating Slack messages. Raw turns off escaping, for situations where you are absolutely sure you want plain text.

const (
	EscapeHTML EscapeMode = iota // Escape output as HTML (default)
	EscapeJSON                   // Escape output as JSON
	Raw                          // Do not escape output (plain text mode)
)

type FileProvider

type FileProvider struct {
	Paths      []string
	Extensions []string
	Unsafe     bool
}

FileProvider implements the PartialProvider interface by providing partials drawn from a filesystem. When a partial named `NAME` is requested, FileProvider searches each listed path for a file named as `NAME` followed by any of the listed extensions. The default for `Paths` is to search the current working directory. The default for `Extensions` is to examine, in order, no extension; then ".mustache"; then ".stache". If Unsafe is set, partial names are allowed to begin with '.' or '..' after cleaning, meaning they can potentially refer to files outside any of the listed directory paths.

func (*FileProvider) Get

func (fp *FileProvider) Get(name string) (string, error)

Get accepts the name of a partial and returns the parsed partial.

type PartialProvider

type PartialProvider interface {
	// Get accepts the name of a partial and returns the parsed partial, if it could be found; a valid but empty
	// template, if it could not be found; or nil and error if an error occurred (other than an inability to find
	// the partial).
	Get(name string) (string, error)
}

PartialProvider comprises the behaviors required of a struct to be able to provide partials to the mustache rendering engine.

type RenderFn

type RenderFn func(text string) (string, error)

RenderFn is the signature of a function which can be called from a lambda section

type StaticProvider

type StaticProvider struct {
	Partials map[string]string
}

StaticProvider implements the PartialProvider interface by providing partials drawn from a map, which maps partial name to template contents.

func (*StaticProvider) Get

func (sp *StaticProvider) Get(name string) (string, error)

Get accepts the name of a partial and returns the parsed partial.

type Tag

type Tag interface {
	// Type returns the type of the tag.
	Type() TagType
	// Name returns the name of the tag.
	Name() string
	// Tags returns any child tags. It panics for tag types which cannot contain
	// child tags (i.e. variable tags).
	Tags() []Tag
}

Tag represents the different mustache tag types.

Not all methods apply to all kinds of tags. Restrictions, if any, are noted in the documentation for each method. Use the Type method to find out the type of tag before calling type-specific methods. Calling a method inappropriate to the type of tag causes a run time panic.

type TagType

type TagType uint

A TagType represents the specific type of mustache tag that a Tag represents. The zero TagType is not a valid type.

const (
	Invalid TagType = iota
	Variable
	Section
	InvertedSection
	Partial
)

Defines representing the possible Tag types.

func (TagType) String

func (t TagType) String() string

type Template

type Template struct {
	// contains filtered or unexported fields
}

Template represents a compiled mustache template which can be used to render data.

func (*Template) FRenderInLayout

func (tmpl *Template) FRenderInLayout(out io.Writer, layout *Template, context ...interface{}) error

FRenderInLayout uses the given data source - generally a map or struct - to render the compiled templated a loayout "wrapper" template to an io.Writer.

func (*Template) Frender

func (tmpl *Template) Frender(out io.Writer, context ...interface{}) error

Frender uses the given data source - generally a map or struct - to render the compiled template to an io.Writer.

func (*Template) Render

func (tmpl *Template) Render(context ...interface{}) (string, error)

Render uses the given data source - generally a map or struct - to render the compiled template and return the output.

func (*Template) RenderInLayout

func (tmpl *Template) RenderInLayout(layout *Template, context ...interface{}) (string, error)

RenderInLayout uses the given data source - generally a map or struct - to render the compiled template and layout "wrapper" template and return the output.

func (*Template) Tags

func (tmpl *Template) Tags() []Tag

Tags returns the mustache tags for the given template.