Liquid ML

Shopify's Liquid templating language for the OCaml programming language

Featured on Awesome OCaml!

Getting Started

Install via OPAM:

opam install liquid_ml

This basic example renders a Liquid file with the default settings. The render is returned as a string.

Default Settings:

open Liquid_ml

let () =
  Liquid.render "liquid_templates/test.liquid"
  |> Stdio.print_endline

(or use Liquid.render_text to render a template stored as string instead of a file)

With Settings:

open Liquid_ml

let () =
  let settings = Settings.make ~error_policy:Warn ~log_policy:Never in
  Liquid.render ~settings "liquid_templates/test.liquid"
  |> Stdio.print_endline

Custom Variable Context

The variable context provides the template with variables accessible in the global scope.

  let () =
    (* Create an object that can be accessed in Liquid using dot notation (environment.language -> "OCaml") *)
    let environment =
      Object.empty
      |> Object.add "language" (String "OCaml")
      |> Object.add "version" (String "4.14.0")
    in

    (* HeRe we include our favorite_animal as a string an our environment as an object *)
    let context =
      Ctx.empty
      |> Ctx.add "favorite_animal" (String "horse")
      |> Ctx.add "environment" (Object environment)
    in

    let settings = Settings.make ~context () in
    render ~settings "liquid_templates/test.liquid"
    |> Stdio.print_endline

Now we can access these variables from the template:

My favorite animal is {{ favorite_animal }}!
This template was rendered using {{ environment.language }} Version {{ environment.version }}!

This renders as:

My favorite animal is horse!
This template was rendered using OCaml Version 4.14.0

We can perform logic operations using our variables:

(* OCaml *)
let () =
  (* Create an object that can be accessed in Liquid using dot notation (environment.language -> "OCaml") *)
  let context =
    Ctx.empty
    |> Ctx.add "beatles" (List [String "John"; String "Paul"; String "Ringo"; String "George"])
    |> Ctx.add "my_money" (Number 15.0)
    |> Ctx.add "apple_price" (Number 5.0)
  in

  let settings = Settings.make ~context () in
  render ~settings "liquid_templates/test.liquid"
  |> Stdio.print_endline

{% comment %}Liquid{% endcomment %}
{% for beatle in beatles %}
    {{ beatle }} lives in a yellow submarine!
{% endfor %}

{% if my_money >= apple_price %}
   You bought an apple for {{ apple_price | money }}
   {% assign after_purchase = my_money | minus: apple_price %}
   You now have {{ after_purchase | money }}
{% else %}
   You don't have enough money!
{% endif %}

This template renders to:

John lives in a yellow submarine!
Paul lives in a yellow submarine!
Ringo lives in a yellow submarine!
George lives in a yellow submarine!

You bought an apple for $5.00
You now have $10.00

Settings

You have access to the following settings:

template_directory

• The directory that contains template files. This is used both for the initial lookup (ie Liquid.render "yada.liquid") and for the render tag used within liquid. Default is project root.

log_directory

• Where log files are written too. This must be set if log policy is set to Verbose.

error_policy:

• Strict - A Liquid Syntax error will raise an exception
• Warn - A Liquid Syntax error will print an error message
• Silent - Errors will be ignored
• Custom of (handler: string -> unit) - Accepts a custom handler function

log_policy:

• Verbose - Everything will be logged
• Minimal - The most important things will be logged
• Never - Log nothing

filters:

• A function that maps filter names to filter functions
• string -> liquid_filter option

context:

• Variable Context available in the global scope
• value Ctx.t aka variable_context

preferred_currency:

• Used in money formatting filters
• Usd, Eur, Cad, Aud, Gbp

Execution Context

The type Ctx.t is used to store the execution context. All variables active in the current scope are stored here. Certain events such as break and continue are also stored in the execution context. Ctx.t is a Stdlib.Map learn more here: OCaml Map Docs

Custom Filters

A filter is a function that accepts the execution context (value Ctx.t) and a list of params (value list) and returns a result of a value. This is what a filter looks like in Liquid:

{{ "my cool dog" | replace: "dog", "cat" }}

This is transformed into a list of a parameters and passed to the filter. Notice how the value on the left side of the pipe is the first in the list. This is how all filters work. You can think of this filter as function: replace "my cool dog" "dog" "cat". This is the parameter list that will be passed to the filter:

[String "my cool dog"; String "dog"; String "cat"]

We then can use pattern matching to type check the filter. If the wrong type / wrong contents are passed into the filter we can return an error. The error will be processed based on the error policy you set. The default is Warn which causes the filter to return Nil and print an error message to the console.

Filter Example

open Liquid_ml
(* defined in syntax.ML *)
type liquid_filter = value Ctx.t -> value list -> (value, string) Result.t

let () =
  (*
    This function accepts a string, anything else will throw an error.
    Note: since we discard the tail, extra params aRe simply ignored
  *)
  let greet _ = function
    | String person :: _ -> Ok (String ("Hello " ^ person ^ "!"))
    | _ -> Error "greet accepts a string"
  in

  (* This maps the liquid name to our function *)
  let filter_lookup = function
    | "greet" -> Some greet
    | "say_hello" -> Some greet (* we can create an alias to our filter *)
    | _ -> None
  in

  let settings = Settings.make ~filters:filter_lookup in
  render ~settings "liquid_templates/test.liquid"
  |> Stdio.print_endline

Lookup Function

A filter lookup function maps filter names (the name in liquid) to the OCaml filter function in the example above we map the string greet to the function greet.

Liquid Code:
{{ "John" | greet }}
Render:
Hello John!

Liquid Types

type value =
| Bool of bool
| String of string
| Number of float
| Var of string list
| List of value list
| Date of Date.t
| Object of liquid_object
| Nil
and liquid_object = value Object.t

These are all the possible values that can be passed to a filter or stored in the execution context. Date is powered by the library Calendar. Object is a custom Stdlib.Map defined in the file syntax.ML.

Identifiers are represented as string lists. The ID apple is represented as ["apple"]. The ID collection.products[0].title is represented as ["collection"; "products"; "0"; "title"]. This means you can refer to indexes using syntax: collections.products.1.title which is standard in Liquid.

When a list of parameters is passed to a filter it will never contain the Var type. Variables are unpacked before they are passed to filters. If the variable is undefined Nil is returned.

Compatibility

This is not a complete port of Liquid. Here is a list of everything that has been ported:

Tags

• for
• if
• case
• unless
• capture
• raw
• comment (comment tag, hash comments)
• render
• include
• section
• assign
• cycle
• style
• liquid tag, allowing you to write a block of liquid code without using {% TAG_NAME %}

Filters

• Most filters not explicitly labeled "Shopify" in the Liquid Filter Docs have been ported. A complete list can be viewed in liquid_std/std.ml

Object

• forloop