Since writers are normally only used synchronously (i.e. to write one document
at a time), we don't guard modifications to their internal
state (e.g. temporarily replacing the string.Builder in WriteNodesAsString)
against race conditions.
The package global `orgWriter` and corresponding use cases of it (`org.String`,
`$node.String`) break that pattern - the writer is potentially used from
multiple go routines at the same time. This results in race conditions that
manifest as error messages like e.g.
could not write output: runtime error: invalid memory address or nil pointer dereference. Using unrendered content.
Additionally, since we catch panics in `Document.Write`, the corresponding
stack trace is lost and dependents of go-org never know what hit them.
As using a writer across simultaneously across go routines is not a standard
pattern, we'll sync the use of the global `orgWriter` instead of trying to make
the actual writer threadsafe; less code noise for the common use case.
To support code block directives like :exports none we need context - i.e. we
need to have the block and it's results at once and can't just render them
independently.
WriteNodesAsString is simple enough to implement but exposing it is helpful in
the implementation of extending writers and we don't aim to keep writer a small
interface so let's expose it.
Being able to very easily get the original [1] Org mode content seems like
something that will come up quite often and is very little code.
[1] it's not really the original content, but rather the pretty printed version
of that - as the semantics don't change it shouldn't matter.
- enable logging by default: debug was a bad name - it's error logging that I
just want to hide in tests
- don't panic (all the time)
- use a logger. this allows us to add more information - like the path of the
parsed file!
Org mode separates kvs not as initially assumed by whitespace (~ csv) but
rather at keywords (~ :\w+).
This is still not replicating Org mode behaviour though as I decided against
attributes ignoring multi-definitions. Instead we stack their
values (and those existing on the element) for certain attributes (class, style
for now).
e.g.
[[foo]]
would become <foo class="a"> in Org mode but becomes <foo class="a b"> with
go-org.
While adding another test case from the goorgeous issues it became clear that
inline markup and html entity replacement were erronously applied to raw text
elements like inline code =foo=, src/example/export blocks, example lines,
etc.
To correctly handle those cases in both org and html exports a new
parseRawInline method had to be added.
Also some misc html export whitespace fixes and stuff
including org files is more complex - e.g. footnotes need to be namespaced to
their source file. org does this by prefixing each included files footnotes
with a number - but even that is not enough as it doesn't guarantee
uniqueness.
As I don't have a usecase for it, I'll avoid the additional complexity for
now.
until now buffersettings were always appended using \n which means the first
value would already be written as "\nVALUE". Not anymore.
Also we finally add an option to parse just the front matter. Still not
efficient as we tokenize the whole org file but i don't think saving a few
milliseconds would be worth making the code uglier.
