plymio_ast v0.2.0 Plymio.Ast.Helpers

Miscellaneous Helper Functions

Summary

Functions

aliases_tuples_create/1 takes Keyword where the keys are the canonical key names, and their values are zero (nil), one or more aliases for the canonical key

canon_keys/2 takes a list of keys together with a lookup dictionary and replaces each key with its canonical value from the dictionary, returning {:ok, known_keys_values}

canon_keys!/2 takes a list of keys together with a lookup dictionary and replaces each key with its canonical value from the dictionary. Unknown keys raise a KeyError

list_wrap_flat_just/1 wraps a value (if not already a list), flattens and removes nils at the first / top level

list_wrap_flat_just_uniq/1 wraps a value (if not already a list), flattens, removes nils at the first / top level, and deletes duplicates (using Enum.uniq/1)

maybe_canon_keys/2 takes a list of keys together with a lookup dictionary and, if the key is in the dictionary, replaces it with its value. Unknown keys are passed through unchanged

opts_canon_keys/2 takes an opts list, together with a lookup dictionary and replaces each key with its canonical value from the dictionary, returning {:ok, opts}

opts_canon_keys!/2 takes an opts list, together with a lookup dictionary and replaces each key with its canonical value from the dictionary. Unknown keys raise a KeyError

opts_sort_keys/ takes an opts list, together with a list of sort keys, and returns the opts sorted in the sort keys order. Duplicate keys follow one after another

struct_kvs_create/2 takes an opts list, together with a defaults map, and returns an opts list where each value is the value of the key in the defaults map (with default nil)

unquotables_maybe_escape/1 takes a key-value enumerable, validates whether each value is a valid ast (Macro.validate/1) and escapes the value (Macro.escape/1) if not, returning a Map

Types

alias_key()
alias_key() :: atom
alias_keys()
alias_keys() :: alias_key | [alias_key]
alias_value()
alias_value() :: nil | alias_keys
aliases_kvs()
aliases_kvs() :: [{alias_key, alias_value}]
aliases_map()
aliases_map() :: %{optional(alias_key) => alias_key}
aliases_tuples()
aliases_tuples() :: [{alias_key, alias_key}]
ast()
ast() :: Macro.t
defaults_map()
defaults_map() :: %{optional(alias_key) => any}
dict()
dict() :: %{optional(alias_key) => any}
maybe_unquotables()
maybe_unquotables ::
  %{optional(atom) => any} |
  [{atom, any}]
opts()
opts() :: Keyword.t
unquotables()
unquotables() :: %{optional(atom) => ast}

Functions

aliases_map_create(aliases)
aliases_map_create(aliases_kvs) :: aliases_map

aliases_map_create/1 does the same job as aliases_tuples_create/1 but returns a map.

Examples

iex> [a: nil, b: [:b1], c: [:c1, :c2, :c3]] |> aliases_map_create
%{a: :a, b: :b, b1: :b, c: :c, c1: :c, c2: :c, c3: :c}
aliases_tuples_create(aliases)
aliases_tuples_create(aliases_kvs) :: aliases_tuples

aliases_tuples_create/1 takes Keyword where the keys are the canonical key names, and their values are zero (nil), one or more aliases for the canonical key.

A Keyword is returned where each key is an alias and its value the canonical key.

The canonical key also has an entry with the same value.

Examples

iex> [a: nil, b: [:b1], c: [:c1, :c2, :c3]] |> aliases_tuples_create
[a: :a, b: :b, b1: :b, c: :c, c1: :c, c2: :c, c3: :c]
canon_keys(keys, dict)
canon_keys(alias_keys, dict) ::
  {:ok, alias_keys} |
  {:error, {alias_keys, list}}

canon_keys/2 takes a list of keys together with a lookup dictionary and replaces each key with its canonical value from the dictionary, returning {:ok, known_keys_values}.

If there are any unknown keys, {:error, {known_keys_values, unknown_keys}} is returned.

Examples

iex> [:a, :b, :c] |> canon_keys(%{a: 1, b: 2, c: 3})
{:ok, [1,2,3]}

iex> [:a, :x, :b, :y, :c, :z] |> canon_keys(%{a: 1, b: 2, c: 3})
{:error, {[1, 2, 3], [:x, :y, :z]}}
canon_keys!(keys, dict)
canon_keys!(alias_keys, dict) :: alias_keys | no_return

canon_keys!/2 takes a list of keys together with a lookup dictionary and replaces each key with its canonical value from the dictionary. Unknown keys raise a KeyError.

Examples

iex> [:a, :b, :c] |> canon_keys!(%{a: 1, b: 2, c: 3})
[1,2,3]

iex> [:x] |> canon_keys!(%{a: 1, b: 2, c: 3})
** (KeyError) key :x not found in: %{a: 1, b: 2, c: 3}
list_wrap_flat_just(value)
list_wrap_flat_just(any) :: [any]

list_wrap_flat_just/1 wraps a value (if not already a list), flattens and removes nils at the first / top level.

Examples

iex> [{:a, 1}, nil, [{:b1, 12}, nil, {:b2, [nil, 22, nil]}], nil, {:c, 3}] |> list_wrap_flat_just
[a: 1, b1: 12, b2: [nil, 22, nil], c: 3]

