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:

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

Link to this section Summary

Types

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

More about modifiers

This depends on the modifier

Value returned by non-bang path call

t()

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

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

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

Specs

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

More about modifiers

Link to this type

pathex_compatible_structure()

View Source

Specs

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

This depends on the modifier

Specs

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

Value returned by non-bang path call

Specs

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
Link to this macro

alongside(list)

View Source (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)
Link to this macro

at(struct, path, func)

View Source (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})
Link to this macro

at!(struct, path, func)

View Source (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})

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
Link to this macro

exists?(struct, path)

View Source (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)
Link to this macro

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

View Source (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

Link to this macro

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

View Source (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

Link to this macro

force_set(struct, path, value)

View Source (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"
Link to this macro

force_set!(struct, path, value)

View Source (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
Link to this macro

get(struct, path, default \\ nil)

View Source (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)
Link to this macro

over(struct, path, func)

View Source (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
Link to this macro

over!(struct, path, func)

View Source (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
Link to this macro

path(quoted, mod \\ nil)

View Source (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)
Link to this macro

set(struct, path, value)

View Source (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
Link to this macro

set!(struct, path, value)

View Source (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
Link to this macro

sigil_P(arg, mod)

View Source (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
Link to this macro

view(struct, path)

View Source (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
Link to this macro

view!(struct, path)

View Source (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