View Source Iteraptor (iteraptor v1.14.0)

Iteraptor makes complicated nested structures (currently Maps, Lists and Keywords) iteration easier.

usage
Usage

Iterating, Mapping, Reducing

Iteraptor.each/3 to iterate a deeply nested map/list/keyword;
Iteraptor.map/3 to map a deeply nested map/list/keyword;
Iteraptor.reduce/4 to reduce a deeply nested map/list/keyword;
Iteraptor.map_reduce/4 to map and reduce a deeply nested map/list/keyword;

Flattening

Iteraptor.to_flatmap/2 to flatten a deeply nested map/list/keyword into flatten map with concatenated keys;
Iteraptor.from_flatmap/3 to “unveil”/“unflatten” the previously flattened map into nested structure;

Filtering

Iteraptor.filter/3 to filter the structure according to the value returned from each iteration (true to leave the element, false to discard.)

Link to this section Summary

Types

option()

options()

traverse_fun()

The function that might be passed to all the traversion functions.

Functions

each(input, fun, opts \\ [])

Iterates the given nested structure, calling the callback provided on each value. The key returned is an array of all the parent keys (and/or indices in a case of an array.)

filter(input, fun, opts \\ [])

Filters the deeply nested term, optionally calling the function on filtered entries.

from_flatmap(input, transformer \\ & &1, opts \\ [])

Build a nested structure out of a flatmap given, decomposing the names of keys and handling lists carefully.

jsonify(input, opts \\ [])

Produces a term ready-to-use with JSON interchange. Stringifies all keys and converts keywords to maps.

map(input, fun, opts \\ [])

Maps the given nested structure, calling the callback provided on each value. The key returned is a concatenated names of all the parent keys (and/or indices in a case of an array.)

map_reduce(input, acc \\ %{}, fun, opts \\ [])

Iteration with mapping and reducing. The function of arity 2, called back on each iteration with {k, v} pair and an accumulator is accepted.

reduce(input, acc \\ nil, fun, opts \\ [])

Iteration with reducing. The function of arity 2, called back on each iteration with {k, v} pair and an accumulator is accepted.

to_flatmap(input, opts \\ [])

Build a flatmap out of nested structure, concatenating the names of keys.

Link to this section Types

option()

@type option() ::
  {:keys, :reverse}
  | {:yield, :all | :none | :maps | :lists}
  | {:structs, :values | :keep}

options()

@type options() :: [option()]

traverse_fun()

@type traverse_fun() :: ({any(), any()} -> any()) | (any(), any() -> any())

The function that might be passed to all the traversion functions.

When it’s a function or arity 1, it receives {key, value} tuple when the key is the list of keys down the nesting levels.

When its arity is 2, it receives key and value as separated arguments.

Link to this section Functions

each(input, fun, opts \\ [])

@spec each(Access.t(), traverse_fun(), options()) :: Access.t()

Iterates the given nested structure, calling the callback provided on each value. The key returned is an array of all the parent keys (and/or indices in a case of an array.)

The return value is self.

parameters
Parameters

input: nested map/list/keyword to be walked through.
fun: callback to be called on each {key, value} pair, where key is an array or deeply nested keys; e.g. on %{a: {b: 42}} will be called once, with tuple {[:a, :b], 42};
opts: the options to be passed to the iteration
- yield: [:all | :none | :maps | :lists] what to yield; default: :all for yielding values only
- keys: [:reverse] reverse keys list to ease pattern matching; default: nil
- structs: [:values | :keep] how to handle structs; default: :values for treating them as maps. When :values, the nested structs are considered leaves and returned to the iterator instead of being iterated through; when :keep it returns a struct back after iteration

examples
Examples

iex> %{a: %{b: %{c: 42}}} |> Iteraptor.each(&IO.inspect/1)
{[:a, :b, :c], 42}
%{a: %{b: %{c: 42}}}