iex> [[[nil, 42, nil]]] |> list_wrap_flat_just
[42]
list_wrap_flat_just_uniq(value)
list_wrap_flat_just_uniq(any) :: [any]

list_wrap_flat_just_uniq/1 wraps a value (if not already a list), flattens, removes nils at the first / top level, and deletes duplicates (using Enum.uniq/1)

Examples

iex> [{:a, 1}, nil, [{:b1, 12}, nil, {:b2, [nil, 22, nil]}], nil, {:c, 3}, {:a, 1}, {:b1, 12}] |> list_wrap_flat_just_uniq
[a: 1, b1: 12, b2: [nil, 22, nil], c: 3]

iex> [nil, [42, [42, 42, nil]], 42] |> list_wrap_flat_just_uniq
[42]
maybe_canon_keys(keys, dict)
maybe_canon_keys(alias_keys, dict) :: alias_keys

maybe_canon_keys/2 takes a list of keys together with a lookup dictionary and, if the key is in the dictionary, replaces it with its value. Unknown keys are passed through unchanged.

Examples

iex> [:a, :b, :c] |> maybe_canon_keys(%{a: 1, b: 2, c: 3})
[1, 2, 3]

iex> [:x, :a] |> maybe_canon_keys(%{a: 1, b: 2, c: 3})
[:x, 1]
opts_canon_keys(opts, dict)
opts_canon_keys(opts, dict) ::
  {:ok, opts} |
  {:error, {opts, opts}}

opts_canon_keys/2 takes an opts list, together with a lookup dictionary and replaces each key with its canonical value from the dictionary, returning {:ok, opts}.

If there are any unknown keys, {:error, {known_opts, unknown_opts}} is returned.

Examples

iex> [a: 1, b: 2, c: 3] |> opts_canon_keys(%{a: :x, b: :y, c: :z})
{:ok, [x: 1, y: 2, z: 3]}

iex> [a: 11, p: 1, b: 22, q: 2, c: 33, r: 3] |> opts_canon_keys(%{a: :x, b: :y, c: :z})
{:error, {[x: 11, y: 22, z: 33], [p: 1, q: 2, r: 3]}}
opts_canon_keys!(opts, dict)
opts_canon_keys!(opts, dict) :: opts | no_return

opts_canon_keys!/2 takes an opts list, together with a lookup dictionary and replaces each key with its canonical value from the dictionary. Unknown keys raise a KeyError.

Examples

iex> [a: 1, b: 2, c: 3] |> opts_canon_keys!(%{a: :x, b: :y, c: :z})
[x: 1, y: 2, z: 3]

iex> [x: 1, y: 3, z: 3] |> opts_canon_keys!(%{a: 1, b: 2, c: 3})
** (KeyError) key :x not found in: %{a: 1, b: 2, c: 3}
opts_sort_keys(opts, keys \\ [])
opts_sort_keys(opts, alias_keys) :: opts

opts_sort_keys/ takes an opts list, together with a list of sort keys, and returns the opts sorted in the sort keys order. Duplicate keys follow one after another.

Any keys found but not given in the sort keys follow the sorted keys in the returned opts.

Any key in the sort list not found in the opts is ignored.

Examples

iex> [a: 1, b: 2, c: 3, d: 4] |> opts_sort_keys([:c, :a])
[c: 3, a: 1,  b: 2, d: 4]

iex> [a: 1, b: 2, c: 3, d: 4] |> opts_sort_keys([:d, :x, :b, :z])
[d: 4, b: 2, a: 1, c: 3]
struct_kvs_create(struct_kvs, defaults_map \\ %{})
struct_kvs_create(opts, defaults_map) :: opts

struct_kvs_create/2 takes an opts list, together with a defaults map, and returns an opts list where each value is the value of the key in the defaults map (with default nil).

struct_kvs_create/2 creates an argument suitable for use with Kernel.defstruct/1

Examples

iex> [a: 1, b: :two, c: "tre", d: nil] |> struct_kvs_create(%{a: 42, b: "two"})
[a: 42, b: "two", c: nil, d: nil]
unquotables_maybe_escape(maybe_unquotables)
unquotables_maybe_escape(maybe_unquotables) :: unquotables

unquotables_maybe_escape/1 takes a key-value enumerable, validates whether each value is a valid ast (Macro.validate/1) and escapes the value (Macro.escape/1) if not, returning a Map.

Examples

iex> [a: 1, b: :two, c: "tre"] |> unquotables_maybe_escape
%{a: 1, b: :two, c: "tre"}

iex> [a: 1, b: %{b1: 21}, c: {:c, 3, :tre, "tre"}] |> unquotables_maybe_escape
%{a: 1, b: {:%{}, [], [b1: 21]}, c: {:{}, [], [:c, 3, :tre, "tre"]}}

iex> [a: 1, b: %{b1: 21}, c: quote(do: {:c, 3, :tre, "tre"})] |> unquotables_maybe_escape
%{a: 1, b: {:%{}, [], [b1: 21]}, c: {:{}, [], [:c, 3, :tre, "tre"]}}