MapRewire makes it easier to rewire maps, such as might be done when translating from an external API result to an internal value or taking the output of one external API and transforming it the input shape of an entirely different external API.

To rewire a map, build transformation rules and call rewire/3, or if MapRewire has been imported, use the operator, <~>.

iex> map   = %{"id" => "234923409", "title" => "asdf"}
iex> rules = "title=>name id=>shopify_id"
iex> map <~> rules
{%{"id" => "234923409", "title" => "asdf"}, %{"shopify_id" => "234923409", "name" => "asdf"}}
iex> MapRewire.rewire(map, rules) == (map <~> rules)
true

Rewire Rules

The rewire rules have three basic forms.

1. A string containing string rename rules separated by whitespace.

   iex> map   = %{"id" => "234923409", "title" => "asdf"}
   iex> rules = "title=>name id=>shopify_id"
   iex> map <~> rules
   {%{"id" => "234923409", "title" => "asdf"}, %{"shopify_id" => "234923409", "name" => "asdf"}}

   Here, rules normalizes to: [{"title", "name"}, {"id", "shopify_id"}].

2. A list of strings with one string rename rule in each string.

   iex> map   = %{"id" => "234923409", "title" => "asdf"}
   iex> rules = ["title=>name", "id=>shopify_id"]
   iex> map <~> rules
   {%{"id" => "234923409", "title" => "asdf"}, %{"shopify_id" => "234923409", "name" => "asdf"}}

   Here, rules normalizes to: [{"title", "name"}, {"id", "shopify_id"}].

3. Any enumerable value that iterates as key/value tuples (map, keyword list, or a list of 2-tuples). These may be either rename rules, or may be more complex key transform rules.

   iex> map   = %{id: "234923409", title: "asdf"}
   iex> rules = [title: :name, id: :shopify_id]
   iex> map <~> rules
   {%{id: "234923409", title: "asdf"}, %{shopify_id: "234923409", name: "asdf"}}
   iex> map   = %{"id" => "234923409", "title" => "asdf"}
   iex> rules = [{"title", "name"}, {"id", "shopify_id"}]
   iex> map <~> rules
   {%{"id" => "234923409", "title" => "asdf"}, %{"shopify_id" => "234923409", "name" => "asdf"}}
   iex> map   = %{"id" => "234923409", "title" => "asdf"}
   iex> rules = %{"title" => :name, "id" => :shopify_id}
   iex> map <~> rules
   {%{"id" => "234923409", "title" => "asdf"}, %{shopify_id: "234923409", name: "asdf"}}
   # This is legal, but really ugly. Don't do it.
   iex> map   = %{"id" => "234923409", "title" => "asdf"}
   iex> rules = ["title=>name", {"id", "shopify_id"}]
   iex> map <~> rules
   {%{"id" => "234923409", "title" => "asdf"}, %{"shopify_id" => "234923409", "name" => "asdf"}}

Rename Rules

Rename rules take the value of the old key from the source map and write it to the target map as the new key, like "title=>name", %{"title" => "name"}, and [title: :name] that normalize to {old_key, new_key}. Both old_key and new_key are typically atoms or strings, but may be any valid Map key value, except for the forms noted below.

Advanced Rules

There are two types of advanced rules (keys with options and producer functions), which can only be provided when the rules are in an enumerable format such as a keyword list, map, or list of tuples.

Keys with Options

The new key is provided as a tuple {new_key, options}. Supported options are :transform (expecting a transformer/0 function) and :default, expecting any normal map value. The :default will work as the third parameter of Map.get/3 and be used instead of key_missing/0.

iex> map   = %{"title" => "asdf"}
iex> rules = %{"title" => {:name, transform: &String.reverse/1}}
iex> map <~> rules
{%{"title" => "asdf"}, %{name: "fdsa"}}

# If "title" could be missing from the source map, the `transform` function
# should be written to handle `key_missing/0` values or have its own safe
# `default` value.
iex> map   = %{}
iex> rules = %{"title" => {:name, default: "unknown", transform: &String.reverse/1}}
iex> map <~> rules
{%{}, %{name: "nwonknu"}}

Producer Functions

Producer functions (producer/0) take in the value and return zero or more key/value tuples. It may be provided either as producer or {producer, options} as shown below.

iex> dcs = fn value -> ...> unless MapRewire.key_missing?(value) do ...> [dept, class, subclass] = ...> value ...> |> String.split("-", parts: 3) ...> |> Enum.map(&String.to_integer/1) ...> ...> Enum.to_list(%{"department" => dept, "class" => class, "subclass" => subclass}) ...> end ...> end iex> map = %{"title" => "asdf", "dcs" => "1-3-5"} iex> rules = %{"title" => "name", "dcs" => dcs} iex> map <~> rules {%{"title" => "asdf", "dcs" => "1-3-5"}, %{"name" => "asdf", "department" => 1, "class" => 3, "subclass" => 5}}

If "title" could be missing from the source map, the transform function

should be written to handle key_missing/0 values or have its own safe

default value.

iex> dcs = fn value -> ...> [dept, class, subclass] = ...> value ...> |> String.split("-", parts: 3) ...> |> Enum.map(&String.to_integer/1) ...> ...> Enum.to_list(%{"department" => dept, "class" => class, "subclass" => subclass}) ...> end iex> map = %{"title" => "asdf"} iex> rules = %{"title" => "name", "dcs" => {dcs, default: "0-0-0"}} iex> map <~> rules {%{"title" => "asdf"}, %{"name" => "asdf", "department" => 0, "class" => 0, "subclass" => 0}}