Код

@spec append_path(Path.t(), [{:cache, boolean()}]) :: true | false

Добавляет путь в список путей к коду Erlang VM.

Это список каталогов, используемых Erlang VM для поиска модулей. Список файлов управляется для каждого узла Erlang VM.

Путь расширяется с помощью Path.expand/1 перед добавлением. Путь должен существовать. Возвращает булево значение, указывающее, был ли путь успешно добавлен.

Примеры

Code.append_path(".")
#=> true

Code.append_path("/does_not_exist")
#=> false

Параметры

• :cache - (с версии v1.15.0) если истинно, путь к коду кэшируется при первом проходе, чтобы сократить операции с файловой системой. Требуется Erlang/OTP 26, в противном случае это пустая операция.

@spec append_paths([Path.t()], [{:cache, boolean()}]) :: :ok

Добавляет список путей к списку путей к коду Erlang VM.

Это список каталогов, используемых Erlang VM для поиска модулей. Список файлов управляется для каждого узла Erlang VM.

Все пути расширяются с помощью Path.expand/1 перед добавлением. Добавляются только существующие пути. Эта функция всегда возвращает :ok, независимо от того, сколько путей было добавлено. Используйте append_path/1, если вам нужен больший контроль.

Примеры

Code.append_paths([".", "/does_not_exist"])
#=> :ok

Параметры

• :cache - если истинно, путь к коду кэшируется при первом проходе, чтобы сократить операции с файловой системой. Требуется Erlang/OTP 26, в противном случае это пустая операция.

@spec available_compiler_options() :: [atom()]

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

Описание всех параметров см. в put_compiler_option/2.

Примеры

Code.available_compiler_options()
#=> [:docs, :debug_info, ...]

@spec can_await_module_compilation?() :: boolean()

Возвращает true, если текущий процесс может ожидать компиляции модуля.

При компиляции кода Elixir через Kernel.ParallelCompiler, который используется Mix и elixirc, вызов модуля, который еще не скомпилирован, заблокирует вызывающий процесс, пока модуль не станет доступен. Выполнение скриптов Elixir, например, передача имени файла в elixir, не ожидает.

@spec compile_file(binary(), nil | binary()) :: [{module(), binary()}]

Компилирует указанный файл.

Принимает relative_to в качестве аргумента, чтобы указать расположение файла.

Возвращает список кортежей, где первый элемент - имя модуля, а второй - его байткод (в виде двоичных данных). В отличие от require_file/2, он не отслеживает имя файла скомпилированного файла.

Если вы хотите получить результат вычисления файла, а не модулей, определенных в нем, см. eval_file/2.

Для одновременной компиляции многих файлов см. Kernel.ParallelCompiler.compile/2.

@spec compile_quoted(Macro.t(), binary()) :: [{module(), binary()}]

Компилирует выражение в виде котировки.

Возвращает список кортежей, где первый элемент - имя модуля, а второй - его байткод (в виде двоичных данных). В качестве второго аргумента может быть передан file, который будет использоваться для отчётов о предупреждениях и ошибках.

@spec compile_string(List.Chars.t(), binary()) :: [{module(), binary()}]

Компилирует заданную строку.

Возвращает список кортежей, где первый элемент - имя модуля, а второй - его байткод (в виде двоичных данных). В качестве второго аргумента может быть передан file, который будет использоваться для отчётов о предупреждениях и ошибках.

Предупреждение: string может быть любым кодом Elixir, и код может быть выполнен с теми же привилегиями, что и Erlang VM: это означает, что такой код может представлять угрозу для системы (например, выполняя системные команды). Не используйте compile_string/2 с ненадежными входными данными (например, строками, полученными из сети).

@spec compiler_options() :: map()

Получает все параметры компиляции из сервера кода.

Для получения отдельных параметров см. get_compiler_option/1. Описание всех параметров см. в put_compiler_option/2.

Примеры

Code.compiler_options()
#=> %{debug_info: true, docs: true, ...}

@spec compiler_options(Enumerable.t({atom(), term()})) :: %{
  optional(atom()) => term()
}

Сохраняет все заданные параметры компиляции.