iex> %{a: %{b: %{c: 42}}} |> Iteraptor.each(&IO.inspect/1, yield: :all)
{[:a], %{b: %{c: 42}}}
{[:a, :b], %{c: 42}}
{[:a, :b, :c], 42}
%{a: %{b: %{c: 42}}}

filter(input, fun, opts \\ [])

@spec filter(Access.t(), traverse_fun(), options()) :: Access.t()

Filters the deeply nested term, optionally calling the function on filtered entries.

The return value is the filtered term.

parameters
Parameters

input: nested map/list/keyword to be filtered.
fun: callback to be called on each {key, value} to filter entries.
opts: the options to be passed to the iteration (see Iteraptpr.each/3)

examples
Examples

iex> %{a: %{b: 42, e: %{f: 3.14, c: 42}, d: %{c: 42}}, c: 42, d: 3.14}
...> |> Iteraptor.filter(fn {key, _} -> :c in key end, yield: :none)
%{a: %{e: %{c: 42}, d: %{c: 42}}, c: 42}

from_flatmap(input, transformer \\ & &1, opts \\ [])

@spec from_flatmap(%{}, traverse_fun(), options()) :: Access.t()

Build a nested structure out of a flatmap given, decomposing the names of keys and handling lists carefully.

%{"a.b.c": 42, "a.b.d.0": nil, "a.b.d.1": 42, "a.e.0": :f, "a.e.1": 42}
|> Iteraptor.from_flatmap
#⇒ %{a: %{b: %{c: 42, d: [nil, 42]}, e: [:f, 42]}}

parameters
Parameters

input: flat map to be “expanded” to nested maps/lists,
transformer: the transformer function to be called on all the elements,
opts: additional options to be passed through.

examples
Examples

iex> %{"a.b.c": 42} |> Iteraptor.from_flatmap
%{a: %{b: %{c: 42}}}

iex> %{"a.b.c": 42, "a.b.d": 42} |> Iteraptor.from_flatmap
%{a: %{b: %{c: 42, d: 42}}}

iex> %{"a.b.c": 42, "a.b.d": 42, "a.e": 42} |> Iteraptor.from_flatmap
%{a: %{b: %{c: 42, d: 42}, e: 42}}

iex> %{"0": 42, "1": 42} |> Iteraptor.from_flatmap
[42, 42]

iex> %{"1": :a1, "0": :a0, "2": :a2, "3": :a3, "4": :a4, "5": :a5,
...>   "6": :a6, "7": :a7, "8": :a8, "9": :a9, "10": :a10, "11": :a11}
...> |> Iteraptor.from_flatmap
[:a0, :a1, :a2, :a3, :a4, :a5, :a6, :a7, :a8, :a9, :a10, :a11]

iex> %{"0.a": 42, "0.b": 42} |> Iteraptor.from_flatmap
[%{a: 42, b: 42}]

iex> %{"a.0.0" => :b, "a.1" => 42, d: 42} |> Iteraptor.from_flatmap
%{a: [[:b], 42], d: 42}

iex> %{"a.b.c": 42, "a.b.d.0": nil, "a.b.d.1": 42, "a.e.0": :f, "a.e.1": 42}
...> |> Iteraptor.from_flatmap
%{a: %{b: %{c: 42, d: [nil, 42]}, e: [:f, 42]}}

iex> %{"0.a": 42, "0.b": 42} |> Iteraptor.from_flatmap(&IO.inspect/1)
{[0, :a], 42}
{[0, :b], 42}
[%{a: 42, b: 42}]

jsonify(input, opts \\ [])

@spec jsonify(
  Access.container() | any(),
  keyword()
) :: map()

Produces a term ready-to-use with JSON interchange. Stringifies all keys and converts keywords to maps.

If the option keys: false is given, leaves keys intact.

examples
Examples

iex> Iteraptor.jsonify([foo: [:zzz], bar: :baz], values: true)
%{"foo" => ["zzz"], "bar" => "baz"}

