Expression (expression v2.41.4)

Documentation for Expression, a library to parse and evaluate Floip compatible expressions

Expression is an expression language which consists of the functions provided by Excel with a few additions.

Function and variable names are not case-sensitive so UPPER is equivalent to upper:

contact.name -> Marshawn Lynch
FIRST_WORD(contact.name) -> Marshawn
first_word(CONTACT.NAME) -> Marshawn

For templating, RapidPro uses the @ character to denote either a single variable substitution or the beginning of an Expression block. @ was chosen as it is known how to type by a broad number of users regardless of keyboard. It does have the disadvantage of being used in email addresses and Twitter handles, but these are rarely ambiguous and escaping can be done easily via doubling of the character (@@).

Functions are called by using the block syntax:

10 plus 4 is @(SUM(10, 4))

Within a block, @ is not required to refer to variable in the context:

Hello @(contact.name)

A template can contain more than one substitution or block:

Hello @contact.name, you were born in @(YEAR(contact.birthday))

Summary

Types

expression_type()

Functions

error(message)

Generate an error map

escape(expression)
evaluate(expression, context \\ %{}, mod \\ Expression.Callbacks)
evaluate!(expression, context \\ %{}, mod \\ Expression.Callbacks)
evaluate_as_boolean!(expression, context \\ %{}, mod \\ Expression.Callbacks)
evaluate_as_string!(expression, context \\ %{}, mod \\ Expression.Callbacks)
evaluate_block(expression, context \\ %{}, mod \\ Expression.Callbacks, opts \\ [])
evaluate_block!(expression, context \\ %{}, mod \\ Expression.Callbacks, opts \\ [])
parse!(expression)
parse_expression(expression_block)
parse_expression!(expression_block)
prewalk(ast, fun)

See Macro.prewalk/2.

stringify(items)

Convert an Expression type into a string.

traverse(ast, acc, pre, post)

See Macro.traverse/4.

Types

expression_type()

@type expression_type() :: String.t() | number() | map() | DateTime.t() | Date.t()

Functions

error(message)

@spec error(message :: term()) :: %{required(String.t()) => term()}

Generate an error map

escape(expression)

@spec escape(String.t()) :: String.t()

evaluate(expression, context \\ %{}, mod \\ Expression.Callbacks)

evaluate!(expression, context \\ %{}, mod \\ Expression.Callbacks)

evaluate_as_boolean!(expression, context \\ %{}, mod \\ Expression.Callbacks)

evaluate_as_string!(expression, context \\ %{}, mod \\ Expression.Callbacks)

@spec evaluate_as_string!(
  String.t() | Number.t() | nil,
  map(),
  module()
) :: String.t()

evaluate_block(expression, context \\ %{}, mod \\ Expression.Callbacks, opts \\ [])

evaluate_block!(expression, context \\ %{}, mod \\ Expression.Callbacks, opts \\ [])

parse!(expression)

@spec parse!(String.t() | Number.t()) :: Keyword.t()

parse_expression(expression_block)

@spec parse_expression(String.t()) :: {:ok, Keyword.t()} | {:error, String.t()}

parse_expression!(expression_block)

@spec parse_expression!(String.t()) :: Keyword.t()

prewalk(ast, fun)

See Macro.prewalk/2.

stringify(items)

@spec stringify([expression_type()] | expression_type()) :: String.t()

Convert an Expression type into a string.

This function is applied to all values when Expression.evaluate_as_string!/3 is called.

traverse(ast, acc, pre, post)

See Macro.traverse/4.