The Inspect protocol converts an Elixir data structure into an algebra document.

This documentation refers to implementing the Inspect protocol for your own data structures. To learn more about using inspect, see Kernel.inspect/2 and IO.inspect/2.

The inspect/2 function receives the entity to be inspected followed by the inspecting options, represented by the struct Inspect.Opts. Building of the algebra document is done with Inspect.Algebra.

Examples

Many times, inspecting a structure can be implemented in function of existing entities. For example, here is MapSet's inspect/2 implementation:

defimpl Inspect, for: MapSet do
  import Inspect.Algebra

  def inspect(dict, opts) do
    concat(["#MapSet<", to_doc(MapSet.to_list(dict), opts), ">"])
  end
end

The concat/1 function comes from Inspect.Algebra and it concatenates algebra documents together. In the example above, it is concatenating the string "MapSet<" (all strings are valid algebra documents that keep their formatting when pretty printed), the document returned by Inspect.Algebra.to_doc/2 and the other string ">".

Since regular strings are valid entities in an algebra document, an implementation of the Inspect protocol may simply return a string, although that will devoid it of any pretty-printing.

Error handling

In case there is an error while your structure is being inspected, Elixir will raise an ArgumentError error and will automatically fall back to a raw representation for printing the structure.

You can however access the underlying error by invoking the Inspect implementation directly. For example, to test Inspect.MapSet above, you can invoke it as:

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

Deriving

The Inspect protocol can be derived to hide certain fields from structs, so they don't show up in logs, inspects and similar. This is especially useful for fields containing private information.

The options :only and :except can be used with @derive to specify which fields should and should not appear in the algebra document:

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

inspect(%User{id: 1, name: "Homer", address: "742 Evergreen Terrace"})
#=> #User<id: 1, name: "Homer", ...>