This module can be used from two different ways:

• As a macro
• Manually

As a macro

To be defining decoders as macro, you need to use the Starchoice.Decoder module in your struct. It's declaration is highly (like totally) inspired by Ecto's schemas.

To see available options, take a look at put_field/3's documentation

Examples

defmodule User do
  use Starchoice.Decoder
  defstruct first_name: nil, age: nil

  defdecoder do
    field(:first_name)
    field(:age)
  end
end

User.__decoder__() # %Decoder{}
User.__decoder__(:default) # %Decoder{}

When you don't pass a name to the defdecoder/2 function, it defaults to default. So calling defdecoder do and defdecoder :default do is identical. This is because you might be interested in creating multiple decoders for the same struct like below:

defmodule User do
  use Starchoice.Decoder
  defstruct first_name: nil, last_name: nil, email: nil, age: nil

  defdecoder do
    field(:first_name)
    field(:age)
  end

  defdecoder :full do
    field(:first_name)
    field(:last_name)
    field(:email)
    field(:age)
  end
end

User.__decoder__() # %Decoder{fields: [{:first_name, _}, {:age, _}]}
User.__decoder__(:default) # %Decoder{fields: [{:first_name, _}, {:age, _}]}
User.__decoder__(:full) # %Decoder{fields: [{:first_name, _}, {:last_name, _}, {:email, _}, {:age, _}]}

And you can now use the module directly when calling Starchoice.decode/3 like:

iex> Starchoice.decode(input, User)
iex> Starchoice.decode(input, {User, :full})

Source mapper

While each field supports a :source option to specify what key to use in the parsed map, you can provide a module to perform the casting. If, as an example, the map is using camelCaseKeys, you can provide a source mapper that perform the appropriate conversion.

defmodule CamelCase do
  def map_source(field) do
    splitted =
      field
      |> to_string()
      |> String.split("_", parts: 2)

    case splitted do
      [key] -> key
      [head, rest] -> head <> Macro.camelize(rest)
    end
  end
end

defmodule User do
  defstruct [:first_name, :last_name]

  use Starchoice.Decoder, source_mapper: CamelCase

  defdecoder do
    field(:first_name)
    field(:last_name)
  end
end

iex> map = %{"firstName" => "Bobby", "lastName" => "Hill"}
iex> Starchoice.decode(map, User)
%User{first_name: "Bobby", last_name: "Hill"}

iex> map = %{"first_name" => "Bobby", "last_name" => "Hill"}
iex> Starchoice.decode(map, User)
%User{first_name: nil, last_name: nil}

Doing so is the same as adding individual :source option to each field.

Manually

You could also build decoder manually like the following:

defmodule User do
  defstruct email: nil, password: nil

  def mask_password(_), do: "MASKED"
end

User
|> Decoder.new()
|> Decoder.put_field(:email)
|> Decoder.put_field(:password, with: &User.mask_password/1)

# or

Decoder.new(User, [
  {:email, []},
  {:password, with: &User.mask_password/1}
])

To see available options, take a look at put_field/3's documentation