path_express v0.2.0 PathExpress View Source

Path Express provides nil-safe list navigation for use with Kernel.get_in/2 plus its own get_in/2 wrapper with some shortcuts.

Link to this section Summary

Functions

Returns a function that accesses all the elements in a list.

Returns a function that accesses the element at index (zero based) of a list.

Returns a function that accesses all elements of a list that match the provided predicate.

Allows pulling multiple paths out of a data tree into a map.

Gets a value from a nested structure.

Returns a function that maps all the elements in a list through your function ref.

Link to this section Functions

Link to this function

all()

View Source
all() :: Kernel.access_fun(data :: list(), get_value :: list())

Returns a function that accesses all the elements in a list.

The returned function is typically passed as an accessor to get_in/2 and Kernel.get_in/2.

Examples

iex> list = [%{name: "john"}, %{name: "mary"}]
iex> get_in(list, [PathExpress.all(), :name])
["john", "mary"]

An empty list is a shortcut to all/0 when PathExpress.get_in/2 used

iex> data = %{items: [%{qty: 1}, %{qty: 2}]}
iex> PathExpress.get_in(data, [:items, [], :qty])
[1, 2]

nil or a non-list is traversed by returning empty list:

 iex> get_in(nil, [PathExpress.all()])
 []
 iex> get_in(%{}, [PathExpress.all()])
 []
Link to this function

at(index)

View Source
at(integer()) :: Access.access_fun(data :: list(), get_value :: term())

Returns a function that accesses the element at index (zero based) of a list.

The returned function is typically passed as an accessor to get_in/2 and Kernel.get_in/2.

Examples

#

iex> list = [%{name: "john"}, %{name: "mary"}]
iex> get_in(list, [PathExpress.at(1), :name])
"mary"
iex> get_in(list, [PathExpress.at(-1), :name])
"mary"

nil or a non-list is traversed by returning nil:

iex> get_in(nil, [PathExpress.at(0)])
nil
iex> get_in(%{}, [PathExpress.at(1)])
nil
Link to this function

filter(func)

View Source
filter((term() -> boolean())) ::
  Kernel.access_fun(data :: list(), get_value :: list())

Returns a function that accesses all elements of a list that match the provided predicate.

The returned function is typically passed as an accessor to get_in/2 and Kernel.get_in/2.

Examples

iex> list = [%{name: "john", salary: 10}, %{name: "francine", salary: 30}]
iex> get_in(list, [PathExpress.filter(&(&1.salary > 20)), :name])
["francine"]

When no match is found, an empty list is returned:

iex> list = [%{name: "john", salary: 10}, %{name: "francine", salary: 30}]
iex> get_in(list, [PathExpress.filter(&(&1.salary >= 50)), :name])
[]

nil or a non-list is traversed by returning an empty list, as if no match is found:

iex> get_in(nil, [PathExpress.filter(&(&1.salary >= 50)), :name])
[]
iex> get_in(%{}, [PathExpress.filter(fn a -> a == 10 end)])
[]

An error is raised if the predicate is not a function or is of the incorrect arity:

iex> get_in([], [PathExpress.filter(5)])
** (FunctionClauseError) no function clause matching in PathExpress.filter/1
Link to this function

get_all_in(container, mappings)

View Source
get_all_in(Access.t(), map()) :: map()

Allows pulling multiple paths out of a data tree into a map.

iex> data = %{a: %{b: "pick me"}, c: [%{d: "pick me too"}]}
iex> mappings = %{me: [:a, :b], me2: [:c, 0, :d]}
iex> PathExpress.get_all_in(data, mappings)
%{me: "pick me", me2: "pick me too"}

Gets a value from a nested structure.

Uses a combination of functions from the Access module and PathExpress to traverse the structures in a nil-safe way according to the given keys, unless the key is a function, which is detailed in a later section.

Examples

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> get_in(users, ["john", :age])
27

In case any of the keys returns nil, nil will be returned:

iex> users = %{"john" => %{age: 27}, "meg" => %{age: 23}}
iex> get_in(users, ["unknown", :age])
nil
iex> get_in(users, ["unknown", PathExpress.at(0)])
nil

Shortcuts

Integers in keys will be treated as PathExpress.at/1 and an empty list will be treated as PathExpress.all/

iex> alias PathExpress, as: PE
iex> data = %{"users" => [%{name: "john", age: 27}, %{name: "meg", age: 23}]}
iex> PE.get_in(data, ["users", 0, :name])
"john"
iex> PE.get_in(data, ["users", [], :age])
[27, 23]

The examples above are nil-safe:

iex> alias PathExpress, as: PE
iex> data = %{}
iex> PE.get_in(data, ["users", 0, :name])
nil
iex> PE.get_in(data, ["users", [], :age])
[]

Functions as keys

See documentation for Kernel.get_in/2

Link to this function

map_all(custom_f)

View Source
map_all(fun(1)) :: Kernel.access_fun(data :: list(), get_value :: list())

Returns a function that maps all the elements in a list through your function ref.

The returned function is typically passed as an accessor to get_in/2 and Kernel.get_in/2.

Examples

iex> alias PathExpress, as: PE
iex> data = %{names: ["john", "mary"]}
iex> get_in(data, [:names, PE.map_all(&String.upcase/1)])
["JOHN", "MARY"]

A list containing the function ref is a shortcut to map_all/1 when PathExpress.get_in/2 used

iex> data = %{quantities: [1, 2]}
iex> PathExpress.get_in(data, [:quantities, [&(&1 + 1)]])
[2, 3]

nil or a non-list is traversed by returning empty list:

 iex> get_in(nil, [PathExpress.map_all(&String.upcase/1)])
 []
 iex> get_in(%{}, [PathExpress.map_all(&String.upcase/1)])
 []