# `Otera`
[🔗](https://github.com/georgeguimaraes/otera/blob/v0.1.0/lib/otera.ex#L1)

Otera (お寺, "temple") renders Jinja templates in pure Elixir, with the semantics of Python Jinja2.

    iex> Otera.render("Hello {{ name }}!", %{name: "World"})
    {:ok, "Hello World!"}

Variables are Elixir values, which templates see as Python values: maps are dicts, lists are lists, `nil` is `None`, and atom keys become strings. See `Otera.Value` for the full mapping, and `Otera.Dict` for the key order of dicts.

To render the chat template of a Hugging Face model like transformers, see `Otera.ChatTemplate`.

## Options

  * `:trim_blocks` - removes the first newline after a block tag. The default is `false`.
  * `:lstrip_blocks` - removes the spaces and tabs before a block tag at the start of a line. The default is `false`.
  * `:keep_trailing_newline` - keeps the final newline of the template. The default is `false`.
  * `:globals` - a map of names to values or Elixir functions that the template can use.
  * `:filters` - a map of names to Elixir functions, called with the value and the filter arguments.
  * `:tests` - a map of names to Elixir functions, called with the value and the test arguments.

A plain Elixir function gets the positional arguments of the call. For keyword arguments and defaults, give an `Otera.Function`, which has a Python signature. Values that a function returns become template values, like variables.

The `break` and `continue` statements of the `loopcontrols` extension and the `{% generation %}` block of transformers are always available.

# `error`

```elixir
@type error() :: Otera.SyntaxError.t() | Otera.Error.t()
```

# `parse`

```elixir
@spec parse(String.t(), keyword()) ::
  {:ok, Otera.Template.t()} | {:error, Otera.SyntaxError.t()}
```

Parses `source` into a template that renders many times.

The options are the options of the module documentation. They apply to every render of the template.

# `render`

```elixir
@spec render(String.t() | Otera.Template.t(), map() | keyword(), keyword()) ::
  {:ok, String.t()} | {:error, error()}
```

Renders a template, given as source or as a parsed `Otera.Template`, with `variables`.

`variables` is a map or a keyword list. Returns `{:ok, string}`, or `{:error, exception}` with an `Otera.SyntaxError` or an `Otera.Error`.

# `render!`

```elixir
@spec render!(String.t() | Otera.Template.t(), map() | keyword(), keyword()) ::
  String.t()
```

Like `render/3`, but raises the error.

---

*Consult [api-reference.md](api-reference.md) for complete listing*