Plain-English explanations of Tempo values, in a form renderers can style.
Tempo.Explain.explain/1 returns a 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]Summary
Functions
Return a structured Tempo.Explanation.t/0 for any Tempo
value. Unknown shapes produce a generic fallback rather than
raising.
Render an explanation with ANSI colour codes, suitable for a terminal that supports them.
Render as tagged iodata [{tag, text}, ...], ready for an HTML
or visualizer renderer to style each part by its tag.
Render an explanation as plain multi-line text.
Functions
@spec explain(term()) :: Tempo.Explanation.t()
Return a structured Tempo.Explanation.t/0 for any Tempo
value. Unknown shapes produce a generic fallback rather than
raising.
@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.
@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.).
@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`."