@spec define_alias(t(), Macro.metadata(), module(), keyword()) ::
  {:ok, t()} | {:error, String.t()}

Определяет заданный as как псевдоним для module в среде.

Используется инструментами, которым нужно имитировать компилятор Elixir. Будет выведено соответствующее событие отслеживания компиляции :alias.

Дополнительные параметры

Принимает те же параметры, что и Kernel.SpecialForm.alias/2 плюс:

• :trace - если установлено в false, отключает трекеры компиляции и лексический трекер. Этот параметр должен использоваться только серверами языков и другими инструментами, которым нужно инспектировать код, не влияя на его компиляцию. Отключение трекера внутри макросов или обычной обработки кода крайне не рекомендуется, так как это мешает компилятору точно отслеживать зависимости

Примеры

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}

Если параметр :as не задан, псевдоним будет выведен из модуля:

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}

Если невозможно вывести псевдоним, возвращается ошибка:

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

Определяет заданный module как импортированный в среде.

Предполагается, что module доступен. Используется инструментами, которым нужно имитировать компилятор Elixir. Будет выведено соответствующее событие отслеживания компиляции :import.

Дополнительные параметры

Принимает те же параметры, что и Kernel.SpecialForm.import/2 плюс:

• :emit_warnings - выводить предупреждения, обнаруженные при определении импортов

• :trace - если установлено в false, отключает трекеры компиляции и лексический трекер. Этот параметр должен использоваться только серверами языков и другими инструментами, которым нужно инспектировать код, не влияя на его компиляцию. Отключение трекера внутри макросов или обычной обработки кода крайне не рекомендуется, так как это мешает компилятору точно отслеживать зависимости

• :info_callback - функция, используемая вместо Module.__info__/1. Функция будет вызвана с аргументом :functions или :macros. Она должна вернуть список пар "ключ-значение" {function, arity}. В случае ошибки используется метаданные модуля, основанные на module_info/1.

Примеры

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

Принимает те же параметры, что и 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

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

Определяет заданный module как необходимый в среде.

Не проверяет и не утверждает, что модуль доступен. Используется инструментами, которым нужно имитировать компилятор Elixir. Будет выведено соответствующее событие отслеживания компиляции :require.

Дополнительные параметры

Принимает те же параметры, что и Kernel.SpecialForm.require/2 плюс:

• :trace - если установлено в false, отключает трекеры компиляции и лексический трекер. Этот параметр должен использоваться только серверами языков и другими инструментами, которым нужно инспектировать код, не влияя на его компиляцию. Отключение трекера внутри макросов или обычной обработки кода крайне не рекомендуется, так как это мешает компилятору точно отслеживать зависимости

Примеры

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

Если параметр :as задан, также будет определен псевдоним:

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}

@spec expand_alias(t(), keyword(), [atom()], keyword()) :: {:alias, atom()} | :error

Расширяет псевдоним, заданный сегментами псевдонима.

Возвращает {:alias, alias} если сегменты являются списком атомов и псевдоним был найден. В противном случае возвращает :error.

Это расширение может выводить событие отслеживания :alias_expansion , но не :alias_reference.

Параметры

• :trace - если установлено в false, отключает трекеры компиляции и лексический трекер. Этот параметр должен использоваться только серверами языков и другими инструментами, которым нужно инспектировать код, не влияя на его компиляцию. Отключение трекера внутри макросов или обычной обработки кода крайне не рекомендуется, так как это мешает компилятору точно отслеживать зависимости

Примеры

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}

Если псевдонима нет или псевдоним начинается с Elixir. (что отключает алиасинг), возвращается :error:

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

Расширяет импорт, заданный name и arity.

Если импорт указывает на макрос, возвращается кортеж с модулем и функцией, которая расширяет макрос. Функция ожидает, что метаданные будут присоединены к расширению и аргументы макроса.

Если импорт указывает на функцию, возвращается кортеж с модулем и именем функции.

Если любой импорт найден, будет выведено соответствующее событие отслеживания компиляции.

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

Параметры

• :allow_locals - если установлено в false, не пытается захватить локальные макросы, определенные в текущем модуле в env

• :check_deprecations - если установлено в false, не проверяет устаревшие версии при расширении макросов

• :trace - если установлено в false, отключает трекеры компиляции и лексический трекер. Этот параметр должен использоваться только серверами языков и другими инструментами, которым нужно инспектировать код, не влияя на его компиляцию. Отключение трекера внутри макросов или обычной обработки кода крайне не рекомендуется, так как это мешает компилятору точно отслеживать зависимости

@spec expand_require(t(), keyword(), module(), atom(), arity(), keyword()) ::
  {:macro, module(), (Macro.metadata(), args :: [Macro.t()] -> Macro.t())}
  | :error

Расширяет require, заданный module, name, и arity.

Если require указывает на макрос, и модуль был загружен, возвращается кортеж с модулем и функцией, которая расширяет макрос. Функция ожидает, что метаданные будут присоединены к расширению и аргументы макроса. Соответствующее событие отслеживания компиляции :remote_macro будет выведено, если макрос найден (заметьте, событие :remote_function не выводится в случаях :error).

В противном случае возвращается :error.

Параметры

• :check_deprecations - если установлено в false, не проверяет устаревшие версии при расширении макросов

• :trace - если установлено в false, отключает трекеры компиляции и лексический трекер. Этот параметр должен использоваться только серверами языков и другими инструментами, которым нужно инспектировать код, не влияя на его компиляцию. Отключение трекера внутри макросов или обычной обработки кода крайне не рекомендуется, так как это мешает компилятору точно отслеживать зависимости

@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

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

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

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

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

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

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

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

@spec lookup_import(t(), name_arity()) :: [{:function | :macro, module()}]

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

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

Использовать только для интроспекции

Эта функция не генерирует события отслеживания компилятора, что может помешать компилятору правильно отслеживать зависимости. Используйте эту функцию для целей рефлексии, но не используйте её для расширения импортов в квалифицированные вызовы. Вместо этого используйте expand_import/5.

Примеры

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

@spec prepend_tracer(t(), module()) :: t()

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

Примеры

Macro.Env.prepend_tracer(__ENV__, MyCustomTracer)

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

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

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

@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

@spec stacktrace(t()) :: list()

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

@spec to_guard(t()) :: t()

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

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

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

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

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

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