Изменение параметров компиляции влияет на все процессы, выполняемые на узле Erlang VM. Для сохранения отдельных параметров и описание всех параметров см. put_compiler_option/2.

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

Примеры

Code.compiler_options(warnings_as_errors: true)
#=> %{warnings_as_errors: false}

@spec delete_path(Path.t()) :: boolean()

Удаляет путь из списка путей к коду Erlang VM.

Это список каталогов, используемых Erlang VM для поиска модулей. Список файлов управляется для каждого узла Erlang VM.

Путь расширяется с помощью Path.expand/1 перед удалением. Если путь не существует, эта функция возвращает false.

Примеры

Code.prepend_path(".")
Code.delete_path(".")
#=> true

Code.delete_path("/does_not_exist")
#=> false

@spec delete_paths([Path.t()]) :: :ok

Удаляет список путей из списка путей к коду Erlang VM.

Это список каталогов, используемых Erlang VM для поиска модулей. Список файлов управляется для каждого узла Erlang VM.

Путь расширяется с помощью Path.expand/1 перед удалением. Если путь не существует, эта функция возвращает false.

@spec ensure_all_loaded([module()]) :: :ok | {:error, [{module(), reason}]}
when reason: :badfile | :nofile | :on_load_failure

Убеждается, что указанные модули загружены.

Аналогично ensure_loaded/1, но принимает список модулей вместо одного модуля и загружает все из них.

Если все модули загружаются успешно, возвращает :ok. В противном случае возвращает {:error, errors}, где errors - список кортежей, содержащих модуль и причину его неудачи при загрузке.

Примеры

iex> Code.ensure_all_loaded([Atom, String])
:ok

iex> Code.ensure_all_loaded([Atom, DoesNotExist])
{:error, [{DoesNotExist, :nofile}]}

@spec ensure_all_loaded!([module()]) :: :ok

То же, что и ensure_all_loaded/1, но выбрасывает исключение, если какой-либо из модулей не может быть загружен.

@spec ensure_compiled(module()) ::
  {:module, module()}
  | {:error, :embedded | :badfile | :nofile | :on_load_failure | :unavailable}

Аналогично ensure_compiled!/1, но указывает, что вы можете продолжить без указанного модуля.

В то время как ensure_compiled!/1 указывает компилятору Elixir, что вы можете продолжить только при наличии указанного модуля, эта функция указывает, что вы можете продолжить компиляцию без указанного модуля.

Если модуль успешно загружается, возвращается {:module, module}. В противном случае возвращается {:error, reason} с причиной ошибки. Если проверяемый модуль в настоящее время находится в тупике компиляции, эта функция возвращает {:error, :unavailable}. Отсутствие доступности не обязательно означает, что модуль не существует, просто он в настоящее время недоступен, но может (или не может) стать доступным в будущем.

Поэтому, если вы можете продолжить только в случае наличия модуля, используйте ensure_compiled!/1 вместо него. В частности, не делайте так:

case Code.ensure_compiled(module) do
  {:module, _} -> module
  {:error, _} -> raise ...
end

См. документацию по модулю для получения дополнительной информации о загрузке кода.

@spec ensure_compiled!(module()) :: module()

Обеспечивает компиляцию и загрузку заданного модуля.

Если модуль уже загружен, он работает как пустая операция. Если модуль еще не был скомпилирован, ensure_compiled!/1 приостанавливает компиляцию вызывающего модуля, пока модуль, переданный ensure_compiled!/1, не станет доступным или пока все файлы текущего проекта не будут скомпилированы. Если компиляция завершится, а модуль не будет доступен или находится в тупике, генерируется ошибка.

Поскольку эта функция приостанавливает компиляцию, используйте ее осторожно. В частности, избегайте использования ее для угадывания, какие модули находятся в системе. Чрезмерное использование этой функции также может привести к тупикам, когда два модуля одновременно проверяют, скомпилирован ли другой. Это возвращает конкретный код недоступности, когда мы не можем успешно проверить, доступен ли модуль или нет.

См. документацию по модулю для получения дополнительной информации о загрузке кода.

@spec ensure_loaded(module()) ::
  {:module, module()}
  | {:error, :embedded | :badfile | :nofile | :on_load_failure}

