Skip to content

Teach the grammar a new word¤

In the last tutorial we built a Duration that prints as 3:07. In this one we will teach the format-spec grammar a word it has never heard — total — so that f"{d:total}" prints 187s, and so that f"{d:html-total}" works the moment total exists, without our writing anything for it.

Start by pasting in the type from last time:

>>> import dataclasses
>>> from wadler_lindig_parts import PPart, pparts, pspec

>>> @dataclasses.dataclass
... class Duration:
...     minutes: int
...     seconds: int
...
...     def __repr__(self) -> str:
...         return pspec(self, "bare")
...
...     def __format__(self, spec: str, /) -> str:
...         return pspec(self, spec)

Step 1: teach the type the new behaviour¤

First the behaviour, then the word. Our pparts takes a total keyword and returns different fragments when it is set:

>>> @pparts.dispatch
... def _(obj: Duration, /, *, markup="text", total=False, **kw):
...     if total:
...         return (
...             PPart("total", str(obj.minutes * 60 + obj.seconds)),
...             PPart("unit", "s", "sep"),
...         )
...     return (
...         PPart("minutes", str(obj.minutes)),
...         PPart("colon", ":", "sep"),
...         PPart("seconds", f"{obj.seconds:02d}"),
...     )

>>> d = Duration(3, 7)
>>> d
3:07

Step 2: watch the word do nothing¤

The behaviour exists, but nothing can ask for it yet. Try the spec anyway:

>>> f"{d:total}"
'3:07'

Nothing happened — and notice that nothing complained either. Let's see what the engine made of our word:

>>> from wadler_lindig_parts import parse_spec
>>> parse_spec("total")["value"]
'total'

It did not recognise total as a keyword, so it fell through to the last thing a spec can be: a format spec for the values inside. It landed on the value axis, where our plain-text fragments ignore it. An unregistered word is not an error; it is just a word nothing is listening for.

Step 3: register the word¤

Now we make it mean something. An Axis is a word, a default, and how its value reaches the renderer:

>>> from wadler_lindig_parts import Axis, register_axis

>>> _ = register_axis(Axis(
...     name="total_seconds",
...     keywords={"total": True},
...     default=False,
...     layouts={"product": lambda v: {"total": v}},
... ))

That says: the word total sets this axis to True; when unset it is False; and under product layout its value is handed to the renderer as total=... — which is exactly the keyword our pparts is waiting for.

Ask again:

>>> f"{d:total}"
'187s'

Three minutes and seven seconds is 187 seconds. The word is now part of the grammar.

Step 4: the part we did not write¤

We taught the grammar one word. We said nothing about HTML, and nothing about LaTeX — but both now accept it:

>>> f"{d:html-total}"
'<span>187</span>s'
>>> f"{d:latex-total}"
'$187s$'

Both work. The word we added combines with markups that already existed, and with any markup registered after it.

Notice that s did not get a <span> in the HTML — we marked it "sep" in step 1, and the markup treats separators differently from content, just as it did with the colon.

The order of the words does not matter either:

>>> parse_spec("html-total") == parse_spec("total-html")
True

And the plain form still behaves:

>>> f"{d}"
'3:07'

Step 5: put the registry back¤

One last thing. The registry is process-wide: total is now a word for every piece of code in this session, not just for our Duration. A library would want exactly that. A tutorial should hand the session back as it found it:

>>> from wadler_lindig_parts import unregister_axis, AXES

>>> unregister_axis("total_seconds")
>>> sorted(AXES)
['indent', 'layout', 'markup', 'sep', 'value', 'width']

Back to the six the engine ships with. And total is just text again:

>>> f"{d:total}"
'3:07'

What we built¤

A format spec the package had never heard of, which worked with every markup it already had — from one Axis and one extra branch in pparts.

We unregistered it only because this was a shared session. A real library registers its axes once, when it is imported, and leaves them there.