Protocol controlling how a value is encoded to YAML.

Deriving

The protocol allows leveraging the Elixir's @derive feature to simplify protocol implementation in trivial cases. Accepted options are:

• :only - encodes only values of specified keys.
• :except - If set to a list of fields, all struct fields except specified keys are encoded. If set to :defaults, all fields are encoded, except the ones equaling their default value as defined in the struct.

By default all keys except the :__struct__ key are encoded.

Example

Let's assume a presence of the following struct:

defmodule Test do
  defstruct [:foo, :bar, :baz]
end

If we were to call @derive Ymlr.Encoder just before defstruct, an implementation similar to the following implementation would be generated:

defimpl Ymlr.Encoder, for: Test do
  def encode(data, indent_level) do
    data
    |> Map.take(unquote([:foo, :bar, :baz]))
    |> Ymlr.Encode.map(indent_level)
  end
end

Limit fields using the only Option

We can limit the fields being encoded using the :only option:

defmodule Test do
  @derive {Ymlr.Encoder, only: [:foo]}
  defstruct [:foo, :bar, :baz]
end

This would generate an implementation similar to the following:

defimpl Ymlr.Encoder, for: Test do
  def encode(data, indent_level) do
    data
    |> Map.take(unquote([:foo]))
    |> Ymlr.Encode.map(indent_level)
  end
end

Exclude fields using the except Option

We can exclude the fields being encoded using the :except option:

defmodule Test do
  @derive {Ymlr.Encoder, except: [:foo]}
  defstruct [:foo, :bar, :baz]
end

This would generate an implementation similar to the following:

defimpl Ymlr.Encoder, for: Test do
  def encode(data, indent_level) do
    data
    |> Map.take(unquote([:bar, :baz]))
    |> Ymlr.Encode.map(indent_level)
  end
end

We can exclude the fields being left at their defaults by passing except: :defaults:

defmodule TestExceptDefaults do
  @derive {Ymlr.Encoder, except: :defaults}
  defstruct [:foo, bar: 1, baz: :ok]
end

This would generate an implementation similar to the following:

iex> Ymlr.document!(%TestExceptDefaults{foo: 1, bar: 1, baz: :error})
"baz: error\nfoo: 1"