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
all()
View Sourceall() :: 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()])
[]
at(index)
View Sourceat(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
filter(func)
View Sourcefilter((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
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"}
get_in(data, keys)
View Sourceget_in(Access.t(), Kernel.nonempty_list(term())) :: term()
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
map_all(custom_f)
View Sourcemap_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)])
[]