# `Macaw.Layers.Fault`
[🔗](https://github.com/dcoai/macaw_layers/blob/v0.2.2/lib/macaw/layers/fault.ex#L1)

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.

# `option`

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

`format/2`'s options.

# `path`

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

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

# `t`

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

A fault: where, and why.

# `format`

```elixir
@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`

```elixir
@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`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*