Код

Утилиты для управления компиляцией кода, оценкой кода и загрузкой кода.

Этот модуль дополняет Erlang’s :code модуль, добавляя поведение, специфичное для Elixir. Почти все функции в этом модуле имеют глобальные побочные эффекты на поведение Elixir.

Резюме

Функции

append_path(path): Добавляет путь в конец списка путей к коду Erlang VM.
available_compiler_options(): Возвращает список доступных параметров компилятора.
compile_quoted(quoted, file \\ "nofile"): Компилирует выражение в виде quoted.
compile_string(string, file \\ "nofile"): Компилирует заданную строку.
compiler_options(): Получает параметры компиляции из сервера кода.
compiler_options(opts): Устанавливает параметры компиляции.
delete_path(path): Удаляет путь из списка путей к коду Erlang VM. Это список каталогов, используемых Erlang VM для поиска кода модулей.
ensure_compiled(module): Убеждается, что указанный модуль скомпилирован и загружен.
ensure_compiled?(module): Убеждается, что указанный модуль скомпилирован и загружен.
ensure_loaded(module): Убеждается, что указанный модуль загружен.
ensure_loaded?(module): Убеждается, что указанный модуль загружен.
eval_file(file, relative_to \\ nil): Вычисляет заданный файл.
eval_quoted(quoted, binding \\ [], opts \\ []): Вычисляет содержимое в виде quoted.
eval_string(string, binding \\ [], opts \\ []): Вычисляет содержимое, заданное string.
get_docs(module, kind): Возвращает документацию для указанного модуля.
load_file(file, relative_to \\ nil): Загружает заданный файл.
loaded_files(): Отображает все загруженные файлы.
prepend_path(path): Добавляет путь в начало списка путей к коду Erlang VM.
require_file(file, relative_to \\ nil): Требует указанный file.
string_to_quoted(string, opts \\ []): Преобразует заданную строку в её представление в виде quoted.
string_to_quoted!(string, opts \\ []): Преобразует заданную строку в её представление в виде quoted.
unload_files(files): Удаляет файлы из списка загруженных файлов.

Функции

append_path(path)

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

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

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

Примеры

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

Code.append_path("/does_not_exist") #=> {:error, :bad_directory}

available_compiler_options()

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

См. Code.compiler_options/1 для дополнительной информации.

Примеры

iex> Code.available_compiler_options
[:docs, :debug_info, :ignore_module_conflict, :relative_paths, :warnings_as_errors]

compile_quoted(quoted, file \\ "nofile")

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

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

compile_string(string, file \\ "nofile")

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

Для компиляции многих файлов сразу, см. Kernel.ParallelCompiler.files/2.

compiler_options()

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

См. compiler_options/1 для получения дополнительной информации.

Примеры

Code.compiler_options
#=> %{debug_info: true, docs: true,
      warnings_as_errors: false, ignore_module_conflict: false}

compiler_options(opts)

Устанавливает параметры компиляции.

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

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

:docs - когда true, сохраняет документацию в скомпилированном модуле, true по умолчанию
:debug_info - когда true, сохраняет отладочную информацию в скомпилированном модуле; это позволяет разработчику восстановить исходный код, false по умолчанию
:ignore_module_conflict - когда true, переопределяет уже определённые модули без вывода ошибок, false по умолчанию
:relative_paths - когда true, использует относительные пути в узлах quoted, предупреждения и ошибки, генерируемые компилятором, true по умолчанию. Обратите внимание, что отключение этого параметра не повлияет на предупреждения и ошибки во время выполнения.
:warnings_as_errors - вызывает сбой компиляции при появлении предупреждений

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

Примеры

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

delete_path(path)

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

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

Примеры

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

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

ensure_compiled(module)

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

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

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

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

См. ensure_loaded/1 для получения дополнительной информации о загрузке модулей и о том, когда использовать ensure_loaded/1 или ensure_compiled/1.

ensure_compiled?(module)

ensure_compiled?(module()) :: boolean()

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

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

ensure_loaded(module)

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

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

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

Загрузка кода в Erlang VM

Erlang имеет два режима загрузки кода: интерактивный и встроенный.

По умолчанию Erlang VM работает в интерактивном режиме, где модули загружаются по мере необходимости. В режиме встроенной загрузки происходит обратное: все модули должны быть загружены заранее или явно.

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

Code.ensure_compiled/1

Elixir также содержит функцию ensure_compiled/1, которая является надмножеством ensure_loaded/1.

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

ensure_compiled/1 приостанавливает текущий процесс, пока модуль, от которого мы зависим, не станет доступным.

