liquid/README.md

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.

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

Differences from Liquid

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

In brief, these aren't implemented:

• The cycle and tablerow tags
• {% case %}…{% else %} and {% when a or b %}
• The sort_natural, url_decode, and url_encode filters
• Loop ranges {% for a in 1...10 %}
• Error modes
• Whitespace control

These are opinionated differences that unlikely to change:

• The expression parser accepts parentheses in more locations
• The truncatewords filter leaves whitespace prior to the truncation point unchanged.

Stability Guarantees

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

Until it reaches 1.0, breaking changes will accompanied by a bump in the minor version, not the major version. For example, tag v0.2 is incompatible with v0.1 and (hypothetical) v0.1.1. (gopkg.in doesn't work this way, so you won't can't use gopkg.in/osteele/liquid.v0.1 to specify version 0.1.)

Even within these parameters, only the liquid package itself, and the sub-package APIs that it documents, are guaranteed stable. For example, render.Context is documented as the parameter type for tag definitions; it therefore has the same stability guarantees as liquid.Engine and liquid.Template. Other "public" definitions in render and in other sub-packages are intended only for use in other packages in this repo; they are not generally stable between even sub-minor releases.

Install

go get gopkg.in/osteele/liquid.v0.2-- latest snapshot

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

Usage

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>

Command-Line tool

go install gopkg.in/osteele/liquid.v0/cmd/liquid installs a command-line liquid program in your GO bin. 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
gopkg.in/yaml.v2	Canonical	YAML support (for printing parse trees)	Apache License 2.0
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