liquid

package module
v1.2.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 18, 2017 License: MIT Imports: 6 Imported by: 0

README

Liquid Template Parser

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

Compatibility

These features of Shopify Liquid 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.

Drops have a different design from the Shopify (Ruby) implementation. A Ruby drop sets liquid_attributes to a list of attributes that are exposed to Liquid. A Go drop implements ToLiquid() interface{}, that returns a proxy object. Conventionally, the proxy is a map or struct that defines the exposed properties. See http://godoc.org/github.com/osteele/liquid#Drop for additional information.

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, if ever, until at least version 2 (at which point gopkg.in/osteele/liquid.v1 will continue to pin to the v1 implementation).

Install

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

go get -u github.com/osteele/liquid # 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!

Values

Render and friends take a Bindings parameter. This is a map of string to interface{}, that associates template variable names with Go values.

Any Go value can be used as a variable value. These values have special meaning:

  • false and nil
    • These, and no other values, are recognized as false by and, or, {% if %}, {% elsif %}, and {% case %}`.
  • Integers
    • (Only) integers can be used as array indices: array[1]; array[n], where array has an array value and n has an integer value.
    • (Only) integers can be used as the endpoints of a range: {% for item in (1..5) %}, {% for item in (start..end) %} where start and end have integer values.
  • Integers and floats
    • Integers and floats are converted to their join type for comparison: 1 == 1.0 evaluates to true. Similarly, int8(1), int16(1), uint8(1) etc. are all ==.
    • [There is currently no special treatment of complex numbers.]
  • Integers, floats, and strings
    • Integers, floats, and strings can be used in comparisons <, >, <=, >=. Integers and floats can be meaningfully compared with each other. Strings can be meaningfully compared with each other but not with other values. Any other comparison, e.g. 1 < "one", 1 > "one", will always be false.
  • Arrays (and slices)
    • An array can be indexed by integer array[1]; array[n] where n has an integer value.
    • Arrays have first, last, and size properties: array.first == array[0], array[array.size-1] == array.last (where array.size > 0)
  • Maps
    • A map can be indexed by a string: hash[“key”]; hash[s] where s has a string value
    • A map can be accessed using property syntax hash.key
    • Maps have a special size property, that returns the size of the map.
  • Drops
    • A value value of a type that implements the Drop interface acts as the value value.ToLiquid(). There is no guarantee about how many times ToLiquid will be called. [This is in contrast to Shopify Liquid, which both uses a different interface for drops, and makes stronger guarantees.]
  • Structs
    • A public field of a struct can be accessed by its name: value.FieldName, value[“fieldName”].
      • A field tagged e.g. liquid:”name” is accessed as value.name instead.
      • If the value of the field is a function that takes no arguments and returns either one or two arguments, accessing it invokes the function, and the value of the property is its first return value.
      • If the second return value is non-nil, accessing the field panics instead.
    • A function defined on a struct can be accessed by function name e.g. value.Func, value[“Func”].
      • The same rules apply as to accessing a func-valued public field.
    • Note that despite being array- and map-like, structs do not have a special value.size property.
  • []byte
    • A value of type []byte is rendered as the corresponding string, and presented as a string to filters that expect one. A []byte is not (currently) equivalent to a string for all uses; for example, a < b, a contains b, hash[b] will not behave as expected where a or b is a []byte.
  • MapSlice
    • An instance of yaml.MapSlice acts as a map. It implements m.key, m[key], and m.size.

Contributing

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

References

Attribution

Package Author Description License
Ragel Adrian Thurston scanning expressions MIT
gopkg.in/yaml.v2 Canonical MapSlice 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
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

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func FromDrop added in v1.0.0

func FromDrop(object interface{}) interface{}

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

func IterationKeyedMap added in v1.2.3

func IterationKeyedMap(m map[string]interface{}) tags.IterationKeyedMap

IterationKeyedMap returns a map whose {% for %} tag iteration values are its keys, instead of [key, value] pairs. Use this to create a Go map with the semantics of a Ruby struct drop.

Example
vars := map[string]interface{}{
	"map":       map[string]interface{}{"a": 1},
	"keyed_map": IterationKeyedMap(map[string]interface{}{"a": 1}),
}
engine := NewEngine()
out, err := engine.ParseAndRenderString(
	`{% for k in map %}{{ k[0] }}={{ k[1] }}.{% endfor %}`, vars)
if err != nil {
	log.Fatal(err)
}
fmt.Println(out)
out, err = engine.ParseAndRenderString(
	`{% for k in keyed_map %}{{ k }}={{ keyed_map[k] }}.{% endfor %}`, vars)
if err != nil {
	log.Fatal(err)
}
fmt.Println(out)
Output:

a=1.
a=1.

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 (Map)
// type redConvertible struct{}
//
// func (c redConvertible) ToLiquid() interface{} {
// 	return map[string]interface{}{
// 		"color": "red",
// 	}
// }
engine := NewEngine()
bindings := map[string]interface{}{
	"car": redConvertible{},
}
template := `{{ car.color }}`
out, err := engine.ParseAndRenderString(template, bindings)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(out)
Output:

red
Example (Struct)
// type car struct{ color, model string }
//
// func (c car) ToLiquid() interface{} {
// 	return carDrop{c.model, c.color}
// }
//
// type carDrop struct {
// 	Model string
// 	Color string `liquid:"color"`
// }
//
// func (c carDrop) Drive() string {
// 	return "AWD"
// }

engine := NewEngine()
bindings := map[string]interface{}{
	"car": car{"blue", "S85"},
}
template := `{{ car.color }} {{ car.Drive }} Model {{ car.Model }}`
out, err := engine.ParseAndRenderString(template, bindings)
if err != nil {
	log.Fatalln(err)
}
fmt.Println(out)
Output:

blue AWD Model S85

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) Delims added in v1.2.1

func (e *Engine) Delims(objectLeft, objectRight, tagLeft, tagRight string) *Engine

Delims sets the action delimiters to the specified strings, to be used in subsequent calls to ParseTemplate, ParseTemplateLocation, ParseAndRender, or ParseAndRenderString. An empty delimiter stands for the corresponding default: objectLeft = {{, objectRight = }}, tagLeft = {% , tagRight = %}

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) ParseString added in v1.2.1

func (e *Engine) ParseString(source string) (*Template, SourceError)

ParseString creates a new Template using the engine configuration.

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.ParseString(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 added in v1.0.0

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 added in v0.2.0

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

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

SourceError does not depend on, but is compatible with, the causer interface of https://github.com/pkg/errors.

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.

Directories

Path Synopsis
cmd
liquid
Package main defines a command-line interface to the Liquid engine.
Package main defines a command-line interface to the Liquid engine.
Package evaluator is an interim internal package that forwards to package values.
Package evaluator is an interim internal package that forwards to package values.
Package expressions is an internal package that parses and evaluates the expression language.
Package expressions is an internal package that parses and evaluates the expression language.
Package filters is an internal package that defines the standard Liquid filters.
Package filters is an internal package that defines the standard Liquid filters.
Package parser is an internal package that parses template source into an abstract syntax tree.
Package parser is an internal package that parses template source into an abstract syntax tree.
Package render is an internal package that renders a compiled template parse tree.
Package render is an internal package that renders a compiled template parse tree.
Package tags is an internal package that defines the standard Liquid tags.
Package tags is an internal package that defines the standard Liquid tags.
Package values is an internal package that defines methods such as sorting, comparison, and type conversion, that apply to interface types.
Package values is an internal package that defines methods such as sorting, comparison, and type conversion, that apply to interface types.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL