liquex

defmodule Liquex do
  @moduledoc """
  Liquid template renderer for Elixir with a goal of 100% compatibility with the
  [Liquid](https://shopify.github.io/liquid/) gem by [Shopify](https://www.shopify.com/).

  ## Basic Usage

      iex> {:ok, template_ast} = Liquex.parse("Hello {{ name }}!")
      iex> context = Liquex.Context.new(%{"name" => "World"})
      iex> {content, _context} = Liquex.render(template_ast, context)
      iex> content |> to_string()
      "Hello World!"

  ## Supported features

  Currently, all standard Liquid tags, filters, and types are fully supported.  Liquex can
  be considered a drop in replacement of the Liquid gem, but in Elixir.

  There are a few caveats that must be noted:

  ***Whitespace control is partially supported.***

  [Whitespace control](https://shopify.github.io/liquid/basics/whitespace/) is only partially
  supported.  Whitespace is successfully removed after `-%}` and `-}}` tags.  However, whitespace
  isn't removed from the left side yet, before `{%-` and `{{-`.  This is because we're using
  [NimbleParsec](https://github.com/dashbitco/nimble_parsec) which does not support greedy matches.
  Instead, we will need to do post processing to properly remove spaces.  As whitespace control is
  deemed of low importance for most applications, this has not been prioritized.

  ***Date parsing isn't fully compatible***

  Liquid uses Ruby's date parser which allows for a very wide range of formats.  Liquix takes a
  somewhat simpler approach and only supports a few standard formats for ease of use.  The library
  uses [Timex](https://hexdocs.pm/timex/Timex.html) for date parsing, but this may change to be an
  optional dependency in the future.

  ## Custom filters

  Liquex contains the full suite of standard Liquid filters, but you may find that there are still
  filters that you may want to add.

  Liquex supports adding your own custom filters to the render pipeline.  When creating the context
  for the renderer, set the filter module to your own module.

      defmodule CustomFilter do
        # Import all the standard liquid filters
        use Liquex.Filter

        def scream(value, _), do: String.upcase(value) <> "!"
      end

      context = %Liquex.Context{filter_module: CustomFilter},
      {:ok, template_ast} = Liquex.parse("{{'Hello World' | scream}}",

      {result, _} =  Liquex.render(template_ast, context)
      result |> to_string()

      iex> "HELLO WORLD!"

  ## Custom tags

  One of the strong points for Liquex is that the tag parser can be extended to support non-standard
  tags.  For example, Liquid used internally for the Shopify site includes a large range of tags that
  are not supported by the base Ruby gem.  These tags could also be added to Liquex by extending the
  liquid parser.


      defmodule CustomTag do
        import NimbleParsec
        alias Liquex.Parser.Base

        # Parse <<Custom Tag>>
        def custom_tag(combinator \\\\ empty()) do
          text =
            lookahead_not(string(">>"))
            |> utf8_char([])
            |> times(min: 1)
            |> reduce({Kernel, :to_string, []})
            |> tag(:text)

          combinator
          |> ignore(string("<<"))
          |> optional(text)
          |> ignore(string(">>"))
          |> tag(:custom_tag)
        end

        def element(combinator \\\\ empty()) do
          # Add the `custom_tag/1` parsing function to the supported element tag list
          combinator
          |> choice([custom_tag(), Base.base_element()])
        end
      end

      defmodule CustomParser do
        @moduledoc false
        import NimbleParsec

        defcombinatorp(:document, repeat(CustomTag.element()))
        defparsec(:parse, parsec(:document) |> eos())
      end

      iex> Liquex.parse("<<Hello World!>>", CustomParser)
      iex> {:ok, [custom_tag: [text: ["Hello World!"]]]}

  ## Installation

  Add the package to your `mix.exs` file.

      def deps do
        [{:liquex, "~> 0.1.1"}]
      end

  """

  alias Liquex.Context

  alias Liquex.Render.{
    ControlFlow,
    Iteration,
    Object,
    Variable
  }

  @type document_t :: [
          {:control_flow, nonempty_maybe_improper_list}
          | {:iteration, [...]}
          | {:object, [...]}
          | {:text, any}
          | {:variable, [...]}
        ]

  @spec parse(String.t(), module) :: {:ok, document_t} | {:error, String.t(), pos_integer()}
  @doc """
  Parses a liquid `template` string using the given `parser`.

  Returns a liquid AST document or the parser error
  """
  def parse(template, parser \\ Liquex.Parser) do
    case parser.parse(template) do
      {:ok, content, _, _, _, _} -> {:ok, content}
      {:error, reason, _, _, line, _} -> {:error, reason, line}
    end
  end

  @spec render(document_t(), Context.t()) :: {iolist(), Context.t()}
  @doc """
  Renders a Liquid AST `document` into an `iolist`

  A `context` is given to handle temporary contextual information for
  this render.
  """
  def render(document, context \\ %Context{}),
    do: do_render([], document, context)

  @spec do_render(iolist(), document_t(), Context.t()) :: {iolist(), Context.t()}
  defp do_render(content, [], context),
    do: {content |> Enum.reverse(), context}

  defp do_render(content, [{:text, text} | tail], context) do
    [text | content]
    |> do_render(tail, context)
  end

  defp do_render(content, [{:object, object} | tail], context) do
    result = Object.render(object, context)

    [result | content]
    |> do_render(tail, context)
  end

  defp do_render(content, [{:control_flow, tag} | tail], context) do
    {result, context} = ControlFlow.render(tag, context)

    [result | content]
    |> do_render(tail, context)
  end

  defp do_render(content, [{:variable, tag} | tail], context) do
    {result, context} = Variable.render(tag, context)

    [result | content]
    |> do_render(tail, context)
  end

  defp do_render(content, [{:iteration, tag} | tail], context) do
    {result, context} = Iteration.render(tag, context)

    [result | content]
    |> do_render(tail, context)
  end
end