Extension of the org & html writers is made possible by creating circular
references between the extending and extended writer - that way the extending
writer can forward all methods it doesn't implement to the extended writer and the
extended writer can use the extending writer as the root for method calls to
make sure methods overridden in the extending writer are used even for nested
method calls.
This circular reference leads to problems when cloning writers - cloning the
extended writer merely copies the pointer to the extending writer - i.e. the
extending writer does not get cloned with an updated reference to the extended
writer. Thus method calls to the extending writer act as if no cloning took
place and things break.
The easiest solution is to just get rid of cloning. We could also clone the
ExtendingWriter and replace it's reference to the extended writer with the just
cloned one but that's harder so we just remove it.
As there are a lot of "extending writer" and "extended writer" in the above
paragraphs and I'm too lazy to write up something better here's another attempt
at a TLDR:
Cloning is broken as ExtendingWriter is a reference to a writer that has
a reference to the writer we are cloning - that writer would have to have it's
reference updated but that's hard. So we solve it it by not cloning at all.
Go does not support inheritance, just composition. While composition with type
embedding (i.e. forwarding method calls to the embedded type) can replace
inheritance for most use cases this is not one of them. We really want to
overwrite methods so that method calls from inside the base writer also use the
custom methods ouf our extending writer - naive embedding does not work here
as the this in this.WriteText refers to the embedded type rather than the outer
extending type (see open recursion).
A simple solution is to make a reference of the extending type
available from the extended type and use that for nested method calls. We'll go
with that one as it does not require huge code changes. Another solution would
be to flatten the writing process and not use nested method calls - this is
what blackfriday does. Assuming the current solution works I feel it's cleaner
and keeps the ugliness of simulating inheritance with composition contained to
a small portion of the code while blackfridays approach requires all write
methods to be written in a flat style (i.e. not do nested calls to write by
being called twice with entering / leaving). The current solution becomes ugly
if we want to do multiple levels of extending but i don't expect that to be a
valid use case - if it turns out to be one we can always adapt to it
later. YAGNI.
TIL embedded types can be acessed by their non-namespaced name - so there
actually is no need for a type alias to access .strings.Builder, one can just
use .Builder.
The existing approach made it hard to extend existing writers.
With this change, replacing individual methods of a writer is possible by
embedding it.
Sharing the WriteNodes function also removes some unnecesseray duplication, so
win win.
