exhal v7.0.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" }

} } )

Link to this section Summary

Link to this section Types

Link to this type t()
t() :: module

Link to this section Functions

Link to this function decode_value(atom, opts)
Link to this function decode_value(raw_value, converter, opts)
Link to this macro deflink(rel, options \\ []) (macro)

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.
    • :templated - a boolean that adds a templated: true parameter if true
    • :value_converter - a ExHal.Transcoder.ValueConverter with which to convert the link target when en/decoding HAL
Link to this macro deflinks(rel, options \\ []) (macro)

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
Link to this macro defproperty(name, options \\ []) (macro)

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
Link to this function encode_value(raw_value, converter, opts)
Link to this function put_link(atom, doc, )
Link to this function put_link(target, doc, rel, templated \\ false)
Link to this function put_param(value, params, param_names)
Link to this function put_property(value, doc, prop_name)

Link to this section Callbacks

Link to this callback decode!(arg0)
decode!(ExHal.Document.t) :: %{}
Link to this callback decode!(arg0, keyword)
decode!(ExHal.Document.t, keyword) :: %{}
decode!(%{}, ExHal.Document.t) :: %{}
Link to this callback decode!(%{}, arg1, keyword)
decode!(%{}, ExHal.Document.t, keyword) :: %{}
Link to this callback encode!(%{})
encode!(%{}) :: ExHal.Document.t
Link to this callback encode!(%{}, keyword)
encode!(%{}, keyword) :: ExHal.Document.t
encode!(Exhal.Document.t, %{}) :: ExHal.Document.t
Link to this callback encode!(arg0, %{}, keyword)
encode!(Exhal.Document.t, %{}, keyword) :: ExHal.Document.t
Link to this callback patch!(%{}, list)
patch!(%{}, [%{}]) :: %{}
Link to this callback patch!(%{}, list, keyword)
patch!(%{}, [%{}], keyword) :: %{}