erl_eval(3)

📦

version 29.0.6 · 3 versions

erl_eval(3) 💅 — the Erlang Module Definition page, but make it make sense

okay bestie, welcome to erl_eval(3) ✨ this is the manual page for the Erlang meta interpreter, and yes we are going to read it together and you are going to get it. grab a strawberry 🍓

🌸 NAME 🌸

erl_eval — the Erlang meta interpreter. that's it, that's the vibe. 👑

✨ DESCRIPTION ✨

So like, this module? It hands you an interpreter for Erlang expressions. The expressions it takes are in the abstract syntax — you know, the shape that erl_parse (the Erlang parser) or io spits out. no cap. 🦋

🎀 Local Function Handler 🎀

Real talk: while you're evaluating a function, you cannot make calls to local functions. if you try, you get an undefined function error. that's just how it is, sorry bestie 😭

BUT. There's this optional argument called LocalFunctionHandler, and it lets you define a function that gets called whenever there's a call to a local function. slay. It comes in these formats:

{value,Func} — this defines a local function handler that gets called like:

Func(Name, Arguments)

Name is the name of the local function (an atom) and Arguments is a list of the evaluated arguments. The function handler returns the value of the local function. In this case, the current bindings cannot be accessed. And if you want to signal an error? the function handler calls exit/1 with a suitable exit value. periodt.

{eval,Func} — this defines a local function handler that gets called like:

Func(Name, Arguments, Bindings)

Name is the name of the local function (an atom), Arguments is a list of the unevaluated arguments, and Bindings are the current variable bindings. The function handler returns:

{value,Value,NewBindings}

Value is the value of the local function and NewBindings are the updated variable bindings. In this case, the function handler has to evaluate all the function arguments itself and manage the bindings. no skipping that part 🙈. To signal an error, the function handler calls exit/1 with a suitable exit value.

none — there is no local function handler. simple as that.

🦋 Non-Local Function Handler 🦋

The optional argument NonLocalFunctionHandler lets you define a function that gets called in these cases:

a functional object (fun) is called.
a built-in function is called.
a function is called using the M:F syntax, where M and F are atoms or expressions.
an operator Op/A is called (this is handled as a call to function erlang:Op/A).

Exceptions, bestie — and this matters: calls to erlang:apply/2,3 are exceptions; neither of the function handlers are called for such calls. 🫶

The argument can have the following formats:

{value,Func} — this defines a non-local function handler. The function may be called with two arguments:

Func(FuncSpec, Arguments)

or three arguments:

Func(Anno, FuncSpec, Arguments)

Anno is the erl_anno:anno() of the node, FuncSpec is the name of the function of the form {Module,Function} or a fun, and Arguments is a list of the evaluated arguments. The function handler returns the value of the function. To signal an error, the function handler calls exit/1 with a suitable exit value.

none — there is no non-local function handler.

NOTE: For calls such as erlang:apply(Fun, Args) or erlang:apply(Module, Function, Args), the call of the non-local function handler corresponding to the call to erlang:apply/2,3 itself (Func({erlang, apply}, [Fun, Args]) or Func({erlang, apply}, [Module, Function, Args])) never takes place. The non-local function handler is however called with the evaluated arguments of the call to erlang:apply/2,3: Func(Fun, Args) or Func({Module, Function}, Args) (assuming that {Module, Function} is not {erlang, apply}). Calls to functions defined by evaluating fun expressions "fun ... end" are also hidden from non-local function handlers. 💀

The non-local function handler argument is probably not used as frequently as the local function handler argument. A possible use is to call exit/1 on calls to functions that for some reason are not allowed to be called. iconic use case honestly.

🌈 DATA TYPES 🌈

binding_struct() :: orddict:orddict() | map().

A binding structure. It is either a map or an orddict. erl_eval will always return the same type as the one given. matching energy, we love to see it 💖

bindings() :: [{name(), value()}].
expression() :: erl_parse:abstract_expr().
expression_list() :: [expression()].
expressions() :: [erl_parse:abstract_expr()].

As returned by erl_parse:parse_exprs/1 or io:parse_erl_exprs/2.

func_spec() ::

{Module :: module(), Function :: atom()} | function().

lfun_eval_handler() ::

fun((Name :: atom(),
     Arguments :: expression_list(),
     Bindings :: binding_struct()) ->
        {value,
         Value :: value(),
         NewBindings :: binding_struct()}).

lfun_value_handler() ::

fun((Name :: atom(), Arguments :: [term()]) ->
        Value :: value()).

local_function_handler() ::

{value, lfun_value_handler()} |
{eval, lfun_eval_handler()} |
none.

Further described in section Local Function Handler in this module.

name() :: term().
nlfun_handler() ::

fun((FuncSpec :: func_spec(), Arguments :: [term()]) ->
term()) |
fun((Anno :: erl_anno:anno(),
     FuncSpec :: func_spec(),
     Arguments :: [term()]) ->
        term()).

