exhal v2.1.0 ExHal

Use HAL APIs with ease.

Example


iex> doc = ExHal.parse(~s|
...> { "name": "Hello!",
...>    "_links": {
...>      "self"   : { "href": "http://example.com" },
...>      "profile": [{ "href": "http://example.com/special" },
...>                  { "href": "http://example.com/normal" }]
...>   }
...> }
...> |)
%ExHal.Document{links: %{"profile" => [%ExHal.Link{name: nil, rel: "profile", target: nil,
              href: "http://example.com/normal", templated: false},
             %ExHal.Link{name: nil, rel: "profile", target: nil, href: "http://example.com/special",
              templated: false}],
            "self" => [%ExHal.Link{name: nil, rel: "self", target: nil, href: "http://example.com",
              templated: false}]}, properties: %{"name" => "Hello!"}}
iex> ExHal.url(doc)
{:ok, "http://example.com"}
iex> ExHal.fetch(doc, "name")
{:ok, "Hello!"}
iex> ExHal.fetch(doc, "non-existent")
:error
iex> ExHal.fetch(doc, "profile")
{:ok,
 [%ExHal.Link{name: nil, rel: "profile", target: nil,
              href: "http://example.com/normal",
              templated: false},
  %ExHal.Link{name: nil, rel: "profile", target: nil,
              href: "http://example.com/special",
              templated: false}]}
iex> ExHal.get_links_lazy(doc, "profile", fn -> [] end)
[%ExHal.Link{name: nil, rel: "profile", target: nil,
             href: "http://example.com/normal",
             templated: false},
 %ExHal.Link{name: nil, rel: "profile", target: nil,
             href: "http://example.com/special",
             templated: false}]
iex> ExHal.get_links_lazy(doc, "alternate", fn -> [] end)
[]

ExHal can also make requests. Continuing the example above:

ExHal.follow_link(doc, "profile")
{:error, %ExHal.Error{reason: "multiple choices"}}

ExHal.follow_link(doc, "nonexistent")
{:error, %ExHal.Error{reason: "no such link"}}

ExHal.follow_link("self")
{:ok, %ExHal.Document{...}}

ExHal.follow_link(doc, "profile", pick_volunteer: true)
{:ok, %ExHal.Document{...}}

ExHal.follow_links(doc, "profile")
[{:ok, %ExHal.Document{...}}, {:ok, %ExHal.Document{...}}]

Summary

Functions

Fetches value of specified property or links whose rel matches

Follows all links of a particular rel in a HAL document

Returns link or property of the specified name, or the result of default_fun if neither are found

Returns [%Link{}...] when link exists

    result of `default_fun` otherwise

Returns <property value> when property exists

    result of `default_fun` otherwise

Returns a new %ExHal.Document representing the HAL document provided

Returns {:ok, <url of specified document>}

    `:error`

Functions

fetch(a_document, name)

Fetches value of specified property or links whose rel matches

Returns {:ok, <property value>} if name identifies a property;

    `{:ok, [%Link{}, ...]}`   if `name` identifies a link;
    `:error`                  othewise
follow_link(a_doc, name, opts \\ %{pick_volunteer: false, tmpl_vars: %{}})

Follows a link in a HAL document.

Returns {:ok, %ExHal.Document{...}} if request is an error

    `{:error, %ExHal.Error{...}}` if not
follow_links(a_doc, name, opts \\ %{tmpl_vars: %{}})

Follows all links of a particular rel in a HAL document.

Returns [{:ok, %ExHal.Document{...}}, {:error, %ExHal.Error{...}, ...]

get_lazy(a_doc, name, default_fun)

Returns link or property of the specified name, or the result of default_fun if neither are found.

get_property_lazy(a_doc, prop_name, default_fun)

Returns <property value> when property exists

    result of `default_fun` otherwise
parse(hal_str)

Returns a new %ExHal.Document representing the HAL document provided.

url(a_doc, default_fn \\ fn _doc -> :error end)

Returns {:ok, <url of specified document>}

    `:error`