View Source Macro.Env (Elixir v1.17.1)
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
.
The majority of the functions in this module are provided
for low-level tools, which need to integrate with the Elixir
compiler, such as language servers and embedded languages.
For regular usage in Elixir code and macros, you must use
the Macro
module instead. In particular, avoid modifying
the Macro.Env
struct directly and prefer to use high-level
constructs, such as a import
, aliases
, and so forth to
build your own environment. For example, to build a custom
environment, you can define a function such as:
def make_custom_env do
import SomeModule, only: [some_function: 2], warn: false
alias A.B.C, warn: false
__ENV__
end
Struct fields
The Macro.Env
struct 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
Summary
Functions
Defines the given as
an alias to module
in the environment.
Defines the given module
as imported in the environment.
Defines the given module
as required in the environment.
Expands an alias given by the alias segments.
Expands an import given by name
and arity
.
Expands a require given by module
, name
, and arity
.
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 names of any aliases for the given module or atom.
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 an environment in the guard context.
Returns an environment in the match context.
Returns a list of variables in the current environment.
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() }
Functions
Defines the given as
an alias to module
in the environment.
This is used by tools which need to mimic the Elixir compiler.
The appropriate :alias
compiler tracing event will be emitted.
Additional options
It accepts the same options as Kernel.SpecialForm.alias/2
plus:
:trace
- when set tofalse
, it disables compilation tracers and lexical tracker. This option must only be used by language servers and other tools that need to introspect code without affecting how it is compiled. Disabling tracer inside macros or regular code expansion is extremely discouraged as it blocks the compiler from accurately tracking dependencies
Examples
iex> env = __ENV__
iex> Macro.Env.expand_alias(env, [], [:Baz])
:error
iex> {:ok, env} = Macro.Env.define_alias(env, [line: 10], Foo.Bar, as: Baz)
iex> Macro.Env.expand_alias(env, [], [:Baz])
{:alias, Foo.Bar}
iex> Macro.Env.expand_alias(env, [], [:Baz, :Bat])
{:alias, Foo.Bar.Bat}
If no :as
option is given, the alias will be inferred from the module:
iex> env = __ENV__
iex> {:ok, env} = Macro.Env.define_alias(env, [line: 10], Foo.Bar)
iex> Macro.Env.expand_alias(env, [], [:Bar])
{:alias, Foo.Bar}
If it is not possible to infer one, an error is returned:
iex> Macro.Env.define_alias(__ENV__, [line: 10], :an_atom)
{:error,
"alias cannot be inferred automatically for module: :an_atom, " <>
"please use the :as option. Implicit aliasing is only supported with Elixir modules"}
@spec define_import(t(), Macro.metadata(), module(), keyword()) :: {:ok, t()} | {:error, String.t()}
Defines the given module
as imported in the environment.
It assumes module
is available. This is used by tools which
need to mimic the Elixir compiler. The appropriate :import
compiler tracing event will be emitted.
Additional options
It accepts the same options as Kernel.SpecialForm.import/2
plus:
:emit_warnings
- emit warnings found when defining imports:trace
- when set tofalse
, it disables compilation tracers and lexical tracker. This option must only be used by language servers and other tools that need to introspect code without affecting how it is compiled. Disabling tracer inside macros or regular code expansion is extremely discouraged as it blocks the compiler from accurately tracking dependencies:info_callback
- a function to use instead ofModule.__info__/1
. The function will be invoked with:functions
or:macros
argument. It has to return a list of{function, arity}
key value pairs. If it fails, it defaults to using module metadata based onmodule_info/1
.
Examples
iex> env = __ENV__
iex> Macro.Env.lookup_import(env, {:flatten, 1})
[]
iex> {:ok, env} = Macro.Env.define_import(env, [line: 10], List)
iex> Macro.Env.lookup_import(env, {:flatten, 1})
[{:function, List}]
It accepts the same options as Kernel.SpecialForm.import/2
:
iex> env = __ENV__
iex> Macro.Env.lookup_import(env, {:is_odd, 1})
[]
iex> {:ok, env} = Macro.Env.define_import(env, [line: 10], Integer, only: :macros)
iex> Macro.Env.lookup_import(env, {:is_odd, 1})
[{:macro, Integer}]
Info callback override
iex> env = __ENV__
iex> Macro.Env.lookup_import(env, {:flatten, 1})
[]
iex> {:ok, env} = Macro.Env.define_import(env, [line: 10], SomeModule, [info_callback: fn :functions -> [{:flatten, 1}]; :macros -> [{:some, 2}]; end])
iex> Macro.Env.lookup_import(env, {:flatten, 1})
[{:function, SomeModule}]
iex> Macro.Env.lookup_import(env, {:some, 2})
[{:macro, SomeModule}]
Defines the given module
as required in the environment.
It does not check or assert the module is available.
This is used by tools which need to mimic the Elixir compiler.
The appropriate :require
compiler tracing event will be emitted.
Additional options
It accepts the same options as Kernel.SpecialForm.require/2
plus:
:trace
- when set tofalse
, it disables compilation tracers and lexical tracker. This option must only be used by language servers and other tools that need to introspect code without affecting how it is compiled. Disabling tracer inside macros or regular code expansion is extremely discouraged as it blocks the compiler from accurately tracking dependencies
Examples
iex> env = __ENV__
iex> Macro.Env.required?(env, Integer)
false
iex> {:ok, env} = Macro.Env.define_require(env, [line: 10], Integer)
iex> Macro.Env.required?(env, Integer)
true
If the :as
option is given, it will also define an alias:
iex> env = __ENV__
iex> {:ok, env} = Macro.Env.define_require(env, [line: 10], Foo.Bar, as: Baz)
iex> Macro.Env.expand_alias(env, [], [:Baz])
{:alias, Foo.Bar}
Expands an alias given by the alias segments.
It returns {:alias, alias}
if the segments is a list
of atoms and an alias was found. Returns :error
otherwise.
This expansion may emit the :alias_expansion
trace event
but it does not emit the :alias_reference
one.
Options
:trace
- when set tofalse
, it disables compilation tracers and lexical tracker. This option must only be used by language servers and other tools that need to introspect code without affecting how it is compiled. Disabling tracer inside macros or regular code expansion is extremely discouraged as it blocks the compiler from accurately tracking dependencies
Examples
iex> alias List, as: MyList
iex> Macro.Env.expand_alias(__ENV__, [], [:MyList])
{:alias, List}
iex> Macro.Env.expand_alias(__ENV__, [], [:MyList, :Nested])
{:alias, List.Nested}
If there is no alias or the alias starts with Elixir.
(which disables aliasing), then :error
is returned:
iex> alias List, as: MyList
iex> Macro.Env.expand_alias(__ENV__, [], [:Elixir, MyList])
:error
iex> Macro.Env.expand_alias(__ENV__, [], [:AnotherList])
:error
@spec expand_import(t(), keyword(), atom(), arity(), keyword()) :: {:macro, module(), (Macro.metadata(), args :: [Macro.t()] -> Macro.t())} | {:function, module(), atom()} | {:error, :not_found | {:conflict, module()} | {:ambiguous, [module()]}}
Expands an import given by name
and arity
.
If the import points to a macro, it returns a tuple with the module and a function that expands the macro. The function expects the metadata to be attached to the expansion and the arguments of the macro.
If the import points to a function, it returns a tuple with the module and the function name.
If any import is found, the appropriate compiler tracing event will be emitted.
Otherwise returns {:error, reason}
.
Options
:allow_locals
- when set tofalse
, it does not attempt to capture local macros defined in the current module inenv
:check_deprecations
- when set tofalse
, does not check for deprecations when expanding macros:trace
- when set tofalse
, it disables compilation tracers and lexical tracker. This option must only be used by language servers and other tools that need to introspect code without affecting how it is compiled. Disabling tracer inside macros or regular code expansion is extremely discouraged as it blocks the compiler from accurately tracking dependencies
expand_require(env, meta, module, name, arity, opts \\ [])
View Source (since 1.17.0)@spec expand_require(t(), keyword(), module(), atom(), arity(), keyword()) :: {:macro, module(), (Macro.metadata(), args :: [Macro.t()] -> Macro.t())} | :error
Expands a require given by module
, name
, and arity
.
If the require points to a macro and the module has been
required, it returns a tuple with the module and a function
that expands the macro. The function expects the metadata
to be attached to the expansion and the arguments of the macro.
The appropriate :remote_macro
compiler tracing event will
be emitted if a macro is found (note a :remote_function
event is not emitted in :error
cases).
Otherwise returns :error
.
Options
:check_deprecations
- when set tofalse
, does not check for deprecations when expanding macros:trace
- when set tofalse
, it disables compilation tracers and lexical tracker. This option must only be used by language servers and other tools that need to introspect code without affecting how it is compiled. Disabling tracer inside macros or regular code expansion is extremely discouraged as it blocks the compiler from accurately tracking dependencies
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.
Returns the names of any aliases for the given module or atom.
Examples
iex> alias Foo.Bar
iex> Bar
Foo.Bar
iex> Macro.Env.lookup_alias_as(__ENV__, Foo.Bar)
[Elixir.Bar]
iex> alias Foo.Bar, as: Baz
iex> Baz
Foo.Bar
iex> Macro.Env.lookup_alias_as(__ENV__, Foo.Bar)
[Elixir.Bar, Elixir.Baz]
iex> Macro.Env.lookup_alias_as(__ENV__, Unknown)
[]
@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.
Use only for introspection
This function does not emit compiler tracing events, which may block the compiler from correctly tracking dependencies. Use this function for reflection purposes but to do not use it to expand imports into qualified calls. Instead, use
expand_import/5
.
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 an environment in the guard context.
Returns an environment 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.