Registration rules¤
Registration raises rather than overwriting, so a spec cannot change meaning
without someone editing it. Each function takes replace=True to overwrite
deliberately.
All three registries are process-wide and shared by every package in the interpreter.
Summary¤
| Condition | register_axis |
register_alias |
register_markup |
|---|---|---|---|
| Name already registered | raises | raises | raises |
| Name is already a keyword | — | raises | raises |
| Name is already an alias | raises (keyword) | raises | raises |
Name contains - |
raises | raises | raises |
| Second claim on free text | raises | — | — |
| Row missing a required key | — | — | raises |
| Keyword already claimed by another axis | accepted | — | — |
Every refusal is a ValueError, raised before any registry is touched — a
rejected registration leaves the grammar exactly as it was.
Axes¤
A duplicate axis name is refused:
>>> from wadler_lindig_parts import Axis, register_axis, unregister_axis
>>> def probe(name, word):
... return Axis(name=name, keywords={word: True}, default=None,
... layouts={"product": lambda v: {name: v}})
>>> _ = register_axis(probe("probe_a", "wa"))
>>> try:
... register_axis(probe("probe_a", "wb"))
... except ValueError as e:
... print(e)
axis 'probe_a' is already registered
A keyword that is already an alias is refused:
>>> from wadler_lindig_parts import register_alias, unregister_alias
>>> register_alias("al", "html-mul")
>>> try:
... register_axis(probe("probe_b", "al"))
... except ValueError as e:
... print(e)
keyword 'al' is already an alias
For why this one is a refusal while two axes sharing a keyword is not, see Why keywords share one namespace.
Only one axis may claim the spec's trailing free-text run. value already
does:
>>> try:
... register_axis(Axis(name="probe_c", keywords={"wc": True}, default=None,
... layouts={"product": lambda v: {}}, free_text=("product",)))
... except ValueError as e:
... print(e)
axis 'probe_c' claims free text, but 'value' already does; a spec has only one trailing run to give
Aliases¤
An alias maps a name to a whole spec string. The name is refused if it is taken, in either direction:
>>> try:
... register_alias("al", "text")
... except ValueError as e:
... print(e)
alias 'al' is already registered as 'html-mul'
>>> try:
... register_alias("wa", "text")
... except ValueError as e:
... print(e)
alias 'wa' is already a keyword of axis 'probe_a'
The restriction is on the name only. An alias's expansion is a whole spec and therefore contains separators — that is what an alias is for.
Markup rows¤
A markup name also becomes a keyword on the markup axis, so it is subject to
the keyword rules:
>>> from wadler_lindig_parts import MARKUPS, register_markup, unregister_markup
>>> try:
... register_markup("html", MARKUPS["text"])
... except ValueError as e:
... print(e)
markup 'html' is already registered
>>> try:
... register_markup("wa", MARKUPS["text"])
... except ValueError as e:
... print(e)
'wa' is already a keyword or alias
All four keys in
REQUIRED_MARKUP_KEYS must be present. A row missing one is
refused at registration, not when something is first rendered:
>>> try:
... register_markup("broken", {"_content": "{}", "wrap": "{}"})
... except ValueError as e:
... print(e)
markup row is missing required keys ['vsep', 'escape']
Reserved characters¤
No registered name may contain -. The rule applies to axis names, keywords,
alias names and markup names alike:
>>> try:
... register_alias("a-b", "text")
... except ValueError as e:
... print(str(e).split(":")[0])
alias 'a-b' may not contain '-'
Use _ inside a name that needs two words. For why the character is
unusable rather than merely discouraged, see
Why the spec grammar scans left to right.
Keyword collisions¤
Two axes claiming one keyword is the single case that does not raise at registration. Both succeed, and the registry records both claimants:
>>> _ = register_axis(probe("probe_e", "shared"))
>>> _ = register_axis(probe("probe_f", "shared"))
The refusal lands when a spec uses the word bare, and names both claimants and both escapes:
>>> from wadler_lindig_parts import parse_spec
>>> try:
... parse_spec("shared")
... except ValueError as e:
... print(str(e).split(". Expected")[0])
invalid format spec 'shared': ambiguous keyword 'shared'; claimed by 'probe_e', 'probe_f'. Write it as one of: probe_e=shared, probe_f=shared
Each qualified form keeps working:
>>> parse_spec("probe_e=shared")["probe_e"]
True
>>> parse_spec("probe_f=shared")["probe_f"]
True
For why this case is permitted rather than refused, see Why keywords share one namespace.
>>> for name in ["probe_f", "probe_e", "probe_a"]:
... unregister_axis(name)
>>> unregister_alias("al")
See also¤
- Axes, layouts and markups — what is in the registries.
- Format spec grammar — how registered names are written in a spec.
- How to add an axis · How to add a markup