View Source Pathex (Pathex v2.5.3)

This module contains main functions and macros used to create, use and manipulate paths.

Usage

To use Pathex just insert to your context. You can import Pathex in module body or even in function body.

require Pathex
import Pathex, only: [path: 1, path: 2, "~>": 2, ...]

Or you can just use Pathex.

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

Available macros

Any macro here belongs to one of three categories:

Macro which creates path closure (only path/2)
Macro which uses path closure to manipulate the value (like over/3, set/3, view/2, ...)
Macro which creates some path composition (like alongside/1, ~>/2, |||/2, ...)

Summary

Types

force_update_args(input, output)

inner_func(output)

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

inspect_args()

mod()

More about modifiers

pathex_compatible_structure()

This depends on the modifier

result(inner)

Value returned by non-bang path call

t()

Also known as path-closure

t(input, output)

Also known as path-closure

update_args(input, output)

Creates composition of two paths which has some inspiration from logical and. This means that a &&& b path-closure tries to apply a and only if it returns {:ok, something}, tries apply b and if b returns exactly the same as a does, the a &&& b returns {:ok, something}

__using__(opts)

Easy and convenient way to add pathex to your module.

alongside(list)

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

at(struct, path, func)

Applies func under path in struct and returns result of this func.

at!(struct, path, func)

Applies func under path in struct and returns result of this func. Raises if path is not found.

concat(a, b)

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

delete(struct, path)

Deletes value under path in struct.

delete!(struct, path)

Deletes value under path in struct or raises if value is not found.

exists?(struct, path)

Gets the value under path in struct or returns default value if not found.

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

Applies func under path of struct.

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

Applies func under path of struct.

force_set(struct, path, value)

Sets the value under path in struct.

force_set!(struct, path, value)

Sets the value under path in struct.

get(struct, path, default \\ nil)

Gets the value under path in struct or returns default when path is not present. Note that the default value is always lazily evaluted.

inspect(path_closure)

Inspect the given path-closure and returns string which corresponds to given path-closure

over(struct, path, func)

Applies func to the item under the path in struct and returns modified structure. Works like Map.update!/3 but doesn't raise.

over!(struct, path, func)

Applies the func to the item under path in struct and returns modified structure. Works like Map.update!/3.

path(quoted, mod \\ nil)

Creates path from quoted ast. Paths look like unix filesystems paths and consist of elements separated from each other with /. Each element defines the key or index in the collection.

pattern(variable \\ {:_, [], Elixir}, path)

This macro converts path (which can be matched upon) into pattern.

pop(struct, path)

Macro which gets value in the structure and deletes it.

pop!(struct, path)

Gets value under path in struct and then deletes it.

set(struct, path, value)

Sets value under path in structure. Think of it like Map.put/3.

set!(struct, path, value)

Sets the value under path in struct. Think of it like Map.put/3.

view(struct, path)

Gets the value under path in struct.

view!(struct, path)

Gets the value under path in struct. Raises if path not found.

a ||| b

Creates composition of two paths which has some inspiration from logical or. This means that a ||| b path-closure tries to apply a and only if it returns :error, tries apply b

a ~> b

Creates composition of two paths similar to concatenating them together. This means that a ~> b path-closure applies a and only if it returns {:ok, something} it applies b to something

Types

force_update_args(input, output)

@type force_update_args(input, output) :: {input, inner_func(output), any()}

inner_func(output)

@type inner_func(output) :: (any() -> result(output))

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

inspect_args()

@type inspect_args() :: any()

mod()

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

More about modifiers

pathex_compatible_structure()

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

This depends on the modifier

result(inner)

@type result(inner) :: {:ok, inner} | :error | :delete_me

Value returned by non-bang path call

t()

@type t() :: t(pathex_compatible_structure(), any())

Also known as path-closure

t(input, output)

