

API Reference – meex v1.4.1

if(localStorage.getItem('night-mode')) document.body.className += ' night-mode';

meex v1.4.1

 API Reference

===========================

 Modules

----------

[MEEx](MEEx.html)

MEx stands for Embedded Elixir. It allows you to embed

Elixir code inside a string in a robust way

[MEEx.Engine](MEEx.Engine.html)

Basic MEx engine that ships with Elixir

[MEEx.SmartEngine](MEEx.SmartEngine.html)

The default engine used by MEEx

 Exceptions

-------------

[MEEx.SyntaxError](MEEx.SyntaxError.html)



 

MEEx – meex v1.4.1

if(localStorage.getItem('night-mode')) document.body.className += ' night-mode';

meex v1.4.1

 MEEx

==================

MEx stands for Embedded Elixir. It allows you to embed

Elixir code inside a string in a robust way.

```

iex> MEEx.eval_string "foo {%= bar %}", [bar: "baz"]

"foo baz"

```

 API

------

This module provides 3 main APIs for you to use:

1. Evaluate a string (`eval_string`) or a file (`eval_file`)

 directly. This is the simplest API to use but also the

 slowest, since the code is evaluated and not compiled before.

2. Define a function from a string (`function_from_string`)

 or a file (`function_from_file`). This allows you to embed

 the template as a function inside a module which will then

 be compiled. This is the preferred API if you have access

 to the template at compilation time.

3. Compile a string (`compile_string`) or a file (`compile_file`)

 into Elixir syntax tree. This is the API used by both functions

 above and is available to you if you want to provide your own

 ways of handling the compiled template.

 Options

----------

All functions in this module accept MEx-related options.

They are:

* `:line` - the line to be used as the template start. Defaults to 1.

* `:file` - the file to be used in the template. Defaults to the given

file the template is read from or to “nofile” when compiling from a string.

* `:engine` - the MEx engine to be used for compilation.

* `:trim` - trims whitespace left/right of quotation tags

 Engine

---------

MEx has the concept of engines which allows you to modify or

transform the code extracted from the given string or file.

By default, `MEx` uses the [`MEEx.SmartEngine`](MEEx.SmartEngine.html) that provides some

conveniences on top of the simple [`MEEx.Engine`](MEEx.Engine.html).

### Tags

[`MEEx.SmartEngine`](MEEx.SmartEngine.html) supports the following tags:

```

{% Elixir expression - inline with output %}

{%= Elixir expression - replace with result %}

{%% MEx quotation - returns the contents inside %}

{%# Comments - they are discarded from source %}

```

All expressions that output something to the template

**must** use the equals sign (`=`). Since everything in

Elixir is an expression, there are no exceptions for this rule.

For example, while some template languages would special-case

`if/2` clauses, they are treated the same in MEx and

also require `=` in order to have their result printed:

```

{%= if true do %}

  It is obviously true

{% else %}

  This will never appear

{% end %}

```

Notice that different engines may have different rules

for each tag. Other tags may be added in future versions.

### Macros

[`MEEx.SmartEngine`](MEEx.SmartEngine.html) also adds some macros to your template.

An example is the `@` macro which allows easy data access

in a template:

```

iex> MEEx.eval_string "{%= @foo %}", assigns: [foo: 1]

"1"

```

In other words, `{%= @foo %}` translates to:

```

{%= {:ok, v} = Access.fetch(assigns, :foo); v %}

```

The `assigns` extension is useful when the number of variables

required by the template is not specified at compilation time.

 Summary

==========

