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:

Macro which creates path closure (sigil_P/2, path/2, ~>/2)
Macro which uses path closure as path (over/3, set/3, view/2, ...)
Macro which creates path composition (~>/2, |||/2, ...)

Link to this section Summary

Types

force_update_args()

inner_func()

Function which is passed to path-closure as second element in args tuple

mod()

More about modifiers

pathex_compatible_structure()

This depends on the modifier

result()

Value returned by non-bang path call

t()

Also known as path-closure

update_args()

Functions

a &&& b

Creates composition of two paths which has some inspiration from logical and

a ||| b

Creates composition of two paths which has some inspiration from logical or

a ~> b

Creates composition of two paths similar to concating them together

alongside(list)

This macro creates compositions of paths which work along with each other

at(struct, path, func)

Macro returns function applyed to the value in the path or error

at!(struct, path, func)

Macro returns function applyed to the value in the path or error

concat(a, b)

The same as Pathex.~>/2 for those who do not like operators

exists?(struct, path)

Macro gets the value in the given path of the given structure or returns default value if not found

force_over(struct, path, func, value \\ nil)

Macro of four arguments which applies given function in the given path of given structure

force_over!(struct, path, func, value \\ nil)

Macro of four arguments which applies given function in the given path of given structure

force_set(struct, path, value)

Macro of three arguments which sets the given value in the given path of given structure

force_set!(struct, path, value)

Macro of three arguments which sets the given value in the given path of given structure

get(struct, path, default \\ nil)

Macro gets the value in the given path of the given structure or returns default value if not found

over(struct, path, func)

Macro of three arguments which applies given function for item in the given path of given structure and returns modified structure

over!(struct, path, func)

Macro of three arguments which applies given function for item in the given path of given structure

path(quoted, mod \\ nil)

Creates path for given structure

set(struct, path, value)

Macro of three arguments which sets the given value in the given path of given structure

set!(struct, path, value)

Macro of three arguments which sets the given value in the given path of given structure

sigil_P(arg, mod)

Sigil for paths. Three modifiers are avaliable

view(struct, path)

Macro gets the value in the given path of the given structure

view!(struct, path)

Macro gets the value in the given path of the given structure

Link to this section Types

force_update_args()

Specs

force_update_args() :: {pathex_compatible_structure(), inner_func(), any()}

inner_func()

Specs

inner_func() :: (any() -> {:ok, any()} | :error)

Function which is passed to path-closure as second element in args tuple

mod()

Specs

mod() :: :map | :json | :naive

More about modifiers

pathex_compatible_structure()

Specs

pathex_compatible_structure() :: map() | list() | Keyword.t() | tuple()

This depends on the modifier

result()

Specs

result() :: {:ok, any()} | :error

Value returned by non-bang path call

t()

Specs

t() ::
  (Pathex.Operations.name(), force_update_args() | update_args() -> result())

Also known as path-closure

update_args()

Specs

update_args() :: {pathex_compatible_structure(), inner_func()}

Link to this section Functions

a &&& b

(macro)

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

a ||| b

(macro)

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

a ~> b

(macro)

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

alongside(list)

(macro)

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)

at(struct, path, func)

(macro)

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})

at!(struct, path, func)

(macro)

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})

concat(a, b)

(macro)

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

exists?(struct, path)

(macro)

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)

force_over(struct, path, func, value \\ nil)

(macro)

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

force_over!(struct, path, func, value \\ nil)

(macro)

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 is nil

force_set(struct, path, value)

(macro)

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"

force_set!(struct, path, value)

(macro)

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

get(struct, path, default \\ nil)

(macro)

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)

over(struct, path, func)

(macro)

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

over!(struct, path, func)

(macro)

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

path(quoted, mod \\ nil)

(macro)

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)

set(struct, path, value)

(macro)

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

set!(struct, path, value)

(macro)

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_P(arg, mod)

(macro)

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

view(struct, path)

(macro)

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

view!(struct, path)

(macro)

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