Transmog v0.1.1 Transmog.KeyPairs View Source

Transmog.KeyPairs is a struct which holds the information about a list of key_pair/0 and ensures that they are valid. A key pair is a list of mappings from one path to another. For example, {[:a], [:b]} indicates that we are transforming a map with keys :a and :b to now have the keys swapped with the same values.

You can create a new Transmog.KeyPairs struct manually by calling the new/1 and new!/1 functions directly. This struct can be used in most of the core functionality in this library.

This library uses parse/1 and parse!/1 under the hood to coerce your key paths into a format that can be understood by this struct. These functions use the Transmog.Parser protocol for the type that is provided for the key path.

Examples

iex> key_pairs = [{[:identity, :first_name], [:user_details, :first_name]}]
iex> {:ok, %Transmog.KeyPairs{} = key_pairs} = Transmog.KeyPairs.new(key_pairs)
iex> key_pairs
%Transmog.KeyPairs{list: [{[:identity, :first_name], [:user_details, :first_name]}]}

iex> key_pairs = [{[:identity, :first_name], [:user_details, :first_name]}]
iex> Transmog.KeyPairs.new!(key_pairs)
%Transmog.KeyPairs{list: [{[:identity, :first_name], [:user_details, :first_name]}]}

If you do not provide correct key pairs when this struct is created then you will receive an invalid/0 error as a response instead.

Examples

iex> key_pairs = [{nil, [:identity, :last_name]}]
iex> Transmog.KeyPairs.new(key_pairs)
{:error, :invalid_key_pairs}

iex> key_paths = [{nil, ":identity.:last_name"}]
iex> Transmog.KeyPairs.parse(key_paths)
{:error, :invalid_key_path} #=> Also possible to receive these errors

iex> key_pairs = [{nil, [:identity, :last_name]}]
iex> Transmog.KeyPairs.new!(key_pairs)
** (Transmog.InvalidKeyPairsError) key pairs are not valid ({nil, [:identity, :last_name]}, index 0)

iex> key_paths = [{nil, ":identity.:last_name"}]
iex> Transmog.KeyPairs.parse!(key_paths)
** (Transmog.InvalidKeyPathError) key path is not valid (nil)

If you know the shape of your data structures in advance then you should pre-compile your Transmog.KeyPairs structs by calling parse!/1 or new!/1 and saving the results somewhere where they can be reused.

Transmog.format/2 and Transmog.format!/2 optimize for the case where you provide this struct directly.

Link to this section Summary

Types

error/0 is the type for when creating a new Transmog.Keypair struct fails due to either an invalid path or pair.

invalid/0 is the type for when a key pair list is determined to not be valid the struct is created using new/1.

key_pair/0 is the type for a single key pair that is part of the list of key pairs that this struct holds.

t()

t/0 is the type for the Transmog.KeyPair struct.

Functions

find_match/2 takes a list of key pairs and a key and finds the pair in the list which matches. If a match is found then the opposite key in the key pair will be returned as the key that the value should map to.

new/1 creates a new Transmog.KeyPairs struct. It enforces that the key pairs are valid and have been previously parsed. If the key pairs are not valid then an error will be returned.

new!/1 creates a new Transmog.KeyPairs struct. It delegates execution to new/1. If the key pairs are not valid then an error is raised otherwise the result is unwrapped and returned.

parse/1 takes a list of key paths and attempts to coerce them into valid key pairs. If successful then a Transmog.KeyPair struct will be returned with the key paths converted into the list format.

parse!/1 takes a list of key paths are coerces them into valid key pairs. If the key pairs or any path are not valid then an error will be raised. Otherwise the result is unwrapped and returned.

reverse/1 takes a Transmog.KeyPairs and reverses each individual key pair in the list of key pairs. This could be useful if you wanted to reverse a format without having to define two separate key pairs manually.

Link to this section Types

error/0 is the type for when creating a new Transmog.Keypair struct fails due to either an invalid path or pair.

Link to this type

invalid()

View Source
invalid() :: {:error, :invalid_key_pairs}

invalid/0 is the type for when a key pair list is determined to not be valid the struct is created using new/1.

Link to this type

key_pair()

View Source
key_pair() :: {[term()], [term()]}

key_pair/0 is the type for a single key pair that is part of the list of key pairs that this struct holds.

Link to this type

t()

View Source
t() :: %Transmog.KeyPairs{list: [key_pair()]}

t/0 is the type for the Transmog.KeyPair struct.

Link to this section Functions

Link to this function

find_match(key_pairs, key)

