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 the Pathex is used and what macroses are exported

Any macro here belongs to one of two 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, etc.)

Link to this section Summary

Types

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

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

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 \\ 'naive')

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

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

Link to this section Functions

a &&& b

(macro)

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

a ||| b

(macro)

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

a ~> b

(macro)

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

alongside(list)

(macro)

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)

at(struct, path, func)

(macro)

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

at!(struct, path, func)

(macro)

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

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

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> 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 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> 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"

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

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

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

over!(struct, path, func)

(macro)

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

path(quoted, mod \\ 'naive')

(macro)

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)

set(struct, path, value)

(macro)

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

set!(struct, path, value)

(macro)

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_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> 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

view(struct, path)

(macro)

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

view!(struct, path)

(macro)

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