iex> Iteraptor.jsonify(%{foo: [1, [bar: 2], 3], bar: [baz: 42]})
%{"foo" => [1, %{"bar" => 2}, 3], "bar" => %{"baz" => 42}}

iex> Iteraptor.jsonify([foo: [bar: [baz: :zoo], boo: 42]], values: true)
%{"foo" => %{"bar" => %{"baz" => "zoo"}, "boo" => 42}}

iex> Iteraptor.jsonify([foo: [bar: [baz: :zoo], boo: 42]], keys: false)
%{foo: %{bar: %{baz: :zoo}, boo: 42}}

map(input, fun, opts \\ [])

@spec map(Access.t(), traverse_fun(), options()) :: Access.t()

Maps the given nested structure, calling the callback provided on each value. The key returned is a concatenated names of all the parent keys (and/or indices in a case of an array.)

The return value is the result of subsequent calls to the transformer given.

parameters
Parameters

input: nested map/list/keyword to be mapped.
fun: callback to be called on each {key, value} pair, where key is an array or deeply nested keys; e.g. on %{a: {b: 42}} will be called once, with tuple {[:a, :b], 42};
opts: the options to be passed to the iteration (see Iteraptpr.each/3)

examples
Examples

iex> %{a: %{b: %{c: 42}}} |> Iteraptor.map(fn {_, v} -> v * 2 end)
%{a: %{b: %{c: 84}}}

iex> %{a: %{b: %{c: 42}}} |> Iteraptor.map(fn {k, _} -> Enum.join(k) end)
%{a: %{b: %{c: "abc"}}}

iex> %{a: %{b: %{c: 42}}}
...> |> Iteraptor.map(fn
...>      {[_], _} = self -> self
...>      {[_, _], _} -> "YAY"
...>    end, yield: :all)
%{a: %{b: "YAY"}}

map_reduce(input, acc \\ %{}, fun, opts \\ [])

@spec map_reduce(Access.t(), Access.t(), traverse_fun(), options()) ::
  {Access.t(), any()}

Iteration with mapping and reducing. The function of arity 2, called back on each iteration with {k, v} pair and an accumulator is accepted.

The return value is the tuple, consisting of mapped input and the accumulator from the last call to the passed map-reducer.

parameters
Parameters

input: nested map/list/keyword to be mapped.
fun: callback to be called on each {key, value}, acc pair, where key is an array or deeply nested keys, value is the value and acc is the accumulator;
opts: the options to be passed to the iteration (see Iteraptpr.each/3)

examples
Examples

iex> %{a: %{b: %{c: 42}}}
...> |> Iteraptor.map_reduce([], fn
...>      {k, %{} = v}, acc -> {{k, v}, [Enum.join(k, ".") | acc]}
...>      {k, v}, acc -> {{k, v * 2}, [Enum.join(k, ".") <> "=" | acc]}
...>    end, yield: :all)
{%{a: %{b: %{c: 84}}}, ["a.b.c=", "a.b", "a"]}

reduce(input, acc \\ nil, fun, opts \\ [])

@spec reduce(Access.t(), Access.t(), traverse_fun(), options()) :: Access.t()

Iteration with reducing. The function of arity 2, called back on each iteration with {k, v} pair and an accumulator is accepted.

The return value is the result of the last call to the passed reducer function.

parameters
Parameters

input: nested map/list/keyword to be mapped.
fun: callback to be called on each {key, value}, acc pair, where key is an array or deeply nested keys, value is the value and acc is the accumulator;
opts: the options to be passed to the iteration (see Iteraptpr.each/3)

examples
Examples

iex> %{a: %{b: %{c: 42}}}
...> |> Iteraptor.reduce([], fn {k, _}, acc ->
...>      [Enum.join(k, "_") | acc]
...>    end, yield: :all)
...> |> :lists.reverse()
["a", "a_b", "a_b_c"]

to_flatmap(input, opts \\ [])

@spec to_flatmap(Access.t(), options()) :: %{}

Build a flatmap out of nested structure, concatenating the names of keys.