Обеспечивает загрузку данного модуля.

Если модуль уже загружен, это работает как пустая операция. Если модуль еще не загружен, он пытается загрузить его.

Если модуль успешно загружен, возвращается {:module, module}. В противном случае возвращается {:error, reason} с причиной ошибки.

См. документацию по модулю для получения дополнительной информации о загрузке кода.

Примеры

iex> Code.ensure_loaded(Atom)
{:module, Atom}

iex> Code.ensure_loaded(DoesNotExist)
{:error, :nofile}

@spec ensure_loaded!(module()) :: module()

То же, что и ensure_loaded/1, но генерирует исключение, если модуль не может быть загружен.

@spec ensure_loaded?(module()) :: boolean()

Обеспечивает загрузку данного модуля.

Аналогично ensure_loaded/1, но возвращает true если модуль уже загружен или был успешно загружен. В противном случае возвращает false.

Примеры

iex> Code.ensure_loaded?(String)
true

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

Принимает либо Macro.Env, который затем обрезается и подготавливается, либо список параметров. Возвращает среду, готовую к вычислению.

Большинство функций в этом модуле автоматически подготовят заданную среду для вычисления, поэтому вам не нужно явно вызывать эту функцию, за исключением eval_quoted_with_env/3, которая была разработана именно для вызова в цикле, для реализации таких функций, как интерактивные оболочки или что-либо ещё с несколькими вычислениями.

Параметры

Если среда не задана, параметры могут быть:

• :file - файл, который будет рассматриваться при вычислении

• :line - строка, с которой начинается скрипт

@spec eval_file(binary(), nil | binary()) :: {term(), binding()}

Вычисляет указанный файл.

Принимает relative_to в качестве аргумента, чтобы указать, где находится файл.

В то время как require_file/2 и compile_file/2 возвращают загруженные модули и их байткод, eval_file/2 просто вычисляет содержимое файла и возвращает результат вычисления и его привязку (точно такой же возвращаемый результат, как у eval_string/3).

@spec eval_quoted(Macro.t(), binding(), Macro.Env.t() | keyword()) ::
  {term(), binding()}

Вычисляет цитируемое содержимое.

Предупреждение: Вызов этой функции внутри макроса считается плохой практикой, так как она попытается оценить значения времени выполнения во время компиляции. Аргументы макросов обычно преобразуются путем их извлечения из цитирования в возвращаемых цитируемых выражениях (вместо оценки).

См. eval_string/3 для описания binding и opts.

Примеры

iex> contents = quote(do: var!(a) + var!(b))
iex> {result, binding} = Code.eval_quoted(contents, [a: 1, b: 2], file: __ENV__.file, line: __ENV__.line)
iex> result
3
iex> Enum.sort(binding)
[a: 1, b: 2]

Для удобства вы можете передать __ENV__/0 в качестве аргумента opts и все параметры будут автоматически извлечены из текущей среды:

iex> contents = quote(do: var!(a) + var!(b))
iex> {result, binding} = Code.eval_quoted(contents, [a: 1, b: 2], __ENV__)
iex> result
3
iex> Enum.sort(binding)
[a: 1, b: 2]

Вычисляет данные quoted с binding и env.

Эта функция предназначена для вызова в цикле, для реализации таких функций, как интерактивные оболочки или что-либо ещё с несколькими вычислениями. Поэтому в первый раз, когда вы вызываете эту функцию, вы должны вычислить начальную среду с помощью env_for_eval/1. Остальные вызовы должны передать среду, которая была возвращена этой функцией.

Параметры

• :prune_binding - (с версии v1.14.2) обрезать привязку, сохраняя только переменные, считываемые или записываемые вычисляемым кодом. Обратите внимание, что переменные, используемые модулями, всегда обрезаются, даже если используются модулями позже. Вы можете отправить событие отслеживания :on_module и получить доступ к переменным, используемым модулем, из его среды.

@spec eval_string(List.Chars.t(), binding(), Macro.Env.t() | keyword()) ::
  {term(), binding()}

Вычисляет содержимое, заданное string.

Аргумент binding — список всех переменных и их значений. Аргумент opts — список параметров среды в виде ключевых слов.