В большинстве случаев ensure_loaded/1 достаточно. ensure_compiled/1 необходимо использовать в редких случаях, обычно связанных с макросами, которые требуют вызова модуля для получения информации обратного вызова.

Примеры

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

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

ensure_loaded?(module)

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

Примеры

iex> Code.ensure_loaded?(Atom)
true

eval_file(file, relative_to \\ nil)

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

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

В то время как load_file загружает файл и возвращает загруженные модули и их байт-код, eval_file просто вычисляет содержимое файла и возвращает результат вычисления и его связи.

eval_quoted(quoted, binding \\ [], opts \\ [])

Вычисляет содержимое с использованием цитирования.

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

См. eval_string/3 для описания связей и параметров.

Примеры

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

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

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

eval_string(string, binding \\ [], opts \\ [])

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

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

Параметры

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

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

Кроме того, можно настроить следующие значения области:

:aliases - список кортежей с псевдонимом и его целевым объектом
:requires - список требуемых модулей
:functions - список кортежей, где первый элемент — модуль, а второй — список импортированных имен функций и арности; список имён функций и арности должен быть отсортирован
:macros - список кортежей, где первый элемент — модуль, а второй — список импортированных имён макросов и арности; список имён функций и арности должен быть отсортирован

Обратите внимание, что установка любого из вышеперечисленных значений перезаписывает значения по умолчанию Elixir. Например, установка :requires на [], больше не будет автоматически требовать модуль Kernel; точно так же установка :macros больше не будет автоматически импортировать макросы Kernel, такие как if/2, case/2 и т.д.

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

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

Примеры

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

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

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

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

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

get_docs(module, kind)

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

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

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

Возвращаемое значение зависит от значения kind:

:docs - список всех строк документации, прикреплённых к функциям и макросам с помощью атрибута @doc
:moduledoc - кортеж {<line>, <doc>}, где line — строка, с которой начинается определение модуля, а doc — строка, прикреплённая к модулю с помощью атрибута @moduledoc
:callback_docs - список всех строк документации, прикреплённых к @callbacks с помощью атрибута @doc
:type_docs - список всех строк документации, прикреплённых к вызовам обратного вызова @type с помощью атрибута @typedoc
:all - список ключевых слов с :docs и :moduledoc, :callback_docs, и :type_docs.

Если модуль не найден, возвращает nil.

Примеры

# Get the module documentation
iex> {_line, text} = Code.get_docs(Atom, :moduledoc)
iex> String.split(text, "\n") |> Enum.at(0)
"Convenience functions for working with atoms."

# Module doesn't exist
iex> Code.get_docs(ModuleNotGood, :all)
nil

load_file(file, relative_to \\ nil)

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

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

Возвращает список кортежей {ModuleName, <<byte_code>>}, по одному кортежу для каждого модуля, определённого в файле.

Обратите внимание, что если load_file вызывается разными процессами одновременно, целевой файл будет загружаться многократно одновременно. Обратитесь к require_file/2, если вы не хотите, чтобы файл загружался многократно.

Примеры

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

loaded_files()

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

Примеры

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

prepend_path(path)

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

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

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

Примеры

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

Code.prepend_path("/does_not_exist") #=> {:error, :bad_directory}

require_file(file, relative_to \\ nil)

Требует указанный file.

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

Обратите внимание, что если require_file вызывается разными процессами одновременно, первый процесс, вызвавший require_file приобретает блокировку, а остальные блокируются, пока файл не станет доступным. То есть, если require_file вызывается N раз с заданным файлом, он будет загружен только один раз. Первый процесс, вызвавший require_file получит список загруженных модулей, остальные получат nil.

Обратитесь к load_file/2, если вы хотите, чтобы файл загружался несколько раз. Также см. unload_files/1

Примеры

Если код уже загружен, возвращается nil:

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

Если код ещё не загружен, возвращается то же, что и load_file/2:

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

string_to_quoted(string, opts \\ [])

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

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

Параметры

:file - имя файла, используемое в стеках вызовов и в файлах, сообщаемых макросом __ENV__/0
:line - строка, сообщаемая макросом __ENV__/0
:existing_atoms_only - при true, генерирует ошибку при обнаружении несуществующих атомов анализатором токенов

Macro.to_string/2

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

string_to_quoted!(string, opts \\ [])

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

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

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

unload_files(files)

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

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

Примеры

# Load EEx test code, unload file, check for functions still available
Code.load_file("../eex/test/eex_test.exs")
Code.unload_files(Code.loaded_files)
function_exported?(EExTest.Compiled, :before_compile, 0) #=> true