Source Macro.Env

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

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

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

def make_custom_env do
  import SomeModule, only: [some_function: 2], warn: false
  alias A.B.C, warn: false
  __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(env, atom): Возвращает псевдоним для данного атома.
fetch_macro_alias(env, atom): Возвращает псевдоним макроса для данного атома.
has_var?(env, var): Проверяет, принадлежит ли переменная окружению.
in_guard?(env): Возвращает значение, указывающее, находится ли среда компиляции внутри условия.
in_match?(env): Возвращает значение, указывающее, находится ли среда компиляции внутри ветви совпадения.
location(env): Возвращает список ключевых слов, содержащий информацию о файле и строке в качестве ключей.
lookup_alias_as(env, atom): Возвращает имена любых псевдонимов для данного модуля или атома.
lookup_import(env, name_arity): Возвращает модули, из которых был импортирован указанный {name, arity}.
prepend_tracer(env, tracer): Добавляет отслеживатель в начало списка отслеживателей в окружении.
prune_compile_info(env): Удаляет информацию о компиляции из окружения.
required?(env, module): Возвращает 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(env, 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(env, atom)Source

@spec fetch_macro_alias(t(), atom()) :: {:ok, atom()} | :error

Получает макро-псевдоним для данного атома.

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

Макро-псевдоним используется только внутри расширений с использованием `quote`. См. 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()

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

in_match?(env)Source

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

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

location(env)Source

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

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

lookup_alias_as(env, 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(env, name_arity)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?(env, module)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()]

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

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

© 2012-2024 The Elixir Team
Licensed under the Apache License, Version 2.0.
https://hexdocs.pm/elixir/1.16.3/Macro.Env.html