View Source
find_match(key_pairs :: t(), key :: [term()]) :: [term()]

find_match/2 takes a list of key pairs and a key and finds the pair in the list which matches. If a match is found then the opposite key in the key pair will be returned as the key that the value should map to.

Examples

iex> key_pairs = %Transmog.KeyPairs{list: [{[:a], ["a"]}]}
iex> Transmog.KeyPairs.find_match(key_pairs, [:a])
["a"]

iex> key_pairs = %Transmog.KeyPairs{list: [{[:a], ["a"]}]}
iex> Transmog.KeyPairs.find_match(key_pairs, [:b])
[:b]
Link to this function

new(list)

View Source
new(list :: [key_pair()]) :: {:ok, t()} | invalid()

new/1 creates a new Transmog.KeyPairs struct. It enforces that the key pairs are valid and have been previously parsed. If the key pairs are not valid then an error will be returned.

Examples

iex> key_pairs = [{[:a, :b], [:b, :a]}]
iex> {:ok, key_pairs} = Transmog.KeyPairs.new(key_pairs)
iex> key_pairs
%Transmog.KeyPairs{list: [{[:a, :b], [:b, :a]}]}

iex> key_pairs = [{nil, [:a, :b]}]
iex> Transmog.KeyPairs.new(key_pairs)
{:error, :invalid_key_pairs}
Link to this function

new!(list)

View Source
new!(list :: [key_pair()]) :: t()

new!/1 creates a new Transmog.KeyPairs struct. It delegates execution to new/1. If the key pairs are not valid then an error is raised otherwise the result is unwrapped and returned.

Examples

iex> key_pairs = [{[:a, :b], [:b, :a]}]
iex> Transmog.KeyPairs.new!(key_pairs)
%Transmog.KeyPairs{list: [{[:a, :b], [:b, :a]}]}

iex> key_pairs = [{nil, [:a, :b]}]
iex> Transmog.KeyPairs.new!(key_pairs)
** (Transmog.InvalidKeyPairsError) key pairs are not valid ({nil, [:a, :b]}, index 0)
Link to this function

parse(list)

View Source
parse(list :: [Transmog.key_paths()]) :: {:ok, t()} | error()

parse/1 takes a list of key paths and attempts to coerce them into valid key pairs. If successful then a Transmog.KeyPair struct will be returned with the key paths converted into the list format.

Examples

iex> key_paths = [{"a.b", ":a.:b"}]
iex> {:ok, key_pairs} = Transmog.KeyPairs.parse(key_paths)
iex> key_pairs
%Transmog.KeyPairs{list: [{["a", "b"], [:a, :b]}]}

iex> key_paths = [{"", ":a"}, {"a.b", ":a.:b"}]
iex> Transmog.KeyPairs.parse(key_paths)
{:error, :invalid_key_path}

iex> key_paths = [{"a", ":a.:b"}]
iex> Transmog.KeyPairs.parse(key_paths)
{:error, :invalid_key_pairs}
Link to this function

parse!(list)

View Source
parse!(list :: [Transmog.key_paths()]) :: t()

parse!/1 takes a list of key paths are coerces them into valid key pairs. If the key pairs or any path are not valid then an error will be raised. Otherwise the result is unwrapped and returned.

Examples

iex> key_paths = [{"a.b", ":a.:b"}]
iex> Transmog.KeyPairs.parse!(key_paths)
%Transmog.KeyPairs{list: [{["a", "b"], [:a, :b]}]}

iex> key_paths = [{"", ":a"}, {"a.b", ":a.:b"}]
iex> Transmog.KeyPairs.parse!(key_paths)
** (Transmog.InvalidKeyPathError) key path is not valid ("")

iex> key_paths = [{"a", ":a.:b"}]
iex> Transmog.KeyPairs.parse!(key_paths)
** (Transmog.InvalidKeyPairsError) key pairs are not valid ({["a"], [:a, :b]}, index 0)
Link to this function

reverse(key_pairs)

View Source
reverse(key_pairs :: t()) :: t()

reverse/1 takes a Transmog.KeyPairs and reverses each individual key pair in the list of key pairs. This could be useful if you wanted to reverse a format without having to define two separate key pairs manually.

Examples

iex> key_paths = [{"a", "b"}]
iex> %Transmog.KeyPairs{} = key_pairs = Transmog.KeyPairs.parse!(key_paths)
iex> Transmog.KeyPairs.reverse(key_pairs)
%Transmog.KeyPairs{list: [{["b"], ["a"]}]}