View Source Macro.Env (Elixir v1.14.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 benil
(default context),:guard
(inside a guard) or:match
(inside a match)context_modules
- a list of modules defined in the current contextfile
- the current absolute file name as a binaryfunction
- a tuple as{atom, integer}
, where the first element is the function name and the second its arity; returnsnil
if not inside a functionline
- the current line as an integermodule
- 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.
Prunes compile information from 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 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() }
Link to this section Functions
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
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.
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
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.
@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}]
Prepend a tracer to the list of tracers in the environment.
Examples
Macro.Env.prepend_tracer(__ENV__, MyCustomTracer)
Prunes compile information from the environment.
This happens when the environment is captured at compilation time, for example, in the module body, and then used to evaluate code after the module has been defined.
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
Returns the environment stacktrace.
Returns a Macro.Env
in the match context.
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.