[Functions](#functions)

------------------------

[compile\_file(filename, options \\ [])](#compile_file/2)

Gets a `filename` and generate a quoted expression

that can be evaluated by Elixir or compiled to a function

[compile\_string(source, options \\ [])](#compile_string/2)

Gets a string `source` and generate a quoted expression

that can be evaluated by Elixir or compiled to a function

[eval\_file(filename, bindings \\ [], options \\ [])](#eval_file/3)

Gets a `filename` and evaluate the values using the `bindings`

[eval\_string(source, bindings \\ [], options \\ [])](#eval_string/3)

Gets a string `source` and evaluate the values using the `bindings`

[Macros](#macros)

------------------

[function\_from\_file(kind, name, file, args \\ [], options \\ [])](#function_from_file/5)

Generates a function definition from the file contents

[function\_from\_string(kind, name, source, args \\ [], options \\ [])](#function_from_string/5)

Generates a function definition from the string

 Functions

============

compile\_file(filename, options \\ [])

```

compile_file([String.t](https://hexdocs.pm/elixir/String.html#t:t/0), [Keyword.t](https://hexdocs.pm/elixir/Keyword.html#t:t/0)) :: [Macro.t](https://hexdocs.pm/elixir/Macro.html#t:t/0) | no_return

```

Gets a `filename` and generate a quoted expression

that can be evaluated by Elixir or compiled to a function.

compile\_string(source, options \\ [])

```

compile_string([String.t](https://hexdocs.pm/elixir/String.html#t:t/0), [Keyword.t](https://hexdocs.pm/elixir/Keyword.html#t:t/0)) :: [Macro.t](https://hexdocs.pm/elixir/Macro.html#t:t/0) | no_return

```

Gets a string `source` and generate a quoted expression

that can be evaluated by Elixir or compiled to a function.

eval\_file(filename, bindings \\ [], options \\ [])

```

eval_file([String.t](https://hexdocs.pm/elixir/String.html#t:t/0), [Keyword.t](https://hexdocs.pm/elixir/Keyword.html#t:t/0), [Keyword.t](https://hexdocs.pm/elixir/Keyword.html#t:t/0)) :: any

```

Gets a `filename` and evaluate the values using the `bindings`.

 Examples

-----------

```

# sample.mex

foo {%= bar %}

# iex

MEEx.eval_file "sample.mex", [bar: "baz"] #=> "foo baz"

```

eval\_string(source, bindings \\ [], options \\ [])

```

eval_string([String.t](https://hexdocs.pm/elixir/String.html#t:t/0), [Keyword.t](https://hexdocs.pm/elixir/Keyword.html#t:t/0), [Keyword.t](https://hexdocs.pm/elixir/Keyword.html#t:t/0)) :: any

```

Gets a string `source` and evaluate the values using the `bindings`.

 Examples

-----------

```

iex> MEEx.eval_string "foo {%= bar %}", [bar: "baz"]

"foo baz"

```

 Macros

=========

function\_from\_file(kind, name, file, args \\ [], options \\ [])

Generates a function definition from the file contents.

The kind (`:def` or `:defp`) must be given, the

function name, its arguments and the compilation options.

This function is useful in case you have templates but

you want to precompile inside a module for speed.

 Examples

-----------

```

# sample.mex

{%= a + b %}

# sample.ex

defmodule Sample do

  require MEx

  MEEx.function_from_file :def, :sample, "sample.mex", [:a, :b]

end

# iex

Sample.sample(1, 2) #=> "3"

```

function\_from\_string(kind, name, source, args \\ [], options \\ [])

Generates a function definition from the string.

The kind (`:def` or `:defp`) must be given, the

function name, its arguments and the compilation options.

 Examples

-----------

```

iex> defmodule Sample do

...>   require MEx

...>   MEEx.function_from_string :def, :sample, "{%= a + b %}", [:a, :b]

...> end

iex> Sample.sample(1, 2)

"3"

```



 

MEEx.Engine – meex v1.4.1

if(localStorage.getItem('night-mode')) document.body.className += ' night-mode';

meex v1.4.1

 MEEx.Engine

 

 behaviour

======================================

Basic MEx engine that ships with Elixir.

An engine needs to implement four functions:

* `init(opts)` - returns the initial buffer

* `handle_body(quoted)` - receives the final built quoted

expression, should do final post-processing and return a

quoted expression.

* `handle_text(buffer, text)` - it receives the buffer,

the text and must return a new quoted expression.

* `handle_expr(buffer, marker, expr)` - it receives the buffer,

the marker, the expr and must return a new quoted expression.

The marker is what follows exactly after `{%`. For example,

`{% foo %}` has an empty marker, but `{%= foo %}` has `"="`

as marker. The allowed markers so far are: `""` and `"="`.

Read [`handle_expr/3`](#handle_expr/3) below for more information about the markers

implemented by default by this engine.

[`MEEx.Engine`](MEEx.Engine.html#content) can be used directly if one desires to use the

default implementations for the functions above.

 Summary

==========

[Functions](#functions)

------------------------

[handle\_assign(arg)](#handle_assign/1)

Handles assigns in quoted expressions

[handle\_body(quoted)](#handle_body/1)

The default implementation simply returns the given expression

[handle\_expr(buffer, binary, expr)](#handle_expr/3)

Implements expressions according to the markers

[handle\_text(buffer, text)](#handle_text/2)

The default implementation simply concatenates text to the buffer

[init(opts)](#init/1)

Returns an empty string as initial buffer

[Callbacks](#callbacks)

------------------------

[handle\_body(quoted)](#c:handle_body/1)

[handle\_expr(buffer, marker, expr)](#c:handle_expr/3)

[handle\_text(buffer, text)](#c:handle_text/2)

[init(opts)](#c:init/1)

 Functions

============

handle\_assign(arg)

```

handle_assign([Macro.t](https://hexdocs.pm/elixir/Macro.html#t:t/0)) :: [Macro.t](https://hexdocs.pm/elixir/Macro.html#t:t/0)

```

Handles assigns in quoted expressions.

A warning will be printed on missing assigns.

Future versions will raise.

This can be added to any custom engine by invoking

[`handle_assign/1`](#handle_assign/1) with [`Macro.prewalk/2`](https://hexdocs.pm/elixir/Macro.html#prewalk/2):

```

def handle_expr(buffer, token, expr) do

  expr = Macro.prewalk(expr, &MEEx.Engine.handle_assign/1)

  MEEx.Engine.handle_expr(buffer, token, expr)

end

```

handle\_body(quoted)

The default implementation simply returns the given expression.

handle\_expr(buffer, binary, expr)

Implements expressions according to the markers.

```

{% Elixir expression - inline with output %}

{%= Elixir expression - replace with result %}

```

All other markers are not implemented by this engine.

handle\_text(buffer, text)

The default implementation simply concatenates text to the buffer.

init(opts)

Returns an empty string as initial buffer.

 Callbacks

============

handle\_body(quoted)

```

handle_body(quoted :: [Macro.t](https://hexdocs.pm/elixir/Macro.html#t:t/0)) :: [Macro.t](https://hexdocs.pm/elixir/Macro.html#t:t/0)

```

handle\_expr(buffer, marker, expr)

```

handle_expr(buffer :: [Macro.t](https://hexdocs.pm/elixir/Macro.html#t:t/0), marker :: [String.t](https://hexdocs.pm/elixir/String.html#t:t/0), expr :: [Macro.t](https://hexdocs.pm/elixir/Macro.html#t:t/0)) :: [Macro.t](https://hexdocs.pm/elixir/Macro.html#t:t/0)

```

handle\_text(buffer, text)

```

handle_text(buffer :: [Macro.t](https://hexdocs.pm/elixir/Macro.html#t:t/0), text :: [String.t](https://hexdocs.pm/elixir/String.html#t:t/0)) :: [Macro.t](https://hexdocs.pm/elixir/Macro.html#t:t/0)

```

init(opts)

```

init(opts :: [Keyword.t](https://hexdocs.pm/elixir/Keyword.html#t:t/0)) :: [Macro.t](https://hexdocs.pm/elixir/Macro.html#t:t/0)

```



 

MEEx.SmartEngine – meex v1.4.1

if(localStorage.getItem('night-mode')) document.body.className += ' night-mode';

meex v1.4.1

 MEEx.SmartEngine

==============================

The default engine used by MEEx.

It includes assigns (like `@foo`) and possibly other

conveniences in the future.

 Examples

-----------

```

iex> MEEx.eval_string("{%= @foo %}", assigns: [foo: 1])

"1"

```

In the example above, we can access the value `foo` under

the binding `assigns` using `@foo`. This is useful because

a template, after being compiled, can receive different

assigns and would not require recompilation for each

variable set.

Assigns can also be used when compiled to a function:

```

# sample.mex

{%= @a + @b %}

# sample.ex

defmodule Sample do

  require MEx

  MEEx.function_from_file :def, :sample, "sample.mex", [:assigns]

end

# iex

Sample.sample(a: 1, b: 2) #=> "3"

```

 Summary

==========

[Functions](#functions)

------------------------

[handle\_body(quoted)](#handle_body/1)

Callback implementation for [`MEEx.Engine.handle_body/1`](MEEx.Engine.html#c:handle_body/1)

[handle\_expr(buffer, marker, expr)](#handle_expr/3)

Callback implementation for [`MEEx.Engine.handle_expr/3`](MEEx.Engine.html#c:handle_expr/3)

[handle\_text(buffer, text)](#handle_text/2)

Callback implementation for [`MEEx.Engine.handle_text/2`](MEEx.Engine.html#c:handle_text/2)

[init(opts)](#init/1)

Callback implementation for [`MEEx.Engine.init/1`](MEEx.Engine.html#c:init/1)

 Functions

============

handle\_body(quoted)

Callback implementation for [`MEEx.Engine.handle_body/1`](MEEx.Engine.html#c:handle_body/1).

handle\_expr(buffer, marker, expr)

Callback implementation for [`MEEx.Engine.handle_expr/3`](MEEx.Engine.html#c:handle_expr/3).

handle\_text(buffer, text)

Callback implementation for [`MEEx.Engine.handle_text/2`](MEEx.Engine.html#c:handle_text/2).

init(opts)

Callback implementation for [`MEEx.Engine.init/1`](MEEx.Engine.html#c:init/1).



 

MEEx.SyntaxError – meex v1.4.1

if(localStorage.getItem('night-mode')) document.body.className += ' night-mode';

meex v1.4.1

 MEEx.SyntaxError

 

 exception

===========================================

 Summary

==========

[Functions](#functions)

------------------------

[exception(msg)](#exception/1)

Callback implementation for [`Exception.exception/1`](https://hexdocs.pm/elixir/Exception.html#c:exception/1)

[message(exception)](#message/1)

Callback implementation for [`Exception.message/1`](https://hexdocs.pm/elixir/Exception.html#c:message/1)

 Functions

============

exception(msg)

```

exception([String.t](https://hexdocs.pm/elixir/String.html#t:t/0)) :: [Exception.t](https://hexdocs.pm/elixir/Exception.html#t:t/0)

```

```

exception([Keyword.t](https://hexdocs.pm/elixir/Keyword.html#t:t/0)) :: [Exception.t](https://hexdocs.pm/elixir/Exception.html#t:t/0)

```

Callback implementation for [`Exception.exception/1`](https://hexdocs.pm/elixir/Exception.html#c:exception/1).

message(exception)

```

message([Exception.t](https://hexdocs.pm/elixir/Exception.html#t:t/0)) :: [String.t](https://hexdocs.pm/elixir/String.html#t:t/0)

```

Callback implementation for [`Exception.message/1`](https://hexdocs.pm/elixir/Exception.html#c:message/1).

