Macaw.Layers.Fault (macaw_layers v0.2.2)

Copy Markdown View Source

A fault in a document, {path, reason}, and the one formatter that words it (spec/01 §3).

The path runs from the document's root: atoms or strings for keys, non-negative integers for list positions. A key the document type does not know stays at its own spelling, a string. Every fault is reported, never just the first, ordered by path (sort/1).

format/2 words a fault as path: words. The kernel words its own reasons; any other is the document type's, given as words::

iex> Macaw.Layers.Fault.format({[:frames, "main", "wdth"], :unknown_key})
"frames.main.wdth: is not a key of this node"
iex> Macaw.Layers.Fault.format({[], {:newer_schema, 4, 3}}, root: "design")
"design: needs schema v4, this is v3"

The formatter is visualize's Visualize.Chart.Validator.format/1 and the generic part of its wording, with the root's name and the type's own wording as options.

Summary

Types

option()

format/2's options.

path()

Where a fault is: keys and list positions from the document's root.

t()

A fault: where, and why.

Functions

format(arg, opts \\ [])

A fault as path: words.

format_path(path, opts \\ [])

A path as a person reads it: keys joined by ., an index as [i], and the empty path as the root's name.

sort(faults)

Faults ordered by path, keeping the given order of faults at one path.

Types

option()

@type option() :: {:root, String.t()} | {:words, (term() -> String.t())}

format/2's options.

path()

@type path() :: [atom() | String.t() | non_neg_integer()]

Where a fault is: keys and list positions from the document's root.

t()

@type t() :: {path(), reason :: term()}

A fault: where, and why.

Functions

format(arg, opts \\ [])

@spec format(t(), [option()]) :: String.t()

A fault as path: words.

Options:

  • root: the name of the empty path, "document" by default;
  • words: a function that words the reasons the kernel does not. Without one, such a reason is shown with inspect/1.

format_path(path, opts \\ [])

@spec format_path(path(), [option()]) :: String.t()

A path as a person reads it: keys joined by ., an index as [i], and the empty path as the root's name.

iex> Macaw.Layers.Fault.format_path([:marks, 0, :channels])
"marks[0].channels"
iex> Macaw.Layers.Fault.format_path([])
"document"

sort(faults)

@spec sort([t()]) :: [t()]

Faults ordered by path, keeping the given order of faults at one path.