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

Fragments and stacking (spec/02): the fragment-type behavior, and the operations over
fragments of a type.

A **fragment** is a document of a type, or any part of one: a map with the type's keys,
not necessarily all of them and not validated. A document type that stacks implements
this behavior, declaring what visualize read from its chart schema: how each key
combines (`c:key/2`), which elements a layer replaces in place (`c:identity/2`), the kinds
its fragments can be (`c:kinds/0`, `c:wrapper/1`) and where each kind lands in a whole
document (`c:place/3`). The machinery holds no type's vocabulary, so every type combines
the same way:

- `compose/3`, the union, reports a name two fragments declare differently (§3.1);
- `stack/2`, the cascade, takes the higher layer's word (§3.2);
- `explain/2` says which layer set every value of a stack (§6.3);
- `kind/2`, `refs/2` and `relocate/3` read a fragment's kind and ids (§6.1, §6.2);
- `encode_value/2` and `decode_value/3` write and read variables, ids and use sites in
  the type's forms (§9).

**A struct is a leaf of every walk** (visualize D-92): a `%Macaw.Layers.Var{}` stands for
a value rather than being one. Only `refs/2` and `relocate/3` read a struct's parts, a
`%Macaw.Layers.Use{}`'s, by name.

Ported from visualize's `Visualize.Chart.Compose`, `Stack` and `Fragment`.

# `id`

```elixir
@type id() :: {kind(), pos_integer()}
```

An id a store issued: `{kind, n}`.

# `kind`

```elixir
@type kind() :: atom()
```

A node kind of a document type.

# `layer`

```elixir
@type layer() :: map() | {term(), map()}
```

A layer of a stack: a fragment, or a `{name, fragment}` pair.

# `rule`

```elixir
@type rule() :: :concat | :union | :deep | :override | {:type, atom()}
```

How a key combines (spec/02 §2).

# `spec`

```elixir
@type spec() :: %{merge: rule(), node: kind() | nil, element: kind() | nil}
```

A key's spec: its rule, the node kind of a node-valued key, and the node kind of a
list's or a name map's elements.

# `bind_holes`
*optional* 

```elixir
@callback bind_holes(kind(), term(), term(), map()) :: term()
```

That value with its holes substituted, written back in the type's syntax.

# `decompose`
*optional* 

```elixir
@callback decompose(map()) :: [Macaw.Layers.Use.t()]
```

A whole document as inline sites, one kind each.

# `holes`
*optional* 

```elixir
@callback holes(kind(), term(), term()) :: [Macaw.Layers.Var.t()]
```

The variables a value of the type's own syntax holds (a text's holes).

# `identity`
*optional* 

```elixir
@callback identity(kind(), map()) :: term()
```

The identity of an element of a `:concat` list of `kind` elements, or `nil`.

# `inline`
*optional* 

```elixir
@callback inline(map(), (id() -> {:ok, map()} | :error)) :: {map(), [{id(), list()}]}
```

Every id left at a reference site of a flattened document resolved through `fetch`.

# `key`

```elixir
@callback key(kind(), term()) :: spec() | nil
```

How a key of a node of `kind` combines, or `nil` for a key the type does not know.

# `kinds`

```elixir
@callback kinds() :: [kind()]
```

Every kind a fragment of the type can be, and so every kind an id can carry.

# `merge`
*optional* 

```elixir
@callback merge(atom(), term(), term()) :: term()
```

The type's own merge of a key whose rule is `{:type, name}`.

# `place`

```elixir
@callback place(kind(), map(), String.t() | nil) :: {:ok, map()} | :keyless
```

Where a composite site of `kind` lands in a whole document (spec/02 §8.2).

# `root`

```elixir
@callback root() :: kind()
```

The node kind of a whole document of the type.

# `wrapper`

```elixir
@callback wrapper(term()) :: kind() | nil
```

The kind a singular wrapper key names (`style:` → `:style`), or `nil`.

# `compose`

```elixir
@spec compose(module(), [map()]) ::
  {:ok, map()} | {:error, [Macaw.Layers.Fault.t(), ...]}
```

The left fold of `compose/3`; `compose(type, [])` is `{:ok, %{}}`.

# `compose`

```elixir
@spec compose(module(), map(), map()) ::
  {:ok, map()} | {:error, [Macaw.Layers.Fault.t(), ...]}
```

`b` over `a` by every key's rule (spec/02 §3.1): `{:ok, fragment}`, or `{:error, faults}`
with every `:conflict` at its path, ordered by path.

# `decode_value`

```elixir
@spec decode_value(module(), String.t(), term()) :: {:ok, term()} | :default
```

The value of one of this file's tags, its payload already read (spec/02 §9), for a
type's `decode_value/2` to call: `{:ok, value}`, or `:default` for a tag or payload it
does not read, which the reader refuses at its path. An id's kind is matched against the
type's kinds by its string, so no atom is made from a document.

# `encode_value`

```elixir
@spec encode_value(module(), term()) :: {:ok, term()} | :default
```

The map form of this file's terms (spec/02 §9), for a type's `encode_value/1` to call:
a variable as `{"$var": name}`, an id as `{"$id": [kind, n]}`, a use site as
`{"$use": {…}}`, its parts in the type's own map form; `:default` for any other term.

# `explain`

```elixir
@spec explain(module(), [layer()]) :: [map()]
```

One entry per leaf path of `stack/2` of `layers` (spec/02 §6.3), ordered by path:
`%{path, value, layer, overrode}`, `layer` the layer's name or its zero-based position.
It recomputes the stack by the cascade's own walk, so it cannot drift from it.

# `kind`

```elixir
@spec kind(module(), map()) :: kind() | nil
```

The kind of a fragment, derived (spec/02 §6.1): walking down while exactly one key is
set, the last kind reached. A singular wrapper is the kind it names, a name map or list
holding one entry the entry's kind, a composite `:composite`. `nil` for a fragment that
branches at the top, which is no kind of fragment, and for one that reaches no kind
below the root.

# `refs`

```elixir
@spec refs(module(), term()) :: [id()]
```

Every id a fragment refers to, once each, sorted (spec/02 §6.2): a `{kind, n}` of the
type's `c:kinds/0` with `n` a positive integer, wherever it stands, a use site's `ref`,
`origin`, `local` and `vars` included. Sorted, since the order a map is walked is the
runtime's.

# `relocate`

```elixir
@spec relocate(module(), term(), %{required(id()) => id()}) :: {term(), [id()]}
```

The fragment with every id rewritten through `table`, `%{old => new}`, and the ids the
table did not carry, sorted (spec/02 §6.2). A use site's ids are rewritten in place, the
site still a `%Use{}`; an id not in the table is left, to resolve as a mask.

# `stack`

```elixir
@spec stack(module(), [layer()]) :: map()
```

The left fold of `stack/3`, the later layer the higher: `stack(type, [])` is `%{}` and
`stack(type, [a])` is `a`. A layer may be a `{name, fragment}` pair, whose name is
ignored here and reported by `explain/2`.

# `stack`

```elixir
@spec stack(module(), map(), map()) :: map()
```

The cascade of `higher` over `lower` (spec/02 §3.2): for every key the higher layer
wins. It cannot fail, so it answers the fragment itself.

---

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