Pathex (Pathex v1.3.0) View Source
Main module. Use it inside your project to call Pathex macros
To use it just insert
defmodule MyModule do
require Pathex
import Pathex, only: [path: 1, path: 2, "~>": 2, ...]
...
end
Or you can use use
defmodule MyModule do
# `default_mod` option is optional
# when no mod is specified, `:naive` is selected
use Pathex, default_mod: :json
...
end
This will import all operatiors and path
macro
Any macro here belongs to one of three categories:
Link to this section Summary
Types
Function which is passed to path-closure as second element in args tuple
This depends on the modifier
Value returned by non-bang path call
Also known as path-closure
Functions
Creates composition of two paths which has some inspiration from logical and
Creates composition of two paths which has some inspiration from logical or
Creates composition of two paths similar to concating them together
This macro creates compositions of paths which work along with each other
Macro returns function applyed to the value in the path or error
Macro returns function applyed to the value in the path or error
The same as Pathex.~>/2
for those who do not like operators
Macro gets the value in the given path of the given structure or returns default value if not found
Macro of four arguments which applies given function in the given path of given structure
Macro of four arguments which applies given function in the given path of given structure
Macro of three arguments which sets the given value in the given path of given structure
Macro of three arguments which sets the given value in the given path of given structure
Macro gets the value in the given path of the given structure or returns default value if not found
Macro of three arguments which applies given function for item in the given path of given structure and returns modified structure
Macro of three arguments which applies given function for item in the given path of given structure
Creates path for given structure
Macro of three arguments which sets the given value in the given path of given structure
Macro of three arguments which sets the given value in the given path of given structure
Sigil for paths. Three modifiers are avaliable
Macro gets the value in the given path of the given structure
Macro gets the value in the given path of the given structure
Link to this section Types
Specs
force_update_args() :: {pathex_compatible_structure(), inner_func(), any()}
Specs
Function which is passed to path-closure as second element in args tuple
Specs
mod() :: :map | :json | :naive
More about modifiers
Specs
This depends on the modifier
Specs
result() :: {:ok, any()} | :error
Value returned by non-bang path call
Specs
t() :: (Pathex.Operations.name(), force_update_args() | update_args() -> result())
Also known as path-closure
Specs
update_args() :: {pathex_compatible_structure(), inner_func()}
Link to this section Functions
Creates composition of two paths which has some inspiration from logical and
Example:
iex> import Pathex
iex> p1 = path :x / :y
iex> p2 = path :a / :b
iex> ap = p1 &&& p2
iex> {:ok, 1} = view %{x: %{y: 1}, a: [b: 1]}, ap
iex> :error = view %{x: %{y: 1}, a: [b: 2]}, ap
iex> {:ok, %{x: %{y: 2}, a: [b: 2]}} = set %{x: %{y: 1}, a: [b: 1]}, ap, 2
iex> {:ok, %{x: %{y: 2}, a: %{b: 2}}} = force_set %{}, ap, 2
Creates composition of two paths which has some inspiration from logical or
Example:
iex> import Pathex
iex> p1 = path :x / :y
iex> p2 = path :a / :b
iex> op = p1 ||| p2
iex> {:ok, 1} = view %{x: %{y: 1}, a: [b: 2]}, op
iex> {:ok, 2} = view %{x: 1, a: [b: 2]}, op
iex> {:ok, %{x: %{y: 2}, a: [b: 1]}} = set %{x: %{y: 1}, a: [b: 1]}, op, 2
iex> {:ok, %{x: %{y: 2}}} = force_set %{}, op, 2
iex> {:ok, %{x: %{}, a: [b: 1]}} = force_set %{x: %{y: 1}, a: [b: 1]}, op, 2
Creates composition of two paths similar to concating them together
Example:
iex> import Pathex
iex> p1 = path :x / :y
iex> p2 = path :a / :b
iex> composed_path = p1 ~> p2
iex> {:ok, 1} = view %{x: [y: [a: [a: 0, b: 1]]]}, composed_path
This macro creates compositions of paths which work along with each other
Example:
iex> import Pathex
iex> pa = alongside [path(:x), path(:y)]
iex> {:ok, [1, 2]} = view(%{x: 1, y: 2}, pa)
iex> {:ok, %{x: 3, y: 3}} = set(%{x: 1, y: 2}, pa, 3)
iex> :error = set(%{x: 1}, pa, 3)
iex> {:ok, %{x: 1, y: 1}} = force_set(%{}, pa, 1)
Macro returns function applyed to the value in the path or error
Example:
iex> import Pathex
iex> x = 1
iex> {:ok, 9} = at [0, %{x: 8}], path(x / :x), fn x -> x + 1 end
iex> p = path "hey" / 0
iex> {:ok, {:here, 9}} = at(%{"hey" => {9, -9}}, p, & {:here, &1})
Macro returns function applyed to the value in the path or error
Example:
iex> import Pathex
iex> x = 1
iex> 9 = at! [0, %{x: 8}], path(x / :x), fn x -> x + 1 end
iex> p = path "hey" / 0
iex> {:here, 9} = at!(%{"hey" => {9, -9}}, p, & {:here, &1})
The same as Pathex.~>/2
for those who do not like operators
Example:
iex> import Pathex
iex> p1 = path :x / :y
iex> p2 = path :a / :b
iex> composed_path = concat(p1, p2)
iex> {:ok, 1} = view %{x: [y: [a: [a: 0, b: 1]]]}, composed_path
Macro gets the value in the given path of the given structure or returns default value if not found
Example:
iex> import Pathex
iex> x = 1
iex> true = exists?([0, %{x: 8}], path(x / :x))
iex> p = path "hey" / "you"
iex> false = exists?(%{"hey" => [x: 1]}, p)
Macro of four arguments which applies given function in the given path of given structure
If the path does not exist it creates the path favouring maps when structure is unknown and inserts default value
Example:
iex> import Pathex
iex> x = 1
iex> {:ok, [0, %{x: {:xxx, 8}}]} = force_over([0, %{x: 8}], path(x / :x), & {:xxx, &1}, 123)
iex> p = path "hey" / 0
iex> {:ok, %{"hey" => %{0 => 1}}} = force_over(%{}, p, fn x -> x + 1 end, 1)
If the item in path doesn't have the right type, it returns :error
Example:
iex> import Pathex
iex> p = path "hey" / "you"
iex> :error = force_over %{"hey" => {1, 2}}, p, fn x -> x end, "value"
Note: Default "default" value is nil
Macro of four arguments which applies given function in the given path of given structure
If the path does not exist it creates the path favouring maps when structure is unknown and inserts default value
Example:
iex> import Pathex
iex> x = 1
iex> [0, %{x: {:xxx, 8}}] = force_over!([0, %{x: 8}], path(x / :x), & {:xxx, &1}, 123)
iex> p = path "hey" / 0
iex> %{"hey" => %{0 => 1}} = force_over!(%{}, p, fn x -> x + 1 end, 1)
If the item in path doesn't have the right type, it raises Example:
iex> import Pathex
iex> p = path "hey" / "you"
iex> force_over! %{"hey" => {1, 2}}, p, fn x -> x end, "value"
** (Pathex.Error) Type mismatch in structure
Note: Default
default
value isnil
Macro of three arguments which sets the given value in the given path of given structure
If the path does not exist it creates the path favouring maps when structure is unknown
Example:
iex> import Pathex
iex> x = 1
iex> {:ok, [0, %{x: 123}]} = force_set [0, %{x: 8}], path(x / :x), 123
iex> p = path "hey" / 0
iex> {:ok, %{"hey" => %{0 => 1}}} = force_set %{}, p, 1
If the item in path doesn't have the right type, it returns :error
Example:
iex> import Pathex
iex> p = path "hey" / "you"
iex> :error = force_set %{"hey" => {1, 2}}, p, "value"
Macro of three arguments which sets the given value in the given path of given structure
If the path does not exist it creates the path favouring maps when structure is unknown
Example:
iex> import Pathex
iex> x = 1
iex> [0, %{x: 123}] = force_set! [0, %{x: 8}], path(x / :x), 123
iex> p = path "hey" / 0
iex> %{"hey" => %{0 => 1}} = force_set! %{}, p, 1
If the item in path doesn't have the right type, it raises Example:
iex> import Pathex
iex> p = path "hey" / "you"
iex> force_set! %{"hey" => {1, 2}}, p, "value"
** (Pathex.Error) Type mismatch in structure
Macro gets the value in the given path of the given structure or returns default value if not found
Example:
iex> import Pathex
iex> x = 1
iex> 8 = get([0, %{x: 8}], path(x / :x))
iex> p = path "hey" / "you"
iex> nil = get(%{"hey" => [x: 1]}, p)
iex> :default = get(%{"hey" => [x: 1]}, p, :default)
Macro of three arguments which applies given function for item in the given path of given structure and returns modified structure
Example:
iex> import Pathex
iex> x = 1
iex> inc = fn x -> x + 1 end
iex> {:ok, [0, %{x: 9}]} = over [0, %{x: 8}], path(x / :x), inc
iex> p = path "hey" / 0
iex> {:ok, %{"hey" => [2, [2]]}} = over %{"hey" => [1, [2]]}, p, inc
Note: Exceptions from passed function left unhandled
iex> import Pathex
iex> over(%{1 => "x"}, path(1), fn x -> x + 1 end)
** (ArithmeticError) bad argument in arithmetic expression
Macro of three arguments which applies given function for item in the given path of given structure
Example:
iex> import Pathex
iex> x = 1
iex> inc = fn x -> x + 1 end
iex> [0, %{x: 9}] = over! [0, %{x: 8}], path(x / :x), inc
iex> p = path "hey" / 0
iex> %{"hey" => [2, [2]]} = over! %{"hey" => [1, [2]]}, p, inc
Creates path for given structure
Example:
iex> import Pathex
iex> x = 1
iex> mypath = path 1 / :atom / "string" / {"tuple?"} / x
iex> structure = [0, [atom: %{"string" => %{{"tuple?"} => %{1 => 2}}}]]
iex> {:ok, 2} = view structure, mypath
Default modifier of this path/2
is :naive
which means that
- every variable is treated as index / key to any of tuple, list, map, keyword
- every atom is treated as key to map or keyword
- every integer is treated as index to tuple, list or key to map
- every other data is treated as key to map
Note:
-1
allows data to be prepended to the list
iex> import Pathex
iex> x = -1
iex> p1 = path(-1)
iex> p2 = path(x)
iex> {:ok, [1, 2]} = force_set([2], p1, 1)
iex> {:ok, [1, 2]} = force_set([2], p2, 1)
Macro of three arguments which sets the given value in the given path of given structure
Example:
iex> import Pathex
iex> x = 1
iex> {:ok, [0, %{x: 123}]} = set [0, %{x: 8}], path(x / :x), 123
iex> p = path "hey" / 0
iex> {:ok, %{"hey" => [123, [2]]}} = set %{"hey" => [1, [2]]}, p, 123
Macro of three arguments which sets the given value in the given path of given structure
Example:
iex> import Pathex
iex> x = 1
iex> [0, %{x: 123}] = set! [0, %{x: 8}], path(x / :x), 123
iex> p = path "hey" / 0
iex> %{"hey" => [123, [2]]} = set! %{"hey" => [1, [2]]}, p, 123
Sigil for paths. Three modifiers are avaliable:
naive
(default) paths should look like~P["string"/:atom/1]
json
paths should look like~P[string/this_one_is_too/1/0]json
map
paths should look like~P[:x/1]map
Example:
iex> import Pathex
iex> x = 1
iex> mypath = path 1 / :atom / "string" / {"tuple?"} / x
iex> structure = [0, [atom: %{"string" => %{{"tuple?"} => %{1 => 2}}}]]
iex> {:ok, 2} = view structure, mypath
Macro gets the value in the given path of the given structure
Example:
iex> import Pathex
iex> x = 1
iex> {:ok, 8} = view [0, %{x: 8}], path(x / :x)
iex> p = path "hey" / 0
iex> {:ok, 9} = view %{"hey" => {9, -9}}, p
Macro gets the value in the given path of the given structure
Example:
iex> import Pathex
iex> x = 1
iex> 8 = view! [0, %{x: 8}], path(x / :x)
iex> p = path "hey" / 0
iex> 9 = view! %{"hey" => {9, -9}}, p