@type t(input, output) ::
  (op_name(),
   force_update_args(input, output)
   | update_args(input, output)
   | inspect_args() ->
     result(output | input) | Macro.t())

Also known as path-closure

update_args(input, output)

@type update_args(input, output) :: {input, inner_func(output)}

Functions

a &&& b

(macro)

Example

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

using(opts)

(macro)

Easy and convenient way to add pathex to your module.

You can specify modifier

use Pathex, default_mod: :json

Or just use it with default :naive modifier

use Pathex

use Pathex
When you use Pathex, the Pathex module will require Pathex and import Pathex's operators, path/2 and alongside/1 macros. Plus it will set special module attribute with default_mod value in it.

alongside(list)

(macro)

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

Think of alongside([path1, path2, path3]) as path1 &&& path2 &&& path3 The only difference is that for viewing alongside returns list of variables

Example

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)

Applies func under path in struct and returns result of this func.

Example

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)

Applies func under path in struct and returns result of this func. Raises if path is not found.

Example

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

delete(struct, path)

(macro)

Deletes value under path in struct.

Example

iex> x = 1
iex> {:ok, [0, %{}]} = delete([0, %{x: 8}], path(x / :x))
iex> :error = delete([0, %{x: 8}], path(1 / :y))

delete!(struct, path)

(macro)

Deletes value under path in struct or raises if value is not found.

Example

iex> x = 1
iex> [0, %{}] = delete!([0, %{x: 8}], path(x / :x))

exists?(struct, path)

(macro)

Gets the value under path in struct or returns default value if not found.

Example

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)

Applies func under path of struct.

If the path does not exist it creates the path favouring maps when structure is unknown and inserts default value.

Example

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> p = path "hey" / "you"
iex> :error = force_over %{"hey" => {1, 2}}, p, fn x -> x end, "value"

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

(macro)

Applies func under path of struct.

If the path does not exist it creates the path favouring maps when structure is unknown and inserts default value.

Example

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> p = path "hey" / "you"
iex> force_over! %{"hey" => {1, 2}}, p, fn x -> x end, "value"
** (Pathex.Error) Type mismatch in structure

force_set(struct, path, value)

(macro)

Sets the value under path in struct.

If the path does not exist it creates the path favouring maps when structure is unknown.

Example

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> p = path "hey" / "you"
iex> :error = force_set %{"hey" => {1, 2}}, p, "value"

Note that for paths created with Pathex.path/2 list and tuple indexes which are out of bounds fill the empty space with nil.

Example

iex> p = path 4
iex> {:ok, [1, 2, 3, nil, 5]} = force_set [1, 2, 3], p, 5
iex> {:ok, {1, 2, 3, nil, 5}} = force_set {1, 2, 3}, p, 5

This is also true for negative indexes (except -1 for lists which always prepends)

Example

iex> p = path -5
iex> {:ok, [0, nil, 1, 2, 3]} = force_set [1, 2, 3], p, 0
iex> {:ok, {0, nil, 1, 2, 3}} = force_set {1, 2, 3}, p, 0

force_set!(struct, path, value)

(macro)

Sets the value under path in struct.

If the path does not exist it creates the path favouring maps when structure is unknown.

Example

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> p = path "hey" / "you"
iex> force_set! %{"hey" => {1, 2}}, p, "value"
** (Pathex.Error) Type mismatch in structure

Note that for paths created with Pathex.path/2 list and tuple indexes which are out of bounds fill the empty space with nil.

Example

iex> p = path 4
iex> [1, 2, 3, nil, 5] = force_set! [1, 2, 3], p, 5
iex> {1, 2, 3, nil, 5} = force_set! {1, 2, 3}, p, 5

This is also true for negative indexes (except -1 for lists which always prepends)

Example

iex> p = path -5
iex> [0, nil, 1, 2, 3] = force_set! [1, 2, 3], p, 0
iex> {0, nil, 1, 2, 3} = force_set! {1, 2, 3}, p, 0

get(struct, path, default \\ nil)