Предупреждение: string может быть любым кодом Elixir и будет выполняться с теми же правами, что и виртуальная машина Erlang: это означает, что такой код может нанести ущерб машине (например, выполнив системные команды). Не используйте eval_string/3 с недоверенными данными (например, строками, поступающими из сети).

Параметры

Параметры могут быть:

• :file - файл, который будет рассматриваться при вычислении

• :line - строка, с которой начинается скрипт

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

Возвращает кортеж вида {value, binding}, где value — значение, возвращенное из вычисления string. Если при вычислении string произошла ошибка, будет поднято исключение.

binding — список с именами всех переменных и их значениями после вычисления string. Ключи привязки обычно атомы, но они могут быть кортежем для переменных, определенных в другом контексте. Имена расположены в произвольном порядке.

Примеры

iex> {result, binding} = Code.eval_string("a + b", [a: 1, b: 2], file: __ENV__.file, line: __ENV__.line)
iex> result
3
iex> Enum.sort(binding)
[a: 1, b: 2]

iex> {result, binding} = Code.eval_string("c = a + b", [a: 1, b: 2], __ENV__)
iex> result
3
iex> Enum.sort(binding)
[a: 1, b: 2, c: 3]

iex> {result, binding} = Code.eval_string("a = a + b", [a: 1, b: 2])
iex> result
3
iex> Enum.sort(binding)
[a: 3, b: 2]

Для удобства вы можете передать __ENV__/0 в качестве аргумента opts и все импорты, require и алиасы, определенные в текущей среде, будут автоматически перенесены:

iex> {result, binding} = Code.eval_string("a + b", [a: 1, b: 2], __ENV__)
iex> result
3
iex> Enum.sort(binding)
[a: 1, b: 2]

@spec fetch_docs(module() | String.t()) ::
  {:docs_v1, annotation, beam_language, format, module_doc :: doc_content,
   metadata, docs :: [doc_element]}
  | {:error, :module_not_found | :chunk_not_found | {:invalid_chunk, binary()}}
when annotation: :erl_anno.anno(),
     beam_language: :elixir | :erlang | atom(),
     doc_content: %{optional(binary()) => binary()} | :none | :hidden,
     doc_element:
       {{kind :: atom(), function_name :: atom(), arity()}, annotation,
        signature, doc_content, metadata},
     format: binary(),
     signature: [binary()],
     metadata: map()

Возвращает документацию для заданного модуля или пути к файлу .beam.

При указании имени модуля, оно находит его BEAM-код и считывает документацию из него.

При указании пути к файлу .beam, оно загрузит документацию непосредственно из этого файла.

Возвращает терм, хранящийся в блоке документации в формате, определенном в EEP 48, или {:error, reason} если блок не доступен.

Примеры

# Module documentation of an existing module
iex> {:docs_v1, _, :elixir, _, %{"en" => module_doc}, _, _} = Code.fetch_docs(Atom)
iex> module_doc |> String.split("\n") |> Enum.at(0)
"Atoms are constants whose values are their own name."

# A module that doesn't exist
iex> Code.fetch_docs(ModuleNotGood)
{:error, :module_not_found}

@spec format_file!(
  binary(),
  keyword()
) :: iodata()

Форматирует файл.

См. format_string!/2 для получения дополнительной информации о форматировании кода и доступных параметрах.

@spec get_compiler_option(atom()) :: term()

Возвращает значение заданного параметра компиляции.

Описание всех параметров см. в put_compiler_option/2.

Примеры

Code.get_compiler_option(:debug_info)
#=> true

@spec loaded?(module()) :: boolean()

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

Эта функция не пытается загрузить модуль. Для такого поведения можно использовать ensure_loaded?/1.

Примеры

iex> Code.loaded?(Atom)
true

iex> Code.loaded?(NotYetLoaded)
false

@spec prepend_path(Path.t(), [{:cache, boolean()}]) :: boolean()

Добавляет путь в начало списка путей к коду Erlang VM.

Это список директорий, используемых Erlang VM для поиска модулей. Список файлов управляется на узел Erlang VM.

