Исключение поведение

Функции для форматирования бросков/перехватов/выходов и исключений.

Обратите внимание, что трассировки стека в Elixir обновляются при бросках, ошибках и выходах. Например, в любой момент System.stacktrace/0 вернёт трассировку стека последнего броска/ошибки/выхода, произошедшего в текущем процессе.

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

Обзор

Типы

kind(): Тип, обрабатываемый функциями форматирования
stacktrace()
stacktrace_entry()
t(): Тип исключения

Функции

blame(kind, error, stacktrace): Добавляет информацию к исключениям для дополнительной отладки
blame_mfa(module, function, args): Присваивает вину вызову указанного модуля, функции и аргументов
exception?(term): Возвращает true если указанный term является исключением
format(kind, payload, stacktrace \\ nil): Нормализует и форматирует броски/ошибки/выходы и трассировки стека
format_banner(kind, exception, stacktrace \\ nil): Нормализует и форматирует любой бросок/ошибку/выход
format_exit(reason): Форматирует выход. Возвращает строку
format_fa(fun, arity): Принимает анонимную функцию и арность и форматирует её так, как отображается в трассировках стека. Арность также может быть списком аргументов
format_file_line(file, line, suffix \\ ""): Форматирует заданный file и line так, как отображается в трассировках стека. Если какое-либо из значений nil, они опускаются
format_mfa(module, fun, arity): Принимает модуль, функцию и арность и форматирует её так, как отображается в трассировках стека. Арность также может быть списком аргументов
format_stacktrace(trace \\ nil): Форматирует трассировку стека
format_stacktrace_entry(entry): Принимает элемент трассировки стека и форматирует его в строку
message(exception): Получает сообщение для exception
normalize(kind, payload, stacktrace \\ nil): Нормализует исключение, преобразуя Erlang исключения в Elixir исключения

Обработчики

blame(t, stacktrace): Вызывается из Exception.blame/3 для дополнения структуры исключения
exception(term)
message(t)

Типы

kind()

kind() :: :error | non_error_kind()

Тип, обрабатываемый функциями форматирования

stacktrace()

stacktrace() :: [stacktrace_entry()]

stacktrace_entry()

stacktrace_entry() ::
  {module(), atom(), arity_or_args(), location()}
  | {(... -> any()), arity_or_args(), location()}

t()

t() :: %module(){:__exception__ => true, optional(atom()) => any()}

Тип исключения

Функции

blame(kind, error, stacktrace)

blame(non_error_kind(), payload, stacktrace()) :: {payload, stacktrace()}
when payload: var

blame(:error, any(), stacktrace()) :: {t(), stacktrace()}

Добавляет информацию к исключениям для дополнительной отладки.

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

Если модуль исключения реализует необязательный blame/2 обработчик, он будет вызван для выполнения вычислений.

blame_mfa(module, function, args)

blame_mfa(module(), function(), args :: [term()]) ::
  {:ok, :def | :defp | :defmacro | :defmacrop,
   [{args :: [term()], guards :: [term()]}]}
  | :error

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

Эта функция получит доступные клаузы из байткода и проверит их против предоставленных аргументов. Клаузы возвращаются в виде списка пар {args, guards} , где каждый аргумент и каждая условие верхнего уровня в условии разделены and/or заключены в кортежи с метаданными вины.

Эта функция возвращает либо {:ok, definition, clauses} либо :error. Где definition это :def, :defp, :defmacro или :defmacrop. Обратите внимание, что эта функциональность требует Erlang/OTP 20, в противном случае :error всегда возвращается.

exception?(term)

Возвращает true если указанный term является исключением.

format(kind, payload, stacktrace \\ nil)

format(kind(), any(), stacktrace() | nil) :: String.t()

Нормализует и форматирует броски/ошибки/выходы и трассировки стека.

Она полагается на format_banner/3 и format_stacktrace/1 для генерации окончательного формата.

Обратите внимание, что {:EXIT, pid} не генерируют трассировку стека (поскольку они извлекаются как сообщения без трассировки стека).

format_banner(kind, exception, stacktrace \\ nil)

format_banner(kind(), any(), stacktrace() | nil) :: String.t()

Нормализует и форматирует любой бросок/ошибку/выход.

Сообщение форматируется и отображается в том же формате, что и в командной строке Elixir.

Третий аргумент, трассировка стека, необязателен. Если он не указан, System.stacktrace/0 иногда используется для получения дополнительной информации об kind :error. Если трассировка стека неизвестна и System.stacktrace/0 не вернёт трассировку стека, соответствующую исключению, используется пустая трассировка стека, [].

format_exit(reason)

format_exit(any()) :: String.t()

Форматирует выход. Возвращает строку.

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

format_fa(fun, arity)

Принимает анонимную функцию и арность и форматирует её так, как отображается в трассировках стека. Арность также может быть списком аргументов.

Примеры

Exception.format_fa(fn -> nil end, 1)
#=> "#Function<...>/1"

format_file_line(file, line, suffix \\ "")

Форматирует заданный file и line так, как отображается в трассировках стека. Если какое-либо из значений nil, они опускаются.

Примеры

iex> Exception.format_file_line("foo", 1)
"foo:1:"

iex> Exception.format_file_line("foo", nil)
"foo:"

iex> Exception.format_file_line(nil, nil)
""

format_mfa(module, fun, arity)

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

Примеры

iex> Exception.format_mfa Foo, :bar, 1
"Foo.bar/1"

iex> Exception.format_mfa Foo, :bar, []
"Foo.bar()"

iex> Exception.format_mfa nil, :bar, []
"nil.bar()"

Анонимные функции отображаются как -func/arity-anonfn-count-, где func - имя окружающей функции. Преобразуйте в «анонимная функция в func/arity»

format_stacktrace(trace \\ nil)

Форматирует трассировку стека.

Трассировка стека должна быть передана в качестве аргумента. Если нет, трассировка стека извлекается из Process.info/2.

format_stacktrace_entry(entry)

format_stacktrace_entry(stacktrace_entry()) :: String.t()

Принимает элемент трассировки стека и форматирует его в строку.

message(exception)

Получает сообщение для exception.

normalize(kind, payload, stacktrace \\ nil)

normalize(non_error_kind(), payload, stacktrace()) :: payload when payload: var

normalize(:error, any(), stacktrace()) :: t()

Нормализует исключение, преобразуя Erlang исключения в Elixir исключения.

Она принимает kind выброшенное catch в качестве аргумента и нормализует только :error, возвращая неизмененный payload для остальных.

Обработчики

blame(t, stacktrace) (необязательно)

blame(t(), stacktrace()) :: {t(), stacktrace()}

Вызывается из Exception.blame/3 для дополнения структуры исключения.

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

исключение(термин)

exception(term()) :: t()

сообщение(t)

message(t()) :: String.t()