Inspect протокол

Протокол Inspect преобразует структуру данных Elixir в документ алгебры.

Это обычно делается, когда вы хотите настроить, как ваши собственные структуры отображаются в логах и терминале.

В этом документе описывается реализация протокола Inspect для ваших собственных структур данных. Чтобы узнать больше об использовании inspect, см. Kernel.inspect/2 и IO.inspect/2.

Представление inspect

Обычно существует три варианта представления inspect. Чтобы понять их, давайте представим, что у нас есть следующая User структура:

defmodule User do
  defstruct [:id, :name, :address]
end

Наши варианты:

1. Вывести структуру, используя синтаксис Elixir для структур, например: %User{address: "Earth", id: 13, name: "Jane"}. Это стандартное представление и лучший вариант, если все поля структуры являются общедоступными.

2. Вывести, используя обозначение #User<...>, например: #User<id: 13, name: "Jane", ...>. Это обозначение не генерирует допустимый код Elixir и обычно используется, когда структура имеет закрытые поля (например, вы можете скрыть поле :address для сокрытия персональной информации).

3. Вывести структуру, используя синтаксис выражения, например: User.new(13, "Jane", "Earth"). Предполагается, что существует функция User.new/3. Этот вариант в основном используется как альтернатива варианту 2 для представления пользовательских структур данных, таких как MapSet, Date.Range и другие.

Вы можете реализовать протокол Inspect для своих структур, следуя приведенным выше соглашениям. Вариант 1 является стандартным представлением, и вы можете быстро получить вариант 2, выведя протокол Inspect. Для варианта 3 вам нужна ваша собственная реализация.

Наследование

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

Поддерживаемые варианты:

• :only — включать только указанные поля при инспектировании.

• :except — исключать указанные поля при инспектировании.

• :optional — (с версии 1.14.0) не включать поле, если его значение совпадает с значением по умолчанию. Это может быть использовано для упрощения представления структуры за счет скрытия информации.

В случае использования :only или :except для ограничения полей, структура будет выводиться с использованием обозначения #User<...>, так как структура больше не может быть скопирована и вставлена ​​в качестве допустимого кода Elixir. Давайте посмотрим пример:

defmodule User do
  @derive {Inspect, only: [:id, :name]}
  defstruct [:id, :name, :address]
end

inspect(%User{id: 1, name: "Jane", address: "Earth"})
#=> #User<id: 1, name: "Jane", ...>

Если вы используете только вариант :optional, структура по-прежнему будет выводиться как %User{...}.

Пользовательская реализация

Вы также можете определить свою пользовательскую реализацию протокола, определив функцию inspect/2. Функция получает сущность, подлежащую инспектированию, за которой следуют параметры инспектирования, представленные структурой Inspect.Opts. Создание документа алгебры выполняется с помощью Inspect.Algebra.

Многие разы инспектирование структуры может быть реализовано на основе существующих сущностей. Например, вот реализация MapSet для inspect/2:

defimpl Inspect, for: MapSet do
  import Inspect.Algebra

  def inspect(map_set, opts) do
    concat(["MapSet.new(", Inspect.List.inspect(MapSet.to_list(map_set), opts), ")"])
  end
end

Функция concat/1 взята из Inspect.Algebra и объединяет документы алгебры вместе. В примере выше она объединяет строку "MapSet.new(", документ, возвращаемый функцией Inspect.Algebra.to_doc/2, и конечную строку ")". Таким образом, MapSet с числами 1, 2 и 3 будет выводиться следующим образом:

iex> MapSet.new([1, 2, 3], fn x -> x * 2 end)
MapSet.new([2, 4, 6])

Другими словами, представление inspect MapSet возвращает выражение, которое при вычислении создает сам MapSet.

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

В случае возникновения ошибки при инспектировании вашей структуры Elixir генерирует ошибку ArgumentError и автоматически переходит к исходному представлению для вывода структуры.

Однако вы можете получить доступ к основной ошибке, вызвав реализацию Inspect непосредственно. Например, чтобы проверить Inspect.MapSet выше, вы можете вызвать его так:

Inspect.MapSet.inspect(MapSet.new(), %Inspect.Opts{})