Путь расширяется с помощью Path.expand/1 перед добавлением в начало. Требуется, чтобы путь существовал. Возвращает boolean, указывающий, был ли путь успешно добавлен.

Примеры

Code.prepend_path(".")
#=> true

Code.prepend_path("/does_not_exist")
#=> false

Параметры

• :cache - (с версии v1.15.0) если true, путь к коду кешируется при первом проходе, чтобы уменьшить операции с файловой системой. Требуется Erlang/OTP 26, в противном случае это бесполезно.

@spec prepend_paths([Path.t()], [{:cache, boolean()}]) :: :ok

Добавляет список путей в начало списка путей к коду Erlang VM.

Это список директорий, используемых Erlang VM для поиска модулей. Список файлов управляется на узел Erlang VM.

Все пути расширяются с помощью Path.expand/1 перед добавлением в начало. Добавляются только существующие пути. Функция всегда возвращает :ok, независимо от того, сколько путей было добавлено. Используйте prepend_path/1, если вам нужен больший контроль.

Примеры

Code.prepend_paths([".", "/does_not_exist"])
#=> :ok

Параметры

• :cache - если true, путь к коду кешируется при первом проходе, чтобы уменьшить операции с файловой системой. Требуется Erlang/OTP 26, в противном случае это бесполезно.

@spec print_diagnostic(diagnostic(:warning | :error)) :: :ok

Выводит диагностическое сообщение в стандартный поток ошибок.

Диагностическое сообщение возвращается либо функцией Kernel.ParallelCompiler, либо Code.with_diagnostics/2.

@spec purge_compiler_modules() :: {:ok, non_neg_integer()}

Очистка модулей компилятора.

Компилятор использует временные модули для компиляции кода. Например, elixir_compiler_1, elixir_compiler_2, и так далее. В случае, если скомпилированный код хранит ссылки на анонимные функции или подобное, компилятор Elixir может не смочь освободить эти модули, оставляя в памяти лишний код и, в конечном итоге, приводя к таким модулям, как elixir_compiler_12345.

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

Эту функцию следует вызывать только в том случае, если у вас есть узел с длительной работой, который постоянно оценивает код.

Она возвращает {:ok, number_of_modules_purged}.

@spec put_compiler_option(atom(), term()) :: :ok

Сохраняет параметр компиляции.

Изменение параметров компиляции влияет на все процессы, работающие на данном узле Erlang VM.

Доступные параметры:

• :docs - если true, сохраняет документацию в скомпилированном модуле. По умолчанию true.

• :debug_info - если true, сохраняет отладочную информацию в скомпилированном модуле. По умолчанию true. Это позволяет инструментам статического анализа частично восстановить исходный код. Поэтому отключение :debug_info не рекомендуется, так как это лишает компилятор Elixir и других инструментов возможности предоставлять обратную связь. Если вы хотите удалить :debug_info при развертывании, такие инструменты, как mix release уже делают это по умолчанию. Кроме того, mix test отключает его через параметр конфигурации проекта :test_elixirc_options . Этот параметр также может быть переопределен для каждого модуля с помощью директивы @compile.

• :ignore_already_consolidated (с версии v1.10.0) - если true, не предупреждает, когда протокол уже объединен, и добавляется новое реализация. По умолчанию false.

• :ignore_module_conflict - если true, не предупреждает, когда модуль уже определен. По умолчанию false.

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

• :warnings_as_errors - заставляет компиляцию завершиться ошибкой при генерации предупреждений. По умолчанию false.

• :no_warn_undefined (с версии v1.10.0) - список модулей и кортежей {Mod, fun, arity}, которые не будут генерировать предупреждения о том, что модуль или функция не существует во время компиляции. Передайте атом :all, чтобы пропустить предупреждение для всех неопределенных функций. Это может быть полезно при динамической компиляции. По умолчанию [].

• :tracers (с версии v1.10.0) - список трейсеров (модулей), которые будут использоваться во время компиляции. Смотрите документацию модуля для получения дополнительной информации. По умолчанию [].

