Macro.Env

Структура, хранящая информацию об окружении во время компиляции.

Текущее окружение можно получить в любое время как __ENV__/0. Внутри макросов, окружение вызывающей стороны можно получить как __CALLER__/0.

Экземпляр Macro.Env не должен изменяться вручную. Если вам необходимо создать пользовательское окружение для передачи в Code.eval_quoted/3, используйте следующий трюк:

def make_custom_env do
  import SomeModule, only: [some_function: 2]
  alias A.B.C
  __ENV__
end

После этого вы можете вызвать make_custom_env(), чтобы получить структуру с требуемыми импортами и псевдонимами.

Она содержит следующие поля:

context - контекст окружения; он может быть nil (по умолчанию), :guard (внутри условия) или :match (внутри совпадения)
context_modules - список модулей, определённых в текущем контексте
file - текущее абсолютное имя файла как бинарное представление
function - кортеж, как {atom, integer}, где первый элемент — имя функции, а второй — её арность; возвращает nil если не внутри функции
line - текущая строка как целое число
module - текущее имя модуля

Следующие поля предназначены для внутреннего использования механизмом макрорасширения Elixir и не должны напрямую обращаться:

aliases
functions
macro_aliases
macros
lexical_tracker
requires
tracers
versioned_vars

Функции

fetch_alias(map, atom): Возвращает псевдоним для данного атома.
fetch_macro_alias(map, atom): Возвращает макро-псевдоним для данного атома.
has_var?(env, var): Проверяет, принадлежит ли переменная окружению.
in_guard?(env): Возвращает значение, обозначающее, находится ли текущее окружение компиляции внутри условия.
in_match?(env): Возвращает значение, обозначающее, находится ли текущее окружение компиляции внутри раздела совпадения.
location(env): Возвращает список ключевых слов, содержащий информацию о файле и строке в качестве ключей.
lookup_alias_as(map, atom): Возвращает имена любых псевдонимов для данного модуля или атома.
lookup_import(map, pair): Возвращает модули, из которых был импортирован данный {name, arity}.
prepend_tracer(env, tracer): Добавляет отслеживатель в начало списка отслеживателей в окружении.
prune_compile_info(env): Удаляет информацию о компиляции из окружения.
required?(map, mod): Возвращает true, если данный модуль был загружен.
stacktrace(env): Возвращает трассировку стека окружения.
to_match(env): Возвращает Macro.Env в контексте совпадения.
vars(env): Возвращает список переменных в текущем окружении.

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

Извлекает псевдоним для данного атома.

Возвращает {:ok, alias} если псевдоним существует, :error в противном случае.

Примеры

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

Извлекает макро-псевдоним для данного атома.

Возвращает {:ok, macro_alias} если псевдоним существует, :error в противном случае.

Макро-псевдоним используется только внутри раскрытия ссылок. См. fetch_alias/2 для более общего примера.

has_var?(env, var)Source

@spec has_var?(t(), variable()) :: boolean()

Проверяет, принадлежит ли переменная среде.

Примеры

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

Возвращает, находится ли среда компиляции в данный момент внутри условия.

in_match?(env)Source

@spec in_match?(t()) :: boolean()

Возвращает, находится ли среда компиляции в данный момент внутри ветви соответствия.

location(env)Source

@spec location(t()) :: keyword()

Возвращает список ключевых слов, содержащих информацию о файле и строке в качестве ключей.

lookup_alias_as(map, atom)Source

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

Возвращает имена всех псевдонимов для данного модуля или атома.

Примеры

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

Возвращает модули, из которых был импортирован данный {name, arity}.

Возвращает список кортежей из двух элементов в форме {:function | :macro, module}. Элементы в списке упорядочены произвольно, порядок не гарантируется.

Примеры

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

Добавляет отслеживатель в начало списка отслеживателей в среде.

Примеры

Macro.Env.prepend_tracer(__ENV__, MyCustomTracer)

prune_compile_info(env)Source

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

Удаляет информацию о компиляции из среды.

Это происходит, когда среда захватывается во время компиляции, например, в теле модуля, и затем используется для оценки кода после определения модуля.

required?(map, mod)Source

@spec required?(t(), module()) :: boolean()

Возвращает true, если данный модуль был загружен.

Примеры

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

Возвращает стек отслеживания среды.

to_match(env)Source

@spec to_match(t()) :: t()

Возвращает Macro.Env в контексте соответствия.

vars(env)Source

@spec vars(t()) :: [variable()]

Возвращает список переменных в текущей среде.

Каждая переменная определяется кортежем из двух элементов, где первый элемент — имя переменной в виде атома, а второй элемент — её контекст, который может быть атомом или целым числом.