Module djot_escape 

Turn arbitrary plain text into Djot that renders it back verbatim.

The inverse of djot_to_plain_text, and the counterpart it had been missing. The Djot exporter has always needed this — it cannot write a paragraph containing * without the re-parse reading emphasis that the writer never typed — but the two halves lived privately inside export_djot_uc, so anything else holding plain text destined to become Djot had to reinvent them.

That reinvention is the failure this module exists to prevent. A host app promoting a stored plain-text field to a Djot one (a comment body, say) has to escape the values already on disk, and a second, slightly-different escaper would disagree with the exporter about exactly the awkward strings — a paragraph opening - , a title with [brackets], prose about snake_case — while agreeing on everything easy enough to notice in review.

Two levels, because Djot has two:

• escape_djot_inline neutralises the characters that can start inline markup anywhere in a line.
• guard_djot_block_start neutralises the markers that mean something only at the start of a line — a leading # is a heading, a leading - a list item, and no amount of inline escaping reaches them.

plain_text_to_djot composes both over every line, which is what a caller converting a whole stored string wants.

Functions

djot_round_trip_is_lossy

Whether converting s to Djot and reading it back would lose text.

escape_djot_inline

Backslash-escape every character that can trigger Djot inline markup, so arbitrary text survives a re-parse verbatim.

guard_djot_block_start

Neutralise a line’s leading characters so they are not parsed as a block-construct marker.

needs_djot_escaping

Whether plain_text_to_djot would rewrite s at all.

plain_text_to_djot

Convert a whole plain-text string into Djot that parses back to exactly that text.