Docs4dev
Docs
elixir / 1.15 / macro.env.html

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 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 absolute 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

Types

context()
context_modules()
file()
line()
name_arity()
t()
variable()

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_alias_as(map, atom)

Returns the names of any aliases for the given module or atom.

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.

prune_compile_info(env)

Prunes compile information from 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.Env in the match context.

vars(env)

Returns a list of variables in the current environment.

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()}

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_alias_as(map, atom)Source

@spec lookup_alias_as(t(), atom()) :: [atom()]

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)
[]

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)

prune_compile_info(env)Source

@spec prune_compile_info(t()) :: t()

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.

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.15.4/Macro.Env.html