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

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

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

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

Примеры

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

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

Параметры

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

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

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

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

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

Примеры

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

Параметры

• :cache - если true, путь к коду кешируется при первом проходе, чтобы уменьшить количество операций с файловой системой. Требуется 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: это означает, что такой код может представлять угрозу для машины (например, выполняя системные команды). Не используйте 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. Для сохранения отдельных параметров и описания всех параметров см. put_compiler_option/2.

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

Примеры

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

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

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

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

Путь расширяется с помощью 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.

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

Путь расширяется с помощью 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]

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

Вычисляет заданное содержимое quoted в контексте binding и env.

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

Опции

• :prune_binding - (с версии 1.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()}
     | :invalid_beam}
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.

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

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

Примеры

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

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

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

Все пути расширяются с помощью 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),
  keyword()
) :: :ok

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

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

Параметры

• :snippet — требуется ли чтение фрагмента кода в местоположении диагностики. Поскольку это может повлиять на производительность, использование не рекомендуется во время выполнения. По умолчанию true.

@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.

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

• :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). Это можно использовать в сочетании с трассировщиком для получения локализованной информации об событиях, происходящих во время компиляции. По умолчанию [columns: true]. Этот параметр влияет только на функции компиляции кода, такие как 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.

См. 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 - (с версии v1.11.0) начальный столбец анализируемой строки. Значение по умолчанию 1.

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

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

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

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

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

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

• :emit_warnings (с версии v1.16.0) - при 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, else, do, и так далее)

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

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

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

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

Возвращает AST, если преобразование успешно, иначе выбрасывает исключение. Исключение — TokenMissingError в случае отсутствия токена (обычно, из-за незавершенного выражения), MismatchedDelimiterError (в случае несоответствия открывающего и закрывающего разделителей) и 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.

Если используется mix compile или Kernel.ParallelCompiler, обратите внимание, что они уже собирают и возвращают диагностические сообщения.

Опции

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

Обработка ошибок

with_diagnostics/2 не обрабатывает исключения автоматически. Вы можете перехватить их, добавив try/1 в fun:

{result, all_errors_and_warnings} =
  Code.with_diagnostics(fn ->
    try do
      {:ok, Code.compile_quoted(quoted)}
    rescue
      err -> {:error, err}
    end
  end)