Macro

Decomposes a local or remote call into its remote part (when provided), function name and argument list.

Returns :error when an invalid call syntax is provided.

Examples

iex> Macro.decompose_call(quote do: foo)
{ :foo, [] }

iex> Macro.decompose_call(quote do: foo())
{ :foo, [] }

iex> Macro.decompose_call(quote do: foo(1, 2, 3))
{ :foo, [1, 2, 3] }

iex> Macro.decompose_call(quote do: Elixir.M.foo(1, 2, 3))
{ { :__aliases__, [], [:Elixir, :M] }, :foo, [1, 2, 3] }

iex> Macro.decompose_call(quote do: 42)
:error

Recursively escapes a value so it can be inserted into a syntax tree.

One may pass unquote: true to escape/2 which leaves unquote statements unescaped, effectively unquoting the contents on escape.

Examples

iex> Macro.escape(:foo)
:foo

iex> Macro.escape({ :a, :b, :c })
{ :{}, [], [:a, :b, :c] }

iex> Macro.escape({ :unquote, [], [1] }, unquote: true)
1

Receives an AST node and expands it until it no longer represents a macro.

Check expand_once/2 for more information on how expansion works.

Receives an AST node and expands it once.

The following contents are expanded:

• Macros (local or remote);
• Aliases are expanded (if possible) and return atoms;
• Pseudo-variables (__ENV__, __MODULE__ and __DIR__);
• Module attributes reader (@foo);

If the expression cannot be expanded, it returns the expression itself. Notice that expand_once/2 performs the expansion just once and it is not recursive. Check expand/2 for expansion until the node can no longer be expanded.

Examples

In the example below, we have a macro that generates a module with a function named name_length that returns the length of the module name. The value of this function will be calculated at compilation time and not at runtime.

Consider the implementation below:

defmacro defmodule_with_length(name, do: block) do
  length = length(atom_to_list(name))

  quote do
    defmodule unquote(name) do
      def name_length, do: unquote(length)
      unquote(block)
    end
  end
end

When invoked like this:

defmodule_with_length My.Module do
  def other_function, do: ...
end

The compilation will fail because My.Module when quoted is not an atom, but a syntax tree as follow:

{:__aliases__, [], [:My, :Module] }

That said, we need to expand the aliases node above to an atom, so we can retrieve its length. Expanding the node is not straight-forward because we also need to expand the caller aliases. For example:

alias MyHelpers, as: My

defmodule_with_length My.Module do
  def other_function, do: ...
end

The final module name will be MyHelpers.Module and not My.Module. With Macro.expand/2, such aliases are taken into consideration. Local and remote macros are also expanded. We could rewrite our macro above to use this function as:

defmacro defmodule_with_length(name, do: block) do
  expanded = Macro.expand(name, __CALLER__)
  length   = length(atom_to_list(expanded))

  quote do
    defmodule unquote(name) do
      def name_length, do: unquote(length)
      unquote(block)
    end
  end
end

Pipes expr into the call_expr as the argument in the given position.

Recursively traverses the quoted expression checking if all sub-terms are safe.

Terms are considered safe if they represent data structures and don't actually evaluate code. Returns :ok unless a given term is unsafe, which is returned as { :unsafe, term }.

Converts the given expression to a binary.

Examples

iex> Macro.to_string(quote do: foo.bar(1, 2, 3))
"foo.bar(1, 2, 3)"

Unescape the given chars.

This is the unescaping behaviour used by default in Elixir single- and double-quoted strings. Check unescape_string/2 for information on how to customize the escaping map.

In this setup, Elixir will escape the following: \a, \b, \d, \e, \f, \n, \r, \s, \t and \v. Octals are also escaped according to the latin1 set they represent.

This function is commonly used on sigil implementations (like ~r, ~s and others) which receive a raw, unescaped string.

Examples

iex> Macro.unescape_string("example\\n")
"example\n"

In the example above, we pass a string with \n escaped and return a version with it unescaped.

Unescape the given chars according to the map given.

Check unescape_string/1 if you want to use the same map as Elixir single- and double-quoted strings.

Map

The map must be a function. The function receives an integer representing the codepoint of the character it wants to unescape. Here is the default mapping function implemented by Elixir:

def unescape_map(?a), do: ?\a
def unescape_map(?b), do: ?\b
def unescape_map(?d), do: ?\d
def unescape_map(?e), do: ?\e
def unescape_map(?f), do: ?\f
def unescape_map(?n), do: ?\n
def unescape_map(?r), do: ?\r
def unescape_map(?s), do: ?\s
def unescape_map(?t), do: ?\t
def unescape_map(?v), do: ?\v
def unescape_map(e),  do: e

If the unescape_map function returns false. The char is not escaped and \ is kept in the char list.

Octals

Octals will by default be escaped unless the map function returns false for ?0.

Hex

Hexadecimals will by default be escaped unless the map function returns false for ?x.

Examples

Using the unescape_map function defined above is easy:

Macro.unescape_string "example\\n", &unescape_map(&1)

Unescape the given tokens according to the default map.

Check unescape_string/1 and unescape_string/2 for more information about unescaping.

Only tokens that are binaries are unescaped, all others are ignored. This function is useful when implementing your own sigils. Check the implementation of Kernel.sigil_s/2 for examples.

Unescape the given tokens according to the given map.

Check unescape_tokens/1 and unescape_string/2 for more information.

Breaks a pipeline expression into a list.

Raises if the pipeline is ill-formed.

Recurs the quoted expression applying the given function to each metadata node.

This is often useful to remove information like lines and hygienic counters from the expression for either storage or comparison.

Examples

iex> quoted = quote line: 10, do: sample()
{:sample, [line: 10], []}
iex> Macro.update_meta(quoted, &Keyword.delete(&1, :line))
{:sample, [], []}