Repository files navigation

liquid is a pure Go implementation ofShopify Liquidtemplates. It was developed for use in theGojekyll port of the Jekyll static sitegenerator.

• Liquid Template Parser
  • Installation
  • Usage
    • Command-Line tool
  • Documentation
    • Status
    • Drops
    • Value Types
    • Template Store
    • References
  • Contributing
    • Contributors
    • Attribution
  • Other Implementations
    • Go
    • Other Languages
  • License

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

go get -u github.com/osteele/liquid # development version

engine:=liquid.NewEngine()template:=`<h1>{{ page.title }}</h1>`bindings:=map[string]any{"page":map[string]string{"title":"Introduction",    },}out,err:=engine.ParseAndRenderString(template,bindings)iferr!=nil {log.Fatalln(err) }fmt.Println(out)// Output: <h1>Introduction</h1>

See theAPI documentation for additional examples.

go install gopkg.in/osteele/liquid.v0/cmd/liquid installs a command-lineliquid executable. This is intended to make it easier to create test cases forbug reports.

$ liquid --helpusage: liquid [FILE]$echo'{{ "Hello World" | downcase | split: " " | first | append: "!"}}'| liquidhello!

These features of Shopify Liquid aren't implemented:

• Filter keyword parameters, for example{{ image | img_url: '580x', scale: 2 }}. [Issue #42]
• Warn and laxerror modes.
• Non-strict filters. An undefined filter is currently an error.

Drops have a different design from the Shopify (Ruby) implementation. A Rubydrop setsliquid_attributes to a list of attributes that are exposed toLiquid. A Go drop implementsToLiquid() any, that returns a proxyobject. Conventionally, the proxy is amap orstruct that defines theexposed properties. Seehttp://godoc.org/github.com/osteele/liquid#Drop foradditional information.

Render and friends take aBindings parameter. This is a map ofstring toany, 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 byand,or,{% if %},{% elsif %}, and{% case %}.
• 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 haveinteger values.
• 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, floats, and strings
  • Integers, floats, and strings can be used in comparisons<,>,<=,>=. Integers and floats can be usefully compared with each other. Stringscan be usefully compared with each other, but not with other values. Anyother comparison, e.g.1 < "one",1 > "one", is always false.
• Arrays (and slices)
  • An array can be indexed by integer value:array[1];array[n] wherenhas an integer value.
  • Arrays havefirst,last, andsize properties:array.first == array[0],array[array.size-1] == array.last (wherearray.size > 0)
• Maps
  • A map can be indexed by a string:hash["key"];hash[s] wheres has astring value
  • A map can be accessed using property syntaxhash.key
  • Maps have a specialsize property, that returns the size of the map.
• Drops
  • A valuevalue of a type that implements theDrop interface acts as thevaluevalue.ToLiquid(). There is no guarantee about how many timesToLiquid will be called. [This is in contrast to Shopify Liquid, whichboth 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 asvalue.name instead.
    • If the value of the field is a function that takes no arguments andreturns 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 specialvalue.size property.
• []byte
  • A value of type[]byte is rendered as the corresponding string, andpresented 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.
• MapSlice
  • An instance ofyaml.MapSlice acts as a map. It implementsm.key,m[key], andm.size.

The template store allows for usage of varying template storage implementations (embedded file system, database, service, etc). In order to use:

1. Create a struct that implements TemplateStore

   typeTemplateStoreinterface {ReadTemplate(templatenamestring) ([]byte,error)}

2. Register with the engine

   engine.RegisterTemplateStore()

FileTemplateStore is the default mechanism for backwards compatibility.

Refer toexample for an example implementation.

• Shopify.github.io/liquid
• Liquid for Designers
• Liquid for Programmers
• Help.shopify.com

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

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 theall-contributorsspecification. Contributions of any kind welcome!

Michael Hamrah'sLexing with Ragel and Parsing with Yacc usingGowas essential to understandinggo yacc.

Theoriginal Liquid engine, of course, forthe design and documentation of the Liquid template language. Many of the tagand filter test cases are taken directly from the Liquid documentation.

• karlseguin/liquid is a dormantimplementation that inspired a lot of forks.
• acstech/liquid is a more active fork ofKarl Seguin's implementation.
• hownowstephen/go-liquid

See Shopify'sports of Liquid to other environments.

MIT License