exhal v4.10.0 ExHal.Transcoder behaviour

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" }

} } )


Summary

Macros

Define a link extractor & injector

Define a link extractor & injector for links that may have more than one item

Define a property extractor and injector

Types

t :: module

Functions

decode_value(atom)
decode_value(raw_value, converter)
encode_value(raw_value, converter)
put_link(target, doc, rel)
put_param(value, params, param_names)
put_property(value, doc, prop_name)

Macros

deflink(rel, options \\ [])

Define a link extractor & injector.

  • rel - the rel of the link in HAL
  • options - Keywords arguments
  • :param - the key(s) in the param structure that maps to this link. Required.
  • :value_converter - a ExHal.Transcoder.ValueConverter with which to convert the link target when en/decoding HAL
deflinks(rel, options \\ [])

Define a link extractor & injector for links that may have more than one item.

  • rel - the rel of the link in HAL
  • options - Keywords arguments
  • :param - the key(s) in the param structure that maps to this link. Required.
  • :value_converter - a ExHal.Transcoder.ValueConverter with which to convert the link target when en/decoding HAL
defproperty(name, options \\ [])

Define a property extractor and injector.

  • name - the name of the property in HAL
  • options - Keywords arguments
  • :param - the key(s) in the param structure that map to this property. Default is String.to_atom(name).
  • :value_converter - a ExHal.Transcoder.ValueConverter with which to convert the value to and from HAL

Callbacks

decode!(arg0)

Specs

decode!(ExHal.Document.t) :: %{}
decode!(%{}, arg1)

Specs

decode!(%{}, ExHal.Document.t) :: %{}
encode!(%{})

Specs

encode!(%{}) :: ExHal.Document.t
encode!(arg0, %{})

Specs

encode!(Exhal.Document.t, %{}) :: ExHal.Document.t