liquid

README

Liquid Template Parser

liquid is a Go implementation of Shopify Liquid templates. It was developed for use in the Gojekyll static site generator.

“Any sufficiently complicated C or Fortran program contains an ad-hoc, informally-specified, bug-ridden, slow implementation of half of Common Lisp.” – Philip Greenspun

• Liquid Template Parser
  • Differences from Liquid
  • Stability
  • Install
  • Usage
    • Command-Line tool
  • Contributing
  • References
  • Attribution
  • Other Implementations
    • Go
    • Other Languages
  • License

Differences from Liquid

The feature parity board lists differences from Liquid.

In brief, these aren't implemented:

• Warn and lax error modes.
• Non-strict filters. An undefined filter is currently an error.
• Strict variables. An undefined variable is not an error.

Stability

This library is at an early stage of development. It has been mostly used by its author.

Only the liquid package itself, and the sub-package types that are used in that top-level package, are guaranteed stable. For example, render.Context is documented as the parameter type for tag definitions; it therefore won't change incompatibly with minor versions.

Install

go get gopkg.in/osteele/liquid.v1 # latest snapshot

go get -u github.com/osteele/goliquid # development version

Usage

engine := liquid.NewEngine()
template := `<h1>{{ page.title }}</h1>`
bindings := map[string]interface{}{
    "page": map[string]string{
        "title": "Introduction",
    },
}
out, err := engine.ParseAndRenderString(template, bindings)
if err != nil { log.Fatalln(err) }
fmt.Println(out)
// Output: <h1>Introduction</h1>

Command-Line tool

go install gopkg.in/osteele/liquid.v0/cmd/liquid installs a command-line liquid executable. This is intended to make it easier to create test cases for bug reports.

$ liquid --help
usage: liquid [FILE]
$ echo '{{ "Hello World" | downcase | split: " " | first | append: "!"}}' | liquid
hello!

Contributing

Bug reports, test cases, and code contributions are more than welcome. Please refer to the contribution guidelines.

References

• Shopify.github.io/liquid
• Liquid for Designers
• Liquid for Programmers
• Help.shopify.com goes into more detail, but includes features that aren't present in core Liquid as used by Jekyll.

Attribution

Package	Author	Description	License
Ragel	Adrian Thurston	scanning expressions	MIT
gopkg.in/yaml.v2	Canonical	YAML support (for printing parse trees)	Apache License 2.0

Michael Hamrah's Lexing with Ragel and Parsing with Yacc using Go was essential to understanding go yacc.

The original Liquid engine, of course, for the design and documentation of the Liquid template language. Many of the tag and filter test cases are taken directly from the Liquid documentation.

Other Implementations

Go

• karlseguin/liquid is a dormant implementation that inspired a lot of forks.
• acstech/liquid is a more active fork of Karl Seguin's implementation.
• hownowstephen/go-liquid

Other Languages

See Shopify's ports of Liquid to other environments.

License

MIT License

Documentation

Overview

Package liquid is a pure Go implementation of Shopify Liquid templates, developed for use in https://github.com/osteele/gojekyll.

See the project README https://github.com/osteele/liquid for additional information and implementation status.

The liquid package itself is versioned in gopkg.in. Subpackages have no compatibility guarantees. Except where specifically documented, the “public” entities of subpackages are intended only for use by the liquid package and its subpackages.

Example

engine := NewEngine()
source := `<h1>{{ page.title }}</h1>`
bindings := map[string]interface{}{
	"page": map[string]string{
		"title": "Introduction",
	},
}
out, err := engine.ParseAndRenderString(source, bindings)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(out)

Output:

<h1>Introduction</h1>

Index

• func FromDrop(object interface{}) interface{}
• type Bindings
• type Drop
• type Engine
  • func NewEngine() *Engine
  • func (e *Engine) ParseAndRender(source []byte, b Bindings) ([]byte, SourceError)
  • func (e *Engine) ParseAndRenderString(source string, b Bindings) (string, SourceError)
  • func (e *Engine) ParseTemplate(source []byte) (*Template, SourceError)
  • func (e *Engine) ParseTemplateLocation(source []byte, path string, line int) (*Template, SourceError)
  • func (e *Engine) RegisterBlock(name string, td Renderer)
  • func (e *Engine) RegisterFilter(name string, fn interface{})
  • func (e *Engine) RegisterTag(name string, td Renderer)
• type Renderer
• type SourceError
• type Template
  • func (t *Template) Render(vars Bindings) ([]byte, SourceError)
  • func (t *Template) RenderString(b Bindings) (string, SourceError)

Examples

• Package
• Drop
• Engine.ParseAndRenderString
• Engine.ParseTemplate
• Engine.RegisterBlock
• Engine.RegisterFilter
• Engine.RegisterFilter (Optional_argument)
• Engine.RegisterTag

Functions

func FromDrop

func FromDrop(object interface{}) interface{}

FromDrop returns returns object.ToLiquid() if object's type implement this function; else the object itself.

Types

type Bindings

type Bindings map[string]interface{}

Bindings is a map of variable names to values.

Clients need not use this type. It is used solely for documentation. Callers can use instances of map[string]interface{} itself as argument values to functions declared with this parameter type.

type Drop

type Drop interface {
	ToLiquid() interface{}
}

Drop indicates that the object will present to templates as its ToLiquid value.

Example

