Managing a Dictionary of Transform Functions for Enumerables.

This module support the creation and use of a dictionary of named transform functions.

It also supports the composition of higher level transforms from transforms in the dictionary tother and/or new pipelines. Composed transforms can themselves be saved in the dictionary.

It uses Plymio.Enum.Transform for support having peer functions build/2, transform/3 and realise/3 that layer dictionary management.

Building a Transform Dictionary

A transform dictionary can be built using build/1, and updated using build/2, from either a Map or Keyword where the keys are the transform function name.

Each value must be one or more elements that are either supported by Plymio.Enum.Transform.build/1 or an existing dictionary key. See the examplea for the range of options.

The returned transform dictionary is a struct i.e. %Plymio.Enum.Transform.Dictionary{}

iex> td_test1 = [
...>
...>   # v transforms
...>   v_f_number:  [filter: fn v -> is_number(v) end],
...>   v_f_gt_0:    [filter: fn v -> v > 0 end],
...>   v_m_squared: [map: fn v -> v * v end],
...>   v_m_plus_42: [map: fn v -> v + 42 end],
...>   v_r_lt_45:   [reject: fn v -> v < 45 end],
...>   v_r_gt_50:   [reject: fn v -> v > 50 end],
...>
...>   # {k,v} 2tuple transforms
...>   kv_f_v_number:   [filter: fn {_k,v} -> is_number(v) end],
...>   kv_f_v_gt_0:     [filter: fn {_k,v} -> v > 0 end],
...>   kv_m_v_squared:  &(Stream.map(&1, fn {k,v} -> {k, v * v} end)),
...>   kv_m_v_plus_42:  [map: fn {k,v} -> {k, v + 42} end],
...>   kv_r_v_lt_45:    &(Stream.reject(&1, fn {_k,v} -> v < 45 end)),
...>   kv_r_v_gt_50:    [reject: fn {_k,v} -> v > 50 end],
...>
...>   v_f_gt_0_m_cubed: [&(Stream.reject(&1, fn v -> v > 0 end)),
...>                      &(Stream.map(&1, fn v -> v * v * v end))],
...>
...>   v_f_lt_42_m_squared_and_sum: [
...>     [filter: fn v -> v < 42 end],
...>     &(Stream.map(&1, fn v -> v * v end)),
...>     :sum],
...>
...>   # composed from existing dictionary keys (transforms) and pipelines
...>   v_f_number_gt_0: [:v_f_number, :v_f_gt_0],
...>   v_f_number_gt_0_lt_10: [:v_f_number_gt_0, [filter: fn v -> v < 10 end]],
...>   v_m_squared_plus_42: [:v_m_squared, :v_m_plus_42],
...>   v_f_number_gt_0_m_squared_plus_42: [:v_f_number_gt_0, :v_m_squared_plus_42],
...>   v_f_number_gt_0_m_squared_plus_42_minus_7: [
...>     :v_f_number_gt_0_m_squared_plus_42,
...>     [map: fn v -> v - 7 end]],
...>
...>   # copy of an existing key
...>   ensure_only_numbers: :v_f_number,
...> ]
...> |> build
iex> match?(%Plymio.Enum.Transform.Dictionary{}, td_test1)
true

Notes:

1. Each value can be one or more (List) of:

   • transform function (e.g. &(Stream.map(&1, fn {k,v} -> {k, v * v} end)))
   • transform pipeline (e.g. [filter: fn v -> is_number(v) end])
   • discrete transform (e.g. :sum),
   • existing dictionary transform (key) (e.g. : v_f_number)

2. :v_m_squared and :v_r_lt_45 values are explicit transform functions.

3. :v_f_gt_0_m_cubed is a list of transform_functions.

4. :v_f_lt_42_m_squared_and_sum is a mix (pipeline) of valid values.

5. :v_f_number_gt_0 is composed from existing transforms in the dictionary.

6. :v_ensure_only_numbers is a copy of :v_f_number

7. When the value is an Atom it could be a discrete transform (e.g. :sum) or an existing transform (e.g. :v_f_number) in the dictionary. Preference is given to existing dictionary transform.

8. Transforms composed from other dictionary keys are “frozen” and do not track changes to the keys used to compose them.

9. The dictionary is built one key at a time so “later” keys (e.g. :v_m_squared_plus_42) can be composed from “earlier” keys (:v_m_squared and :v_m_plus_42).

To make the following tests less cluttered, the above dictionary has been extracted into the helper function helper_dictionary_build_test1.

The two functions transform/3 and realise/3 complement Plymio.Enum.Transform.transform/2 and Plymio.Enum.Transform.realise/2.

Using a Transform Dictionary

This example selects (filters) just the numbers in the enumerable, returning a lazy enumerable. Normally transform returns a lazy enumerable (as does its peer Plymio.Enum.Transform.transform/2).

iex> td_test1 = helper_dictionary_build_test1()
 ...> result = [-1, make_ref(), 1, :atom, 2, "string", 3, &(&1), 4.25]
 ...> |> transform(td_test1, :v_f_number)
 ...> match?(%Stream{}, result)
 true

Calling realise/3 will return the actual result:

iex> td_test1 = helper_dictionary_build_test1()
 ...> [-1, make_ref(), 1, :atom, 2, "string", 3, &(&1), 4.25]
 ...> |> realise(td_test1, :v_f_number)
 [-1, 1, 2, 3, 4.25]

This example uses one of the composed transforms (:v_f_number_gt_0_m_squared_plus_42_minus_7) to filter just the numbers, square them, add 42 and subtract 7:

iex> td_test1 = helper_dictionary_build_test1()
 ...> [-1, make_ref(), 1, :atom, 2, "string", 3, &(&1), 4.25]
 ...> |> realise(td_test1, :v_f_number_gt_0_m_squared_plus_42_minus_7)
 [36, 39, 44, 53.0625]

Multiple transforms can be given as a list. (The last transform — :sum — always returns a real value)

iex> td_test1 = helper_dictionary_build_test1()
 ...> [-1, make_ref(), 1, :atom, 2, "string", 3, &(&1)]
 ...> |> transform(td_test1, [:v_f_number, :v_f_lt_42_m_squared_and_sum])
 15

A mix of transform forms (keys, functions, pipeline, discrete) can be given.

iex> td_test1 = helper_dictionary_build_test1()
 ...> [-1, make_ref(), 1, :atom, 2, "string", 3, &(&1)]
 ...> |> transform(td_test1, [:v_f_number, :v_f_gt_0, [map: fn v -> v*v*v end], :sum])
 36

Note a single pipeline must be inside another list

iex> td_test1 = helper_dictionary_build_test1()
 ...> [1,2,3] |> realise(td_test1, [[map: fn v -> v*v end]])
 [1,4,9]