# `Tempo.Explain`
[🔗](https://github.com/kipcole9/tempo/blob/v0.5.0/lib/explain.ex#L39)

Plain-English explanations of Tempo values, in a form renderers
can style.

`Tempo.Explain.explain/1` returns a `t:Tempo.Explanation.t/0`
with semantic part tags. Three formatters produce output for
different surfaces:

* `to_string/1` — plain multi-line text. Default for iex.
* `to_ansi/1` — ANSI-coloured for terminals.
* `to_iodata/1` — tagged iodata for HTML or visualizer renderers.

`Tempo.explain/1` delegates here with a `to_string/1` formatter —
the most common case for interactive use.

## Example

    iex> Tempo.Explain.explain(~o"156X").kind
    :masked_year

    iex> Tempo.Explain.explain(~o"156X").parts
    ...> |> Enum.map(&elem(&1, 0))
    [:headline, :span, :enumeration, :hint]

# `explain`

```elixir
@spec explain(term()) :: Tempo.Explanation.t()
```

Return a structured `t:Tempo.Explanation.t/0` for any Tempo
value. Unknown shapes produce a generic fallback rather than
raising.

# `to_ansi`

```elixir
@spec to_ansi(Tempo.Explanation.t()) :: String.t()
```

Render an explanation with ANSI colour codes, suitable for a
terminal that supports them.

The colour mapping is deliberate: headlines are bright, spans
are cyan (technical detail), qualifications and metadata are
yellow (notable), hints are dim.

# `to_iodata`

```elixir
@spec to_iodata(Tempo.Explanation.t()) :: [{atom(), String.t()}]
```

Render as tagged iodata `[{tag, text}, ...]`, ready for an HTML
or visualizer renderer to style each part by its tag.

Each element is a 2-tuple; no string concatenation happens here.
Callers decide how to separate parts (newlines, `<div>`s, etc.).

# `to_string`

```elixir
@spec to_string(Tempo.Explanation.t()) :: String.t()
```

Render an explanation as plain multi-line text.

### Examples

    iex> Tempo.Explain.explain(~o"2022Y") |> Tempo.Explain.to_string()
    "The year 2022.\nSpan: [2022-01-01, 2023-01-01).\nIterates at :month granularity.\nMaterialise as an interval with `Tempo.to_interval/1`."

---

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