Код

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

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

Обзор

Функции

append_path(path): Добавляет путь в конец списка путей кода Erlang VM.
available_compiler_options(): Возвращает список доступных опций компилятора.
compile_quoted(quoted, file \\ "nofile"): Компилирует выражение в виде «цитированного» кода.
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 \\ []): Вычисляет (оценивает) содержимое, заданное в виде «цитированного» кода.
eval_string(string, binding \\ [], opts \\ []): Вычисляет (оценивает) содержимое, заданное в виде строки.
get_docs(module, kind): Возвращает документацию для данного модуля.
load_file(file, relative_to \\ nil): Загружает указанный файл.
loaded_files(): Выводит список всех загруженных файлов.
prepend_path(path): Добавляет путь в начало списка путей кода Erlang VM.
require_file(file, relative_to \\ nil): Загружает (и использует) заданный файл.
string_to_quoted(string, opts \\ []): Преобразует заданную строку в ее цитированную форму.
string_to_quoted!(string, opts \\ []): Преобразует заданную строку в ее цитированную форму.
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")

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

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

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, использовать относительные пути в цитированных узлах, предупреждения и ошибки, сгенерированные компилятором, 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}

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

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

При успешной загрузке модуля возвращается {: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}

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

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

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

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

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

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

`ensure_compiled/1`

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

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

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

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 представляет собой список ключевых слов опций среды.

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

Опции

Опции могут быть:

: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. Если файл уже потребован/загружен, require_file ничего не делает и возвращает 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