Pathex (Pathex v1.2.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
  use Pathex, default_mod: :json

  ...
end

This will import all operatiors and path macro

Note: There is no __using__/2 macro avaliable here because it would be better to explicitly define that the Pathex is used and what macros are exported

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

Link to this section Summary

Types

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

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

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

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

alongside(list)

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

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

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

path(quoted, mod \\ 'naive')

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

view(struct, path)

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

view!(struct, path)

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