Macro.Env
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 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; returnsnilif 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:
aliasesfunctionsmacro_aliasesmacroslexical_trackerrequirestracersversioned_vars
Summary
Types
Functions
- fetch_alias(map, atom)
-
Fetches the alias for the given atom.
- fetch_macro_alias(map, atom)
-
Fetches the macro alias for the given atom.
- has_var?(env, var)
-
Checks if a variable belongs to the environment.
- in_guard?(env)
-
Returns whether the compilation environment is currently inside a guard.
- in_match?(env)
-
Returns whether the compilation environment is currently inside a match clause.
- location(env)
-
Returns a keyword list containing the file and line information as keys.
- lookup_import(map, pair)
-
Returns the modules from which the given
{name, arity}was imported. - prepend_tracer(env, tracer)
-
Prepend a tracer to the list of tracers in the environment.
- required?(map, mod)
-
Returns true if the given module has been required.
- stacktrace(env)
-
Returns the environment stacktrace.
- to_match(env)
-
Returns a
Macro.Envin the match context. - vars(env)
-
Returns a list of variables in the current environment.
Types
context()Source
@type context() :: :match | :guard | nil
context_modules()Source
@type context_modules() :: [module()]
file()Source
@type file() :: binary()
line()Source
@type line() :: non_neg_integer()
name_arity()Source
@type name_arity() :: {atom(), arity()}
t()Source
@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()
}
variable()Source
@type variable() :: {atom(), atom() | term()}
Functions
fetch_alias(map, atom)Source
@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
fetch_macro_alias(map, atom)Source
@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.
has_var?(env, var)Source
@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
in_guard?(env)Source
@spec in_guard?(t()) :: boolean()
Returns whether the compilation environment is currently inside a guard.
in_match?(env)Source
@spec in_match?(t()) :: boolean()
Returns whether the compilation environment is currently inside a match clause.
location(env)Source
@spec location(t()) :: keyword()
Returns a keyword list containing the file and line information as keys.
lookup_import(map, pair)Source
@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_tracer(env, tracer)Source
@spec prepend_tracer(t(), module()) :: t()
Prepend a tracer to the list of tracers in the environment.
Examples
Macro.Env.prepend_tracer(__ENV__, MyCustomTracer)
required?(map, mod)Source
@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
stacktrace(env)Source
@spec stacktrace(t()) :: list()
Returns the environment stacktrace.
to_match(env)Source
@spec to_match(t()) :: t()
Returns a Macro.Env in the match context.
vars(env)Source
@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.
© 2012 Plataformatec
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.13.4/Macro.Env.html