// type redConvertible struct{}
//
// func (c redConvertible) ToLiquid() interface{} {
// 	return "red"
// }
engine := NewEngine()
bindings := map[string]interface{}{
	"drop": redConvertible{},
}
template := `{{ drop }}`
out, err := engine.ParseAndRenderString(template, bindings)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(out)

Output:

red

type Engine

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

An Engine parses template source into renderable text.

An engine can be configured with additional filters and tags.

func NewEngine

func NewEngine() *Engine

NewEngine returns a new Engine.

func (*Engine) ParseAndRender

func (e *Engine) ParseAndRender(source []byte, b Bindings) ([]byte, SourceError)

ParseAndRender parses and then renders the template.

func (*Engine) ParseAndRenderString

func (e *Engine) ParseAndRenderString(source string, b Bindings) (string, SourceError)

ParseAndRenderString is a convenience wrapper for ParseAndRender, that takes string input and returns a string.

Example

engine := NewEngine()
source := `{{ hello | capitalize | append: " Mundo" }}`
bindings := map[string]interface{}{"hello": "hola"}
out, err := engine.ParseAndRenderString(source, bindings)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(out)

Output:

Hola Mundo

func (*Engine) ParseTemplate

func (e *Engine) ParseTemplate(source []byte) (*Template, SourceError)

ParseTemplate creates a new Template using the engine configuration.

Example

engine := NewEngine()
source := `{{ hello | capitalize | append: " Mundo" }}`
bindings := map[string]interface{}{"hello": "hola"}
tpl, err := engine.ParseTemplate([]byte(source))
if err != nil {
	log.Fatalln(err)
}
out, err := tpl.RenderString(bindings)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(out)

Output:

Hola Mundo

func (*Engine) ParseTemplateLocation

func (e *Engine) ParseTemplateLocation(source []byte, path string, line int) (*Template, SourceError)

ParseTemplateLocation is the same as ParseTemplate, except that the source location is used for error reporting and for the {% include %} tag.

The path and line number are used for error reporting. The path is also the reference for relative pathnames in the {% include %} tag.

func (*Engine) RegisterBlock

func (e *Engine) RegisterBlock(name string, td Renderer)

RegisterBlock defines a block e.g. {% tag %}…{% endtag %}.

Example

engine := NewEngine()
engine.RegisterBlock("length", func(c render.Context) (string, error) {
	s, err := c.InnerString()
	if err != nil {
		return "", err
	}
	n := len(s)
	return fmt.Sprint(n), nil
})

template := `{% length %}abc{% endlength %}`
out, err := engine.ParseAndRenderString(template, emptyBindings)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(out)

Output:

3

func (*Engine) RegisterFilter

func (e *Engine) RegisterFilter(name string, fn interface{})

RegisterFilter defines a Liquid filter, for use as `{{ value | my_filter }}` or `{{ value | my_filter: arg }}`.

A filter is a function that takes at least one input, and returns one or two outputs. If it returns two outputs, the second must have type error.

Examples:

* https://github.com/osteele/liquid/blob/master/filters/filters.go

* https://github.com/osteele/gojekyll/blob/master/filters/filters.go

Example

engine := NewEngine()
engine.RegisterFilter("has_prefix", strings.HasPrefix)
template := `{{ title | has_prefix: "Intro" }}`
bindings := map[string]interface{}{
	"title": "Introduction",
}
out, err := engine.ParseAndRenderString(template, bindings)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(out)

Output:

true

Example (Optional_argument)

engine := NewEngine()
// func(a, b int) int) would default the second argument to zero.
// Then we can't tell the difference between {{ n | inc }} and
// {{ n | inc: 0 }}. A function in the parameter list has a special
// meaning as a default parameter.
engine.RegisterFilter("inc", func(a int, b func(int) int) int {
	return a + b(1)
})
template := `10 + 1 = {{ m | inc }}; 20 + 5 = {{ n | inc: 5 }}`
bindings := map[string]interface{}{
	"m": 10,
	"n": "20",
}
out, err := engine.ParseAndRenderString(template, bindings)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(out)

Output:

10 + 1 = 11; 20 + 5 = 25

func (*Engine) RegisterTag

func (e *Engine) RegisterTag(name string, td Renderer)

RegisterTag defines a tag e.g. {% tag %}.

Further examples are in https://github.com/osteele/gojekyll/blob/master/tags/tags.go

Example

engine := NewEngine()
engine.RegisterTag("echo", func(c render.Context) (string, error) {
	return c.TagArgs(), nil
})
template := `{% echo hello world %}`
out, err := engine.ParseAndRenderString(template, emptyBindings)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(out)

Output:

hello world

type Renderer

type Renderer func(render.Context) (string, error)

A Renderer returns the rendered string for a block. This is the type of a tag definition.

See the examples at Engine.RegisterTag and Engine.RegisterBlock.

type SourceError

type SourceError interface {
	error
	Cause() error
	Path() string
	LineNumber() int
}

SourceError records an error with a source location and optional cause.

type Template

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

A Template is a compiled Liquid template. It knows how to evaluate itself within a variable binding environment, to create a rendered byte slice.

Use Engine.ParseTemplate to create a template.

func (*Template) Render

func (t *Template) Render(vars Bindings) ([]byte, SourceError)

Render executes the template with the specified variable bindings.

func (*Template) RenderString

func (t *Template) RenderString(b Bindings) (string, SourceError)

RenderString is a convenience wrapper for Render, that has string input and output.