Helps to build transcoders for HAL documents.

Given a document like

{
  "name": "Jane Doe",
  "mailingAddress": "123 Main St",
  "_links": {
    "app:department": { "href": "http://example.com/dept/42" },
    "app:manager":    { "href": "http://example.com/people/84" }
  }
}

We can define an transcoder for it.

defmodule PersonTranscoder do
  use ExHal.Transcoder

  defproperty "name"
  defproperty "mailingAddress", param: :address
  deflink     "app:department", param: :department_url
  deflink     "app:manager",    param: :manager_id, value_converter: PersonUrlConverter
end

PersonUrlConverter is a module that has adopted the ExHal.ValueConverter behavior.

defmodule PersonUrlConverter do
  @behaviour ExHal.ValueConveter

  def from_hal(person_url) do
    to_string(person_url)
    |> String.split("/")
    |> List.last
  end

  def to_hal(person_id) do
    "http://example.com/people/#{person_id}"
  end
end

We can use this transcoder to to extract the pertinent parts of the document into a map.

iex> PersonTranscoder.decode!(doc)
%{name: "Jane Doe",
  address: "123 Main St",
  department_url: "http://example.com/dept/42",
  manager_id: 84}

iex> PersonTranscoder.encode!(%{name: "Jane Doe", address: "123 Main St", department_url: "http://example.com/dept/42", manager_id: 84}) ~s( { "name": "Jane Doe", "mailingAddress": "123 Main St", "_links": {

"app:department": { "href": "http://example.com/dept/42" },
"app:manager":    { "href": "http://example.com/people/84" }

} } )