• :parser_options (с версии v1.10.0) - ключевое слово с параметрами, которые будут переданы парсеру при компиляции файлов. Принимает те же параметры, что и string_to_quoted/2 (за исключением параметров, изменяющих сам AST). Это можно использовать в сочетании с трейсером для получения локализованной информации о событиях, происходящих во время компиляции. По умолчанию []. Этот параметр влияет только на функции компиляции кода, такие как compile_string/2 и compile_file/2, но не на string_to_quoted/2 и аналогичные, так как последний используется для других целей, помимо компиляции.

• :on_undefined_variable (с версии v1.15.0) - либо :raise , либо :warn. При :raise (по умолчанию) неопределенные переменные вызывают ошибку компиляции. Вы можете установить его в :warn , если вы хотите, чтобы неопределенные переменные генерировали предупреждение и расширялись в локальный вызов функции с нулевой арностью с тем же именем (например, node расширялось как node()). Такое поведение :warn существует только по соображениям совместимости при работе со старыми зависимостями.

Она всегда возвращает :ok. Вызывает ошибку для неверных параметров.

Примеры

Code.put_compiler_option(:debug_info, true)
#=> :ok

@spec quoted_to_algebra(
  Macro.t(),
  keyword()
) :: Inspect.Algebra.t()

Преобразует цитируемое выражение в документ алгебры, используя правила форматирования Elixir.

Документ алгебры можно преобразовать в строку, вызвав:

doc
|> Inspect.Algebra.format(:infinity)
|> IO.iodata_to_binary()

Для высокоуровневой функции, выполняющей то же самое, см. Macro.to_string/1.

Учитываемые при форматировании моменты

AST Elixir не содержит метаданных для литералов, таких как строки, списки или кортежи с двумя элементами, что означает, что сгенерированный документ алгебры не будет учитывать все пользовательские настройки, а комментарии могут быть неправильно размещены. Для достижения лучших результатов можно использовать опции :token_metadata, :unescape и :literal_encoder для string_to_quoted/2, чтобы предоставить форматировщику дополнительную информацию:

[
  literal_encoder: &{:ok, {:__block__, &2, [&1]}},
  token_metadata: true,
  unescape: false
]

Это создаст AST, содержащий информацию, такую как do начало и конец строки или разделители сигила, и путем обертывания литералов в блоки они теперь могут хранить метаданные, такие как номер строки, разделитель строки и экранированные последовательности, или форматирование целых чисел (например, 0x2a вместо 47). Однако, обратите внимание, что этот AST некорректен. Если вы его оцените, он не будет иметь тех же семантических свойств, что и обычный AST Elixir, из-за опций :unescape и :literal_encoder. Однако эти опции полезны, если вы занимаетесь манипулированием исходного кода, где важно сохранить пользовательские варианты и расположение комментариев.

Опции

• :comments - список комментариев, связанных с цитируемым выражением. Значение по умолчанию []. Рекомендуется передать обе опции :token_metadata и :literal_encoder функции string_to_quoted_with_comments/2 для правильного размещения комментариев

• :escape - когда true, экранированные последовательности, такие как \n, будут экранированы в \\n. Если опция :unescape была установлена в false при использовании string_to_quoted/2, установка этой опции в false предотвратит двойное экранирование последовательностей. Значение по умолчанию true.

• :locals_without_parens - список пар «имя-арность» в виде ключевых слов, которые следует сохранять без скобок по возможности. Арность может быть атомом :*, что подразумевает все арности этого имени. Форматировщик уже содержит список функций, а эта опция дополняет этот список.

• :syntax_colors - список цветов, используемых для цветного вывода. См. Inspect.Opts для получения дополнительной информации.

@spec require_file(binary(), nil | binary()) :: [{module(), binary()}] | nil

Загружает указанный file.

Принимает relative_to в качестве аргумента, чтобы указать, где находится файл. Если файл уже был загружен, require_file/2 ничего не делает и возвращает nil.

Обратите внимание, что если require_file/2 вызывается разными процессами одновременно, первый вызвавший процесс require_file/2 получает блокировку, а остальные будут блокироваться до тех пор, пока файл не станет доступным. Это означает, что если require_file/2 вызывается более одного раза с данным файлом, этот файл будет скомпилирован только один раз. Первый процесс, вызывающий require_file/2, получит список загруженных модулей, остальные получат nil. Список требуемых файлов управляется на узле Erlang VM.

