Skip to content

Axes, layouts and markups¤

An axis is one independent choice a format spec can make. Every axis arrives through register_axis, including the six below — there is no privileged set, and an axis a consumer adds is read out of a spec exactly like a built-in one.

>>> from wadler_lindig_parts import AXES, ALIASES, MARKUPS

>>> sorted(AXES)
['indent', 'layout', 'markup', 'sep', 'value', 'width']
>>> sorted(MARKUPS)
['html', 'latex', 'text']

Summary¤

Axis Default Keywords Applies to Controls
layout product call, product both whether to show what the value is or how to rebuild it
markup text text, html, latex product which output format
sep bare mul, bare product the separator between a value and its label
value values array, values, type, or a format spec both how verbose an array-like payload is, and how a payload is formatted
width None (none — width=<n> only) both the column at which layout breaks lines
indent None (none — indent=<n> only) both the indent for a broken line

markup and sep apply under product only. Naming either under call is an error — see Layout scoping.

layout¤

Default: product. Keywords: call, product. Applies to: both.

product renders what a value is, from its pparts fragments. call renders how to rebuild it, by handing off to the object's own __pdoc__.

>>> from wadler_lindig_parts import pspec
>>> from wadler_lindig_parts.examples import Point, Term

>>> pspec(Term(2.0, "x"), "mul")
'2.0 * x'
>>> pspec(Point(1.0, 2.0), "call")
'Point(x=1.0, y=2.0)'

Point registers no pparts and still renders under call: wadler_lindig supplies a __pdoc__ for any dataclass.

markup¤

Default: text. Keywords: one per registered markup. Applies to: product.

Selects the markup row used to wrap fragments. Adding a markup adds its name as a keyword.

>>> from wadler_lindig_parts.examples import Version

>>> f"{Version(2, 1):text}"
'2.1'
>>> f"{Version(2, 1):html}"
'<span>2</span>.<span>1</span>'
>>> f"{Version(2, 1):latex}"
'$2.1$'

sep¤

Default: bare. Keywords: mul, bare. Applies to: product.

Chooses the separator a markup places between a payload and its label. Fragments a type marks kind="sep" are its own and are left alone.

>>> pspec(Term(2.0, "x"), "bare")
'2.0 x'
>>> pspec(Term(2.0, "x"), "mul")
'2.0 * x'

value¤

Default: values. Keywords: array, values, type, or any Python format spec. Applies to: both; free text under product only.

The axis reaches the renderer as two arguments to pvalue: the three keywords select short_arrays, and a format spec becomes value_spec.

A format spec is applied to the payload as a whole, via format():

>>> pspec(Term(2.0, "x"), ".3f")
'2.000 x'
>>> pspec(Term(2.0, "x"), ".1e")
'2.0e+00 x'

It is therefore only meaningful for a payload format() accepts. The default pvalue passes a list straight to format(), which refuses it:

>>> try:
...     pspec(Term([1.0, 2.0, 3.0], "x"), ".3f")
... except TypeError as e:
...     print(e)
unsupported format string passed to list.__format__

pvalue is itself a dispatch point, so a library holding array types registers its own method and decides what a spec means for them.

The three keywords map to wadler_lindig's short_arrays argument. They affect array-like payloads; a plain Python list renders the same under all three.

>>> from wadler_lindig_parts import SHORT_ARRAYS
>>> SHORT_ARRAYS
{'array': False, 'values': 'compact', 'type': True}

>>> pspec(Term([1.0, 2.0, 3.0], "x"), "values")
'[1.0, 2.0, 3.0] x'

width¤

Default: None. Keywords: none; written width=<n>. Applies to: both.

The column at which the document breaks lines. Layout is wadler_lindig's, so breaking and indentation come from the document rather than from this package.

>>> from wadler_lindig_parts import doc_to_str, parts_to_doc, pparts

>>> parts = pparts(Term([1.0, 2.0, 3.0], "metres"))
>>> print(doc_to_str(parts_to_doc(parts), 60))
[1.0, 2.0, 3.0] * metres
>>> print(doc_to_str(parts_to_doc(parts), 20))
[1.0, 2.0, 3.0] *
  metres

A payload is atomic: a width narrower than the payload cannot break it further.

>>> doc_to_str(parts_to_doc(parts), 12) == doc_to_str(parts_to_doc(parts), 20)
True

FLAT is the sentinel width meaning "never break".

>>> from wadler_lindig_parts import FLAT
>>> FLAT
1000000000

indent¤

Default: None. Keywords: none; written indent=<n>. Applies to: both.

The indent applied to a continuation line after a break.

>>> from wadler_lindig_parts import parse_spec
>>> parse_spec("indent=4")["indent"]
4

Markups¤

A markup is a row of strings describing how to wrap fragments. Three ship.

Key Required Meaning
_content yes wraps a content fragment
wrap yes wraps the whole rendered value
vsep yes separator between stacked values
escape yes callable applied to text, or None
bare, mul, … no the separator for each sep keyword
>>> from wadler_lindig_parts import REQUIRED_MARKUP_KEYS, markup_table

>>> REQUIRED_MARKUP_KEYS
('_content', 'wrap', 'vsep', 'escape')

>>> markup_table("html")["_content"]
'<span>{}</span>'
>>> markup_table("latex")["wrap"]
'${}$'

A row missing a required key is refused at registration — see Registration rules.

Registries¤

Three mappings hold the grammar. All are read-only views; they change only through the register/unregister functions.

Registry Holds Ships with
AXES axis name → Axis the six above
MARKUPS markup name → row text, html, latex
ALIASES alias name → spec string nothing

ALIASES is empty by design: the engine ships no shorthand at all, so every alias in existence was registered by a consumer.

>>> len(ALIASES)
0

See also¤