View Source Macro.Env (Elixir v1.13.0-rc.0)

A struct that holds compile time environment information.

The current environment can be accessed at any time as __ENV__/0. Inside macros, the caller environment can be accessed as __CALLER__/0.

An instance of Macro.Env must not be modified by hand. If you need to create a custom environment to pass to Code.eval_quoted/3, use the following trick:

def make_custom_env do
  import SomeModule, only: [some_function: 2]
  alias A.B.C
  __ENV__
end

You may then call make_custom_env() to get a struct with the desired imports and aliases included.

It contains the following fields:

  • context - the context of the environment; it can be nil (default context), :guard (inside a guard) or :match (inside a match)
  • context_modules - a list of modules defined in the current context
  • file - the current file name as a binary
  • function - a tuple as {atom, integer}, where the first element is the function name and the second its arity; returns nil if not inside a function
  • line - the current line as an integer
  • module - the current module name

The following fields are private to Elixir's macro expansion mechanism and must not be accessed directly:

  • aliases
  • functions
  • macro_aliases
  • macros
  • lexical_tracker
  • requires
  • tracers
  • versioned_vars

Link to this section Summary

Functions

Fetches the alias for the given atom.

Fetches the macro alias for the given atom.

Checks if a variable belongs to the environment.

Returns whether the compilation environment is currently inside a guard.

Returns whether the compilation environment is currently inside a match clause.

Returns a keyword list containing the file and line information as keys.

Returns the modules from which the given {name, arity} was imported.

Prepend a tracer to the list of tracers in the environment.

Returns true if the given module has been required.

Returns the environment stacktrace.

Returns a Macro.Env in the match context.

Returns a list of variables in the current environment.

Link to this section Types

@type context() :: :match | :guard | nil
@type context_modules() :: [module()]
@type file() :: binary()
@type line() :: non_neg_integer()
@type name_arity() :: {atom(), arity()}
@type t() :: %Macro.Env{
  aliases: aliases(),
  context: context(),
  context_modules: context_modules(),
  file: file(),
  function: name_arity() | nil,
  functions: functions(),
  lexical_tracker: lexical_tracker(),
  line: line(),
  macro_aliases: macro_aliases(),
  macros: macros(),
  module: module(),
  requires: requires(),
  tracers: tracers(),
  versioned_vars: versioned_vars()
}
@type variable() :: {atom(), atom() | term()}

Link to this section Functions

Link to this function

fetch_alias(map, atom)

View Source (since 1.13.0)
@spec fetch_alias(t(), atom()) :: {:ok, atom()} | :error

Fetches the alias for the given atom.

Returns {:ok, alias} if the alias exists, :error otherwise.

Examples

iex> alias Foo.Bar, as: Baz
iex> Baz
Foo.Bar
iex> Macro.Env.fetch_alias(__ENV__, :Baz)
{:ok, Foo.Bar}
iex> Macro.Env.fetch_alias(__ENV__, :Unknown)
:error
Link to this function

fetch_macro_alias(map, atom)

View Source (since 1.13.0)
@spec fetch_macro_alias(t(), atom()) :: {:ok, atom()} | :error

Fetches the macro alias for the given atom.

Returns {:ok, macro_alias} if the alias exists, :error otherwise.

A macro alias is only used inside quoted expansion. See fetch_alias/2 for a more general example.

Link to this function

has_var?(env, var)

View Source (since 1.7.0)
@spec has_var?(t(), variable()) :: boolean()

Checks if a variable belongs to the environment.

Examples

iex> x = 13
iex> x
13
iex> Macro.Env.has_var?(__ENV__, {:x, nil})
true
iex> Macro.Env.has_var?(__ENV__, {:unknown, nil})
false
@spec in_guard?(t()) :: boolean()

Returns whether the compilation environment is currently inside a guard.

@spec in_match?(t()) :: boolean()

Returns whether the compilation environment is currently inside a match clause.

@spec location(t()) :: keyword()

Returns a keyword list containing the file and line information as keys.

Link to this function

lookup_import(map, pair)

View Source (since 1.13.0)
@spec lookup_import(t(), name_arity()) :: [{:function | :macro, module()}]

Returns the modules from which the given {name, arity} was imported.

It returns a list of two element tuples in the shape of {:function | :macro, module}. The elements in the list are in no particular order and the order is not guaranteed.

Examples

iex> Macro.Env.lookup_import(__ENV__, {:duplicate, 2})
[]
iex> import Tuple, only: [duplicate: 2], warn: false
iex> Macro.Env.lookup_import(__ENV__, {:duplicate, 2})
[{:function, Tuple}]
iex> import List, only: [duplicate: 2], warn: false
iex> Macro.Env.lookup_import(__ENV__, {:duplicate, 2})
[{:function, List}, {:function, Tuple}]

iex> Macro.Env.lookup_import(__ENV__, {:def, 1})
[{:macro, Kernel}]
Link to this function

prepend_tracer(env, tracer)

View Source (since 1.13.0)
@spec prepend_tracer(t(), module()) :: t()

Prepend a tracer to the list of tracers in the environment.

Examples

Macro.Env.prepend_tracer(__ENV__, MyCustomTracer)
Link to this function

required?(map, mod)

View Source (since 1.13.0)
@spec required?(t(), module()) :: boolean()

Returns true if the given module has been required.

Examples

iex> Macro.Env.required?(__ENV__, Integer)
false
iex> require Integer
iex> Macro.Env.required?(__ENV__, Integer)
true

iex> Macro.Env.required?(__ENV__, Kernel)
true
@spec stacktrace(t()) :: list()

Returns the environment stacktrace.

@spec to_match(t()) :: t()

Returns a Macro.Env in the match context.

@spec vars(t()) :: [variable()]

Returns a list of variables in the current environment.

Each variable is identified by a tuple of two elements, where the first element is the variable name as an atom and the second element is its context, which may be an atom or an integer.