См. compile_file/2, если вы хотите скомпилировать файл без отслеживания его имен файлов. Наконец, если вы хотите получить результат вычисления файла, а не модулей, определенных в нём, см. eval_file/2.

Примеры

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

modules = Code.require_file("eex_test.exs", "../eex/test")
List.first(modules)
#=> {EExTest.Compiled, <<70, 79, 82, 49, ...>>}

Если файл был загружен, возвращается nil:

Code.require_file("eex_test.exs", "../eex/test")
#=> nil

@spec required_files() :: [binary()]

Список всех загруженных файлов.

Примеры

Code.require_file("../eex/test/eex_test.exs")
List.first(Code.required_files()) =~ "eex_test.exs"
#=> true

@spec string_to_quoted(
  List.Chars.t(),
  keyword()
) ::
  {:ok, Macro.t()}
  | {:error, {location :: keyword(), binary() | {binary(), binary()}, binary()}}

Преобразует данную строку в ее цитируемую форму.

Возвращает {:ok, quoted_form} в случае успеха, {:error, {meta, message_info, token}} в противном случае.

Опции

• :file - имя файла, которое будет сообщено в случае ошибок при разборе. Значение по умолчанию "nofile".

• :line - начальная строка анализируемой строки. Значение по умолчанию 1.

• :column - (с версии 1.11.0) начальная колонка анализируемой строки. Значение по умолчанию 1.

• :columns - если true, добавить ключ :column к метаданным цитирования. Значение по умолчанию false.

• :unescape (с версии 1.10.0) - если false, сохраняет экранированные последовательности. Например, "null byte\\t\\x00" сохранится без изменений вместо преобразования в битовую строку. Обратите внимание, что если вы установите эту опцию в false, результирующий AST больше не будет действительным, но может быть полезен при анализе/преобразовании исходного кода, обычно в сочетании с quoted_to_algebra/2. Значение по умолчанию true.

• :existing_atoms_only - если true, вызывать ошибку при обнаружении несуществующих атомов токенизатором. Значение по умолчанию false.

• :token_metadata (с версии 1.10.0) - если true, включает метаданные, относящиеся к токенам, в AST выражения, такие как метаданные для токенов do и end, для закрывающих токенов, конца выражений, а также разделителей для сигилов. См. Macro.metadata/0. Значение по умолчанию false.

• :literal_encoder (с версии 1.10.0) - как кодировать литералы в AST. Это должна быть функция, которая принимает два аргумента, литерал и его метаданные, и возвращает {:ok, ast :: Macro.t} или {:error, reason :: binary}. Если вы возвращаете что-либо, кроме самого литерала в качестве term, AST больше не будет действительным. Эта опция всё ещё может быть полезной для текстового анализа исходного кода.

• :static_atoms_encoder - функция кодирования статических атомов, см. раздел «Функция :static_atoms_encoder» ниже. Обратите внимание, что эта опция переопределяет поведение :existing_atoms_only для статических атомов, но :existing_atoms_only по-прежнему используется для динамических атомов, таких как атомы с интерполяцией.

• :warn_on_unnecessary_quotes - если false, не выводит предупреждение, когда у атомов, ключевых слов или вызовов есть лишние кавычки. Значение по умолчанию true.

Macro.to_string/2

Обратная операция преобразования строки в её цитируемую форму - это Macro.to_string/2, которая преобразует цитируемую форму в строковое/двоичное представление.

Функция :static_atoms_encoder

Когда static_atoms_encoder: &my_encoder/2 передаётся как аргумент, my_encoder/2 вызывается всякий раз, когда токенизатор нуждается в создании «статического» атома. Статические атомы в AST работают как псевдонимы, удалённые вызовы, локальные вызовы, имена переменных, обычные атомы и списки ключевых слов.

Функция-кодировщик получит имя атома (как двоичную строку) и список ключевых слов с текущим файлом, строкой и столбцом. Она должна вернуть {:ok, token :: term} | {:error, reason :: binary}.

