Протокол 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 функции 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{})