liquid/README.md

Go Liquid Template Parser

liquid is a pure Go implementation of Shopify Liquid templates, for use in gojekyll.

It supports a functional API for defining tags and filters. On the one hand, this isn't idiomatic Go. On the other hand, this made it possibly to quickly implement a boatload of Liquid and Jekyll filters that would otherwise have been onerous. The jury is still out…

• Go Liquid Template Parser
  • Status
  • Install
  • Contribute
    • Setup
    • Workflow
    • Working on the Parser and Lexer
  • References
  • Attribution
  • Other Implementations
    • Go
    • Other Languages
  • License

Status

This library is in its early days. IMO it's not sufficiently mature to be worth snapping off a versioned URL. In particular, the tag and filter extension API is likely to change.

• Basics
  • Literals
    • String Escapes
  • Variables
  • Operators (partial)
  • Arrays
  • Whitespace Control
• Tags
  • Comment
  • Control Flow
    • if/else/elsif
    • unless
    • case
      • when
      • else
  • Iteration
    • modifiers (limit, reversed, offset)
    • range
    • break, continue
    • loop variables
    • tablerow
    • cycle
  • Raw
  • Variables
    • Assign
    • Capture
• Filters
  • sort_natural, uniq, escape, truncatewords, url_decode, url_encode
  • everything else

Install

go get -u github.com/osteele/goliquid

Contribute

Setup

make setup

Workflow

go test ./...

Test just the scanner:

cd expressions
ragel -Z scanner.rl && go test

Preview the documentation:

godoc -http=:6060&
open http://localhost:6060/pkg/github.com/osteele/liquid/

Working on the Parser and Lexer

To work on the lexer, install Ragel. On macOS: brew install ragel.

Do this after editing scanner.rl or expressions.y:

go generate ./...

References

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

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. I submitted a couple of pull requests there.
• hownowstephen/go-liquid is a more recent entry.

After trying each of these, and looking at how to extend them, I concluded that I wasn't going to get very far without a parser generator. I also wanted an easy API for writing filters.

Other Languages

See Shopify's ports of Liquid to other environments.

License

MIT License