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.

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

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

Status

This library is in early development. There's probably lots of corner cases, and the API (especially around defining tags) may still change.

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

Other Differences

These will change:

• I haven't investigated the interaction of loop reversed, limit, and offset, and whether it matters which order they're specified, in Shopify Liquid.
• This implementation doesn't parse very many date formats. I have any idea for this; talk to me if you're interested in implementing it.
• Identifiers can include hyphens.
• contains isn't implemented on hashes.
• contains doesn't stringify its argument.
• The nil constant isn't implemented.

These might not:

• This parser accepts parentheses in places where Shopify Liquid does not.
• else and elsif work inside of unless

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