View Source Macro.Env (Elixir v1.17.0-dev)
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__
endStruct 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; returnsnilif 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:
aliasesfunctionsmacro_aliasesmacroslexical_trackerrequirestracersversioned_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"}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
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}]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)
trueIf 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
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.
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})
falseReturns 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)
trueReturns 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.