new/1 takes an optional opts and creates a new forom returning {:ok, forom}.

Examples

iex> {:ok, forom} = new()
...> match?(%FOROMTERM{}, forom)
true

Plymio.Vekil.Utility.forom?/1 returns true if the value implements Plymio.Vekil.Forom

iex> {:ok, forom} = new()
...> forom |> Plymio.Vekil.Utility.forom?
true

The value is passed using the :forom key:

iex> {:ok, forom} = new(forom: [a: 1, b: 2, c: 3])
...> forom |> Plymio.Vekil.Utility.forom?
true

iex> {:ok, forom} = new(
...>    forom: [a: 1, b: 2, c: 3], proxy: :abc)
...> forom |> Plymio.Vekil.Utility.forom?
true

Same example but here the realise function is used to access the value in the :forom field:

iex> {:ok, forom} = new(
...>    forom: [a: 1, b: 2, c: 3], proxy: :abc)
...> {:ok, {answer, _}} = forom |> FOROMPROT.realise
...> answer
[a: 1, b: 2, c: 3]

new!/1 calls new/1 and, if the result is {:ok, instance} returns the instance.

normalise/1 creates a new forom from its argument unless the argument is already one.

Examples

iex> {:ok, forom} = 42 |> normalise
...> {:ok, {answer, _}} = forom |> FOROMPROT.realise
...> answer
42

iex> {:ok, forom} = normalise(
...>   forom: 42, proxy: :just_42)
...> {:ok, {answer, _}} = forom |> FOROMPROT.realise
...> answer
42

An existing forom (of any implementation) is returned unchanged:

iex> {:ok, forom} = %{a: 1, b: 2, c: 3} |> normalise
...> {:ok, forom} = forom |> normalise
...> {:ok, {answer, _}} = forom |> FOROMPROT.realise
...> answer
%{a: 1, b: 2, c: 3}

produce/2 takes a forom and an optional opts, calls update/2 with the vekil and the opts if any, and returns {:ok, {product, forom}}.

The product will be a Keyword with one :forom key with its value set to the original term..

Examples

iex> {:ok, forom} = quote(do: x = x + 1) |> normalise
...> {:ok, {product, %FOROMTERM{}}} = forom |> FOROMPROT.produce
...> [:forom] = product |> Keyword.keys |> Enum.uniq
...> product |> Keyword.get(:forom)
quote(do: x = x + 1)

If opts are given, update/2 is called before producing the forom:

iex> {:ok, forom} = 42 |> normalise()
...> {:ok, forom} = forom |> update(forom: quote(do: x = x + 1))
...> {:ok, {product, %FOROMTERM{}}} = forom |> FOROMPROT.produce
...> [:forom] = product |> Keyword.keys |> Enum.uniq
...> product |> Keyword.get(:forom)
quote(do: x = x + 1)

An empty forom does not produce any :forom keys:

iex> {:ok, forom} = new()
...> {:ok, {product, _}} = forom |> FOROMPROT.produce
...> product |> Keyword.get(:forom)
nil

realise/2 takes a forom and an optional opts, calls produce/2, gets (Keyword.get_values/2) the :forom key values, normalises (Plymio.Fontais.Form.forms_normalise) the :forom values and returns {:ok, {forms, forom}}

Examples

iex> {:ok, forom} = 42 |> normalise
...> {:ok, {answer, _}} = forom |> FOROMPROT.realise
...> answer
42

If opts are given, update/2 is called before realising the forom:

iex> {:ok, forom} = new()
...> {:ok, {answer, %FOROMTERM{}}} = forom
...>    |> FOROMPROT.realise(forom: "The Updated Term Value")
...> answer
"The Updated Term Value"

An empty forom’s answer is the value of the :realise_default (the unset value).

iex> {:ok, forom} = new()
...> {:ok, {answer, %FOROMTERM{}}} = forom |> FOROMPROT.realise
...> answer |> Plymio.Fontais.Guard.is_value_unset
true

The :realise_default value can be set in the optional opts to realise/2:

iex> {:ok, forom} = new(realise_default: 42)
...> {:ok, {answer, %FOROMTERM{}}} = forom |> FOROMPROT.realise
...> answer
42

update/2 implements Plymio.Vekil.Forom.update/2.

Examples

iex> {:ok, forom} = new(
...>    forom: %{a: 1}, proxy: :map_a_1)
...> {:ok, forom} = forom |> update(forom: "Hello World!")
...> {:ok, {answer, _}} = forom |> FOROMPROT.realise
...> answer
"Hello World!"

update!/2 calls update/2 and, if the result is {:ok, instance} returns the instance.