π liquid - Awesome Go Library for Template Engines
Go implementation of Shopify Liquid templates.
Detailed Description of liquid
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.
Installation
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>
See the API documentation for additional examples.
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!
Documentation
Status
These features of Shopify Liquid aren't implemented:
- Filter keyword parameters, for example
{{ image | img_url: '580x', scale: 2 }}
. [Issue #42] - Warn and lax error modes.
- Non-strict filters. An undefined filter is currently an error.
Drops
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.
Value Types
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
andnil
- These, and no other values, are recognized as false by
and
,or
,{% if %}
,{% elsif %}
, and{% case %}
.
- These, and no other values, are recognized as false by
- Integers
- (Only) integers can be used as array indices:
array[1]
;array[n]
, wherearray
has an array value andn
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) %}
wherestart
andend
have integer values.
- (Only) integers can be used as array indices:
- Integers and floats
- Integers and floats are converted to their join type for comparison:
1 == 1.0
evaluates totrue
. Similarly,int8(1)
,int16(1)
,uint8(1)
etc. are all==
. - [There is currently no special treatment of complex numbers.]
- Integers and floats are converted to their join type for comparison:
- Integers, floats, and strings
- Integers, floats, and strings can be used in comparisons
<
,>
,<=
,>=
. Integers and floats can be usefully compared with each other. Strings can be usefully compared with each other, but not with other values. Any other comparison, e.g.1 < "one"
,1 > "one"
, is always false.
- Integers, floats, and strings can be used in comparisons
- Arrays (and slices)
- An array can be indexed by integer value:
array[1]
;array[n]
wheren
has an integer value. - Arrays have
first
,last
, andsize
properties:array.first == array[0]
,array[array.size-1] == array.last
(wherearray.size > 0
)
- An array can be indexed by integer value:
- Maps
- A map can be indexed by a string:
hash["key"]
;hash[s]
wheres
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.
- A map can be indexed by a string:
- Drops
- A value
value
of a type that implements theDrop
interface acts as the valuevalue.ToLiquid()
. There is no guarantee about how many timesToLiquid
will be called. [This is in contrast to Shopify Liquid, which both uses a different interface for drops, and makes stronger guarantees.]
- A value
- 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 asvalue.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 field tagged e.g.
- 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.
- A public field of a struct can be accessed by its name:
[]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 astring
for all uses; for example,a < b
,a contains b
,hash[b]
will not behave as expected wherea
orb
is a[]byte
.
- A value of type
MapSlice
- An instance of
yaml.MapSlice
acts as a map. It implementsm.key
,m[key]
, andm.size
.
- An instance of
References
Contributing
Bug reports, test cases, and code contributions are more than welcome. Please refer to the contribution guidelines.
Contributors
Thanks goes to these wonderful people (emoji key):
Oliver Steele π» π π€ π π β οΈ | James Littlejohn π» π β οΈ | nsf π» β οΈ | Tobias Salzmann π» | Ben Doerr π» | Daniil Gentili π» | Carolyn Van Slyck π» |
Kimmo Lehto π» | Victor "Vito" Gama π» |
This project follows the all-contributors specification. Contributions of any kind welcome!
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
- 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