Pathex (Pathex v1.0.0) View Source
Main module. Use it inside your project to call Pathex macroses
To use it just insert
defmodule MyModule do
require Pathex
import Pathex, only: [path: 1, path: 2, "~>": 2, ...]
...
end
Note: There is no
__using__/2
macro avaliable here because it would be better to explicitly define that thePathex
is used and what macroses are exported
Any macro here belongs to one of two categories:
Link to this section Summary
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
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
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
Link to this section Functions
Creates composition of two paths which has some inspiration from logical and
Example:
iex> require Pathex; 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> require Pathex; 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: 2]}, ap
iex> {:ok, 2} = view %{x: 1, a: [b: 2]}, ap
iex> {:ok, %{x: %{y: 2}, a: [b: 1]}} = set %{x: %{y: 1}, a: [b: 1]}, ap, 2
iex> {:ok, %{x: %{y: 2}}} = force_set %{}, ap, 2
Creates composition of two paths similar to concating them together
Example:
iex> require Pathex; 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> require Pathex; import Pathex
iex> p1 = path :x
iex> p2 = path :y
iex> pa = alongside [p1, p2]
iex> {:ok, [1, 2]} = view(%{x: 1, y: 2}, pa)
iex> {:ok, %{x: 3, y: 3}} = set(%{x: 1, y: 2}, 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> require Pathex; 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> require Pathex; 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})
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> require Pathex; 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> require Pathex; 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> require Pathex; 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> require Pathex; 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> require Pathex; 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> require Pathex; 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> require Pathex; 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> require Pathex; 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> require Pathex; import Pathex
iex> x = 1
iex> 8 = get [0, %{x: 8}], path(x / :x)
iex> p = path "hey" / "you"
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> require Pathex; 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> require Pathex; 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> require Pathex; 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> require Pathex; 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> require Pathex; 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> require Pathex; 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> require Pathex; 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> require Pathex; 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> require Pathex; 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> require Pathex; 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