Код

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

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

Краткое описание

Функции

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

Функции

append_path(path)

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

Это список каталогов, которые 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, :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 по умолчанию
: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. Это список каталогов, которые Erlang VM использует для поиска кода модулей.

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

Примеры

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

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

ensure_compiled(module)

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

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

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

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

ensure_compiled?(module)

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

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

ensure_loaded(module)

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

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

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

Загрузка кода в 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__ в качестве аргумента 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__ в качестве аргумента 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__
:line — строка, представленная в переменной __ENV__
: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