Протокол 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 — (с версии v1.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's 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 будьте внимательны, так как вызовы IO.inspect/2 или dbg/1 могут привести к бесконечной рекурсии (поскольку для инспектирования/отладки структуры необходимо вызывать inspect).

Вот несколько советов:

• Для отладки используйте IO.inspect/2 с опцией structs: false, которая отключает пользовательский вывод и предотвращает рекурсивный вызов реализации Inspect.

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

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