Функция-кодировщик должна создать атом из данной строки. Для создания корректного AST требуется вернуть {:ok, term}, где term - атом. Возвращение чего-либо помимо атома возможно, но в этом случае AST больше не будет «действительным», так как его нельзя использовать для компиляции или оценки кода Elixir. Сценарий применения - использование парсера Elixir в пользовательском интерфейсе без истощения таблицы атомов.

Функция кодирования атомов не вызывается для всех атомов, присутствующих в AST. Она не будет вызвана для следующих атомов:

• операторы (:+, :-, и т.д.)

• ключевые слова синтаксиса (fn, do, else, и т.д.)

• атомы, содержащие интерполяцию (:"#{1 + 1} is two"), так как эти атомы создаются во время выполнения

• атомы, используемые для представления сигилов с одной буквой, таких как :sigil_X (но многобуквенные сигилы, такие как :sigil_XYZ кодируются).

@spec string_to_quoted!(
  List.Chars.t(),
  keyword()
) :: Macro.t()

Преобразует заданную строку в её форматированную форму.

Возвращает AST, если преобразование успешно, в противном случае генерирует исключение. Исключение является TokenMissingError в случае отсутствия токена (обычно, из-за незаконченности выражения), SyntaxError в противном случае.

См. string_to_quoted/2 для информации об опциях.

@spec string_to_quoted_with_comments(
  List.Chars.t(),
  keyword()
) ::
  {:ok, Macro.t(), [map()]} | {:error, {location :: keyword(), term(), term()}}

Преобразует заданную строку в её форматированную форму и список комментариев.

Эта функция полезна при выполнении текстовых изменений в исходном коде, сохраняя при этом информацию о комментариях и позициях литералов.

Возвращает {:ok, quoted_form, comments} при успехе, {:error, {line, error, token}} в противном случае.

Комментарии являются картами со следующими полями:

• :line - Номер строки исходного кода

• :text - Полный текст комментария, включая ведущий #

• :previous_eol_count - Количество символов конца строки между комментарием и предыдущим узлом AST или комментарием

• :next_eol_count - Количество символов конца строки между комментарием и следующим узлом AST или комментарием

См. string_to_quoted/2 для информации об опциях.

Примеры

iex> Code.string_to_quoted_with_comments("""
...> :foo
...>
...> # Hello, world!
...>
...>
...> # Some more comments!
...> """)
{:ok, :foo, [
  %{line: 3, column: 1, previous_eol_count: 2, next_eol_count: 3, text: "# Hello, world!"},
  %{line: 6, column: 1, previous_eol_count: 3, next_eol_count: 1, text: "# Some more comments!"},
]}

iex> Code.string_to_quoted_with_comments(":foo # :bar")
{:ok, :foo, [
  %{line: 1, column: 6, previous_eol_count: 0, next_eol_count: 0, text: "# :bar"}
]}

@spec string_to_quoted_with_comments!(
  List.Chars.t(),
  keyword()
) :: {Macro.t(), [map()]}

Преобразует заданную строку в её форматированную форму и список комментариев.

Возвращает AST и список комментариев при успехе, в противном случае генерирует исключение. Исключение является TokenMissingError в случае отсутствия токена (обычно, из-за незаконченности выражения), SyntaxError в противном случае.

См. string_to_quoted/2 для информации об опциях.

@spec unrequire_files([binary()]) :: :ok

Удаляет файлы из списка требуемых файлов.

Модули, определённые в файлах, не удаляются; вызов этой функции только удаляет их из списка, позволяя их повторно потребовать.

Список файлов управляется по узлу Erlang VM.

Примеры

# Require EEx test code
Code.require_file("../eex/test/eex_test.exs")

# Now unrequire all files
Code.unrequire_files(Code.required_files())

# Note that modules are still available
function_exported?(EExTest.Compiled, :before_compile, 0)
#=> true

@spec with_diagnostics(
  keyword(),
  (-> result)
) :: {result, [diagnostic(:warning | :error)]}
when result: term()

Выполняет заданную fun и захватывает все диагностики.

Диагностики — это предупреждения и ошибки, выданные компилятором и функциями, такими как IO.warn/2.

Опции

• :log - если диагностики должны регистрироваться по мере их появления. По умолчанию false.