How to add an axis¤
Registering an axis adds a word to the format-spec vocabulary, so a spec can ask your library for something the package has no concept of.
Teach the grammar a new word walks through one end to end if you would rather see it built up.
Register the axis¤
An Axis is a name, the keywords that set it, a default, and — per layout —
how its value becomes a renderer argument.
>>> from wadler_lindig_parts import (
... Axis, parse_spec, register_axis, unregister_axis,
... )
>>> _ = register_axis(Axis(
... name="vector_form",
... keywords={"vecform": True},
... default=False,
... layouts={"call": lambda v: {"vector_form": v}},
... ))
>>> parse_spec("call-vecform")["vector_form"]
True
The layouts mapping is what scopes the axis. An axis is only legal under the
layouts it declares, and naming it elsewhere is an error rather than a silent
no-op:
>>> try:
... parse_spec("product-vecform")
... except ValueError as e:
... print(str(e).split(". Expected")[0])
invalid format spec 'product-vecform': 'vector_form' does not apply to 'product' layout
Register it at import, once¤
The registry is process-wide. Register your axes when your package is
imported, not lazily — a __repr_spec__ naming your axis is parsed at class
creation, so the axis must exist before those classes are defined.
Unregister only in tests:
>>> unregister_axis("vector_form")
If you want shorthand for a combination¤
Register an alias. Its name is a single token; its expansion is a whole spec.
>>> from wadler_lindig_parts import register_alias, unregister_alias
>>> register_alias("terse", "call-type")
>>> parse_spec("terse") == parse_spec("call-type")
True
>>> unregister_alias("terse")
The engine ships no aliases at all, so every alias in a running process came from a consumer.
If another library might want your keyword¤
Keywords share one flat namespace. Two axes may claim one word — both
registrations succeed, and the bare word then raises while axis=word keeps
working for each claimant.
If you expect to share vocabulary, write the qualified form from the start and a collision can never affect you:
>>> _ = register_axis(Axis(
... name="vector_form", keywords={"vecform": True}, default=False,
... layouts={"call": lambda v: {"vector_form": v}},
... ))
>>> parse_spec("call-vector_form=vecform")["vector_form"]
True
>>> unregister_axis("vector_form")
Names may not contain -; use _ for a two-word name. For the full set of
constraints see Registration rules.
See also¤
- How to add a markup — add an output format instead.
- Axes, layouts and markups — the six that ship.
- API —
Axis,register_axis,register_alias.