(macro)

Gets the value under path in struct or returns default when path is not present. Note that the default value is always lazily evaluted.

Example

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)

inspect(path_closure)

@spec inspect(t()) :: iodata()

Inspect the given path-closure and returns string which corresponds to given path-closure

Example

iex> index = 1
iex> p = path(:x) ~> path(:y / index) &&& path(-1)
iex> Pathex.inspect(p)
"path(:x) ~> path(:y / 1) &&& path(-1)"

over(struct, path, func)

(macro)

Applies func to the item under the path in struct and returns modified structure. Works like Map.update!/3 but doesn't raise.

Example

iex> index = 1
iex> inc = fn x -> x + 1 end
iex> {:ok, [0, %{x: 9}]} = over [0, %{x: 8}], path(index / :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> over(%{1 => "x"}, path(1), fn x -> x + 1 end)
** (ArithmeticError) bad argument in arithmetic expression

over!(struct, path, func)

(macro)

Applies the func to the item under path in struct and returns modified structure. Works like Map.update!/3.

Example

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 from quoted ast. Paths look like unix filesystems paths and consist of elements separated from each other with /. Each element defines the key or index in the collection.

Example

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

Paths can be used with one of the verbs in Pathex module (for example, Pathex.view/2). Paths can be customized with modifiers, composed using one of composition operators (Pathex.concat/2, Pathex.~>/2, Pathex.|||/2, Pathex.&&&/2 or Pathex.alongside/1).

Note: Each element in path can have collection type annotated using :: operator. Available collection types are :list, :keyword, :tuple and :map. Multiple collections can be annotated using list It must comply with the limits set with modifier.

Example

iex> p = path( (0 :: [:list, :map]) / (:x :: :keyword) )
iex> {:ok, :hit} = view %{0 => [x: :hit]}, p
iex> {:ok, :hit} = view [[x: :hit]], p
iex> :error = view [%{x: :hit}], p

pattern(variable \\ {:_, [], Elixir}, path)

(macro)

This macro converts path (which can be matched upon) into pattern.

These requirements must be satisfied in order for this macro to work correctly:

Path must be inlined into this macro. This means that path must be defined in a argument of this macro
Defined paths must contain constants only
Path must result only in case with one clause

Example

iex> import Pathex
iex> structure = %{users: %{1 => %{fname: "Jose", lname: "Valim"}}}
iex> case structure do
...>   pattern(fname, path(:users / 1 / :fname, :map)) ->
...>     {:ok, fname}
...>
...>   _ ->
...>     :error
...> end
{:ok, "Jose"}

pop(struct, path)

(macro)

Macro which gets value in the structure and deletes it.

Note:
Current implementation of this function performs double lookup. Which is still more efficient than pop_in

Example

iex> {:ok, {1, [2, 3]}} = pop([1, 2, 3], path(0))

pop!(struct, path)

(macro)

Gets value under path in struct and then deletes it.

Note:
Current implementation of this function performs double lookup. Which is still more efficient than pop_in

Example

iex> {1, [2, 3]} = pop!([1, 2, 3], path(0))

set(struct, path, value)

(macro)

Sets value under path in structure. Think of it like Map.put/3.

Example

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)

Sets the value under path in struct. Think of it like Map.put/3.

Example

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

view(struct, path)

(macro)

Gets the value under path in struct.

Example

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)

Gets the value under path in struct. Raises if path not found.

Example

iex> x = 1
iex> 8 = view! [0, %{x: 8}], path(x / :x)
iex> p = path "hey" / 0
iex> 9 = view! %{"hey" => {9, -9}}, p

a ||| b

(macro)

Creates composition of two paths which has some inspiration from logical or. This means that a ||| b path-closure tries to apply a and only if it returns :error, tries apply b

Example

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 concatenating them together. This means that a ~> b path-closure applies a and only if it returns {:ok, something} it applies b to something

Example

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