liquid - Liquid template engine for Crystal

Liquid templating language: http://shopify.github.io/liquid/

Installation

Add this to your application's shard.yml:

dependencies:
  liquid:
    github: amberframework/liquid.cr

Usage

require "liquid"

txt = "
    {% if kenny.sick %}
      Kenny is sick.
    {% elsif kenny.dead %}
      You killed Kenny!  You ***!!!
    {% else %}
      Kenny looks okay --- so far
    {% endif %}
    "
ctx = Liquid::Context.new
ctx.set "kenny", Any{ "sick" => false, "dead" => true}

tpl = Liquid::Template.parse txt  # tpl can be cached and reused

result = tpl.render ctx

# result = "
#      You killed Kenny!  You ***!!!
#
#    "

Tags can be escaped:

\{% assign myvar = 15 %}

# or

{% raw %}
{% assign myvar = 15 %}
{% endraw %}

will both render {% assign myvar = 15 %}.

Blocks

Cache block (only supports caching using Redis): https://github.com/TechMagister/liquid-cache.cr

Filters

• abs
• append
• at_least
• at_most
• capitalize
• ceil
• compact
• concat
• date
• default
• divided_by
• downcase
• escape
• escape_once
• first
• floor
• join
• last
• lstrip
• map
• minus
• modulo
• newline_to_br
• plus
• prepend
• remove
• remove_first
• replace
• replace_first
• reverse
• round
• rstrip
• size
• slice
• sort
• sort_natural
• split
• strip
• strip_html
• strip_newlines
• times
• truncate
• truncatewords
• uniq
• upcase
• url_decode
• url_encode
• where

Helper Methods

• size (for Array and String)
• present / blank (added)
• first / last

Development

TODO:

• Basic For loops
• if/elsif/else/endif
• unless/endunless
• Raw and comment blocks ({% raw %} and {% comment %})
• Add variable assignment ({% assign var = "Hello World" %})
• Add support for multiple operator (no operator precedence support (for now))
• Add support for Array into for loop
• Add support for Hash into for loop ({% for val in myhash %}, access as val[0] and val[1])
• Add support for Hash into for loop ({% for key, val in myhash %}) (new)
• Add support for Float
• Add iteration over Arrays
• Improve data interface
• Add Filter support
• Add capture block
• Add increment block
• Add decrement block
• Add support for Array in expressions
• Add support for Hash in expressions
• Add "secret" empty Array ([]) for use in comparisons (equivalent to #blank helper method)
• Add contains operator
• Add cycle keyword
• Add starts_with keyword (new)
• Add ends_with keyword (new)
• Add continue keyword
• Add break keyword
• Add case/when
• Add syntax checking
• Improve expression parsing
• Add optional strict mode on Context (see below)
• Add Everything that's missing [https://shopify.github.io/liquid/]

Context Strict Mode

NOTE: Will eventually use this to implement a strict_variables rendering flag (planning to implement strict_filters as well).

Enable at initialization:

ctx = Liquid::Context.new(:strict)

Or on an existing Context:

ctx.error_mode = :strict

Raises Liquid::InvalidExpression on missing keys and silently emit nil on array out of bounds.

Append ? to emit nil in strict mode (very simplistic, just checks for ? at the end of the identifier)

ctx = Liquid::Context.new(:strict)
ctx["obj"] = { something: "something" }

{{ missing }}          -> nil, but generates a UndefinedVariable errors if not in Lax mode.
{{ obj.missing }}      -> InvalidExpression
{{ missing.missing? }} -> generates a UndefinedVariable error, evaluates `missing` to nil then raises a InvalidExpression due to `nil.missing` call.

Contributing

1. Fork it ( https://github.com/amberframework/liquid.cr/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• TechMagister Arnaud Fernandés - creator, maintainer of original version
• docelic Davor Ocelic
• anamba Aaron Namba