Transmog v0.1.0 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.
key_pair/0
is the type for a single key pair that is part of the list of
key pairs that this struct holds.
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.
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/0
is the type for the Transmog.KeyPair
struct.
Link to this section 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.
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]
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}
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)
parse(list)
View Sourceparse(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}
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)
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"]}]}