%{a: %{b: %{c: 42, d: [nil, 42]}, e: [:f, 42]}} |> Iteraptor.to_flatmap
%{"a.b.c": 42, "a.b.d.0": nil, "a.b.d.1": 42, "a.e.0": :f, "a.e.1": 42}

Lists are handled gracefully, index is used as a key in resulting map.

parameters
Parameters

input: nested map/list/keyword/struct to be flattened,
opts: the additional options to be passed through: — delimiter (default: ".",) might be passed explicitly or configured with :iteraptor, :delimiter application setting.

examples
Examples

iex> [:a, 42] |> Iteraptor.to_flatmap
%{0 => :a, 1 => 42}

iex> %{a: 42} |> Iteraptor.to_flatmap
%{a: 42}

iex> %{a: 42, b: 42} |> Iteraptor.to_flatmap
%{a: 42, b: 42}

iex> %{a: %{b: 42}, d: 42} |> Iteraptor.to_flatmap
%{"a.b" => 42, d: 42}

iex> %{a: [:b, 42], d: 42} |> Iteraptor.to_flatmap
%{"a.0" => :b, "a.1" => 42, d: 42}

iex> %{a: %{b: [:c, 42]}, d: 42} |> Iteraptor.to_flatmap
%{"a.b.0" => :c, "a.b.1" => 42, d: 42}

iex> %{a: %{b: 42}} |> Iteraptor.to_flatmap
%{"a.b" => 42}

iex> %{a: %{b: %{c: 42}}} |> Iteraptor.to_flatmap
%{"a.b.c" => 42}

iex> %{a: %{b: %{c: 42}}, d: 42} |> Iteraptor.to_flatmap
%{"a.b.c" => 42, d: 42}

iex> [a: [b: [c: 42]], d: 42] |> Iteraptor.to_flatmap
%{"a.b.c" => 42, d: 42}

iex> [a: [[:b], 42], d: 42] |> Iteraptor.to_flatmap
%{"a.0.0" => :b, "a.1" => 42, d: 42}

iex> %{a: %{b: %{c: 42, d: [nil, 42]}, e: [:f, 42]}} |> Iteraptor.to_flatmap
%{"a.b.c" => 42, "a.b.d.0" => nil, "a.b.d.1" => 42, "a.e.0" => :f, "a.e.1" => 42}

iex> %{a: %{b: %{c: 42, d: [nil, 42]}, e: [:f, 42]}}
...> |> Iteraptor.to_flatmap(delimiter: "_")
%{"a_b_c" => 42, "a_b_d_0" => nil, "a_b_d_1" => 42, "a_e_0" => :f, "a_e_1" => 42}

Settings View Source Iteraptor (iteraptor v1.14.0)

usage Usage

Iterating, Mapping, Reducing

Flattening

Filtering

Link to this section Summary

Types

Functions

Link to this section Types

option()

options()

traverse_fun()

Link to this section Functions

each(input, fun, opts \\ [])

parameters Parameters

examples Examples

filter(input, fun, opts \\ [])

parameters Parameters

examples Examples

from_flatmap(input, transformer \\ & &1, opts \\ [])

parameters Parameters

examples Examples

jsonify(input, opts \\ [])

examples Examples

map(input, fun, opts \\ [])

parameters Parameters

examples Examples

map_reduce(input, acc \\ %{}, fun, opts \\ [])

parameters Parameters

examples Examples

reduce(input, acc \\ nil, fun, opts \\ [])

parameters Parameters

examples Examples

to_flatmap(input, opts \\ [])

parameters Parameters

examples Examples

View Source Iteraptor (iteraptor v1.14.0)

usage
Usage

parameters
Parameters

examples
Examples

parameters
Parameters

examples
Examples

parameters
Parameters

examples
Examples

examples
Examples

parameters
Parameters

examples
Examples

parameters
Parameters

examples
Examples

parameters
Parameters

examples
Examples

parameters
Parameters

examples
Examples