liquid

README

Go Liquid Template Parser

“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 ports Shopify Liquid templates to Go. It was developed for use in gojekyll.

liquid provides a functional API for defining tags and filters. See examples here, here, and here.

• Go Liquid Template Parser
  • Status
  • Differences from Liquid
  • Install
  • Contributing
  • References
  • Attribution
  • Other Implementations
    • Go
    • Other Languages
  • License

Status

This library is at an early stage of development. There's probably lots of corner cases, and the API for defining tags may still change.

Differences from Liquid

Refer to the feature parity board for a list of known differences from Liquid.

Other differences, that might not change:

• This implementation is probably more liberal in where it accepts parentheses.
• Two hashes with the same keys and values, or two drops that return deeply equal hashes, are equal for purposes of uniq. I don't know if it's practical to fix this.

Install

go get -u github.com/osteele/goliquid

make install install a command-line liquid program in your GO bin. This is intended to make it easier to create test cases for bug reports. Run liquid --help for help.

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
gopkg.in/yaml.v2	Canonical	YAML support (for printing parse trees)	Apache License 2.0
jeffjen/datefmt	Jeffrey Jen	Go bindings to GNU strftime and strptime	MIT
Ragel	Adrian Thurston	scanning expressions	MIT

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, for use in https://github.com/osteele/gojekyll.

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

Note that the API for this package is not frozen. It is *especially* likely that subpackage APIs will change drastically. Don't use anything except from a subpackage except render.Context.

Example

engine := 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>

Index

• func IsTemplateError(err error) bool
• type Bindings
• type Drop
• type Engine
  • func NewEngine() Engine
• type Renderer
• type Template

Examples

• Package
• Drop

Functions

func IsTemplateError

func IsTemplateError(err error) bool

IsTemplateError returns a boolean indicating whether the error indicates an error in the template. All other errors are either errors in added tags or filters, or errors the implementation of this package.

Use this to avoid coding the specific types of subpackage errors, which are likely to change.

Types

type Bindings

type Bindings map[string]interface{}

Bindings is a map of variable names to values.

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 interface {
	// RegisterFilter defines a filter function e.g. {{ value | filter: arg }}.
	RegisterFilter(name string, fn interface{})
	// RegisterTag defines a tag function e.g. {% tag %}.
	RegisterTag(string, Renderer)
	RegisterBlock(string, Renderer)

	ParseTemplate([]byte) (Template, error)
	// ParseAndRender parses and then renders the template.
	ParseAndRender([]byte, Bindings) ([]byte, error)
	// ParseAndRenderString is a convenience wrapper for ParseAndRender, that has string input and output.
	ParseAndRenderString(string, Bindings) (string, error)
}

An Engine parses template source into renderable text.

An engine can be configured with additional filters and tags.

Filters

RegisterFilter defines a Liquid filter.

A filter is any function that takes at least one input, and returns one or two outputs. If it returns two outputs, the second must be an error.

func NewEngine

func NewEngine() Engine

NewEngine returns a new template engine.

type Renderer

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

A Renderer returns the rendered string for a block.

type Template

type Template interface {
	// Render executes the template with the specified bindings.
	Render(Bindings) ([]byte, error)
	// RenderString is a convenience wrapper for Render, that has string input and output.
	RenderString(Bindings) (string, error)
	SetSourcePath(string)
	SetSourceLocation(string, int)
}

A Template renders a template according to scope.