non_local_function_handler() :: {value, nlfun_handler()} | none.

Further described in section Non-Local Function Handler in this module.

value() :: term().

👑 FUNCTIONS 👑

`add_binding(Name, Value, BindingStruct) -> binding_struct()`

add_binding(Name, Value, BindingStruct) -> binding_struct()
                     when
                         Name :: name(),
                         Value :: value(),
                         BindingStruct :: binding_struct().

Adds binding Name=Value to BindingStruct. Returns an updated binding structure. cute and simple 💅

`binding(Name, BindingStruct) -> {value, value()} | unbound`

binding(Name, BindingStruct) -> {value, value()} | unbound
                 when Name :: name(), BindingStruct :: binding_struct().

Returns the binding of Name in BindingStruct. ✨

`bindings(BindingStruct :: binding_struct()) -> bindings().`

bindings(BindingStruct :: binding_struct()) -> bindings().

Returns the list of bindings contained in the binding structure. give me the whole list bestie 📋

`del_binding(Name, BindingStruct) -> binding_struct()`

del_binding(Name, BindingStruct) -> binding_struct()
                     when
                         Name :: name(),
                         BindingStruct :: binding_struct().

Removes the binding of Name in BindingStruct. Returns an updated binding structure. bye bye binding 👋

`expr(Expression, Bindings, LocalFunctionHandler, NonLocalFunctionHandler, ReturnFormat) -> {value, Value, NewBindings} | Value`

expr(Expression, Bindings, LocalFunctionHandler,
           NonLocalFunctionHandler, ReturnFormat) ->
              {value, Value, NewBindings} | Value
              when
                  Expression :: expression(),
                  Bindings :: binding_struct(),
                  LocalFunctionHandler :: local_function_handler(),
                  NonLocalFunctionHandler ::
                      non_local_function_handler(),
                  ReturnFormat :: none | value,
                  Value :: value(),
                  NewBindings :: binding_struct().

Evaluates Expression with the set of bindings Bindings. Expression is an expression in abstract syntax. 🌸

For an explanation of when and how to use arguments LocalFunctionHandler and NonLocalFunctionHandler, see sections Local Function Handler and Non-Local Function Handler in this module.

Returns {value, Value, NewBindings} by default. If ReturnFormat is value, only Value is returned. your choice, main character 🎀

`expr_list(ExpressionList, Bindings, LocalFunctionHandler, NonLocalFunctionHandler) -> {ValueList, NewBindings}`

expr_list(ExpressionList, Bindings, LocalFunctionHandler,
                NonLocalFunctionHandler) ->
                   {ValueList, NewBindings}
                   when
                       ExpressionList :: expression_list(),
                       Bindings :: binding_struct(),
                       LocalFunctionHandler :: local_function_handler(),
                       NonLocalFunctionHandler ::
                           non_local_function_handler(),
                       ValueList :: [value()],
                       NewBindings :: binding_struct().

Evaluates a list of expressions in parallel, using the same initial bindings for each expression. Attempts are made to merge the bindings returned from each evaluation. multitasking queen 🦋

This function is useful in LocalFunctionHandler, see section Local Function Handler in this module.

Returns {ValueList, NewBindings}.

`exprs(Expressions, Bindings, LocalFunctionHandler, NonLocalFunctionHandler) -> {value, Value, NewBindings}`

exprs(Expressions, Bindings, LocalFunctionHandler,
            NonLocalFunctionHandler) ->
               {value, Value, NewBindings}
               when
                   Expressions :: expressions(),
                   Bindings :: binding_struct(),
                   LocalFunctionHandler :: local_function_handler(),
                   NonLocalFunctionHandler ::
                       non_local_function_handler(),
                   Value :: value(),
                   NewBindings :: binding_struct().

Evaluates Expressions with the set of bindings Bindings, where Expressions is a sequence of expressions (in abstract syntax) of a type that can be returned by io:parse_erl_exprs/2. 🔥

For an explanation of when and how to use arguments LocalFunctionHandler and NonLocalFunctionHandler, see sections Local Function Handler and Non-Local Function Handler in this module.

Returns {value, Value, NewBindings} (no period at the end there, that's just how the original does it, we keep it verbatim okay 😌)

`new_bindings() -> binding_struct().`

new_bindings() -> binding_struct().

Returns an empty binding structure. fresh start, blank slate, new era ✨🧚

okay that's the whole page, you ate that fr fr 💖 🎀

Ericsson AB · stdlib 8.0.4 · and yes, we're keeping the classic erl_eval(3) footer energy — no date on this one bestie, the original footer is just the source and version, so that's all we're passing along 🫶 go forth and interpret, queen 👑

📦 where this page comes from

ubuntu stonking: erlang-doc 1:29.0.6+dfsg-1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms