View Source Syrup.Encoder protocol (Syrup v0.3.0)

Protocol controlling how a value is encoded to Syrup.

Deriving

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

  • :only - encodes only values of specific keys.
  • :except - encodes all struct fields except specific keys.
  • :as - the type of the encoding to use. Can be :map or :record.
  • :label - record name to use instead of the struct name if serializing as a record.

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 Syrup.Encoder just before defstruct, an implementation similar to the following implementation would be generated:

defimpl Syrup.Encoder, for: Test do
  def encode(value, opts) do
    Syrup.Encode.record(Map.take(value, [:foo, :bar, :baz]), Keyword.put_new(opts, :as, "Test"))
  end
end

If we called @derive {Syrup.Encoder, only: [:foo]}, an implementation similar to the following implementation would be generated:

defimpl Syrup.Encoder, for: Test do
  def encode(value, opts) do
    Syrup.Encode.record(Map.take(value, [:foo]), Keyword.put_new(opts, :as, "Test"))
  end
end

If we called @derive {Syrup.Encoder, except: [:foo]}, an implementation similar to the following implementation would be generated:

defimpl Syrup.Encoder, for: Test do
  def encode(value, opts) do
    Syrup.Encode.record(Map.take(value, [:bar, :baz]), Keyword.put_new(opts, :as, "Test"))
  end
end

If we called @derive {Syrup.Encoder, as: "test"}, an implementation similar to the following implementation would be generated:

defimpl Syrup.Encoder, for: Test do
  def encode(value, opts) do
    Syrup.Encode.record(Map.take(value, [:foo, :bar, :baz]), Keyword.put_new(opts, :as, "test"))
  end
end

The actually generated implementations are more efficient computing some data during compilation similar to the macros from the Syrup.Helpers module.

Explicit implementation

If you wish to implement the protocol fully yourself, it is advised to use functions from the Syrup.Encode module to do the actual encoding. They are highly optimized and verified to always produce valid Syrup.

Summary

Functions

Encodes value to Syrup.

Types

opts()

@type opts() :: Syrup.Encode.opts()

t()

@type t() :: term()

Functions

encode!(value, opts)

@spec encode!(t(), opts()) :: iodata() | no_return()

Encodes value to Syrup.

The argument opts is opaque - it can be passed to various functions in Syrup.Encode (or to the protocol function itself) for encoding values to Syrup.