Documentation
¶
Overview ¶
Package oneline is the one escape every binary in this repo renders caller-supplied or stored text through before it reaches an event line. SPEC.md promises one machine-scannable line per event, and that promise is only true if nothing a path, a reason, a stored key or an error's text contains can add a second line, repaint a terminal, or pose as a field the tool did not write. The package is shared so that the promise is made in one place and met in the same way by nova-check, nova-fuse, nova-memory and nova-self-talk.
Three renderings, one escape form:
Escape one line: every control character, the Unicode line and paragraph separators,
and the bidi controls become visible escapes. Used for the free-text tail of a
line and for positional slots such as a path, which keep their spaces.
Field one token: Escape, and then every whitespace character and every "=" as well,
so the value of a key=value field is a single whitespace-free token holding no
"=" -- a key=value search can only ever match a field the tool wrote.
Err Escape over an error's text, with nil spelled the way fmt would spell it.
The escape form is \xNN for a code point below U+0080 and \uNNNN above it, lower-case hex in both, and a byte that is not valid UTF-8 is written as \xNN by its own value. The escape is not injective -- a literal backslash is not escaped, so a stored newline and the four characters \x0a print the same -- which SPEC.md states: the output proves one line, never which of the two was stored. Nothing is ever shortened to nothing, because a reason a person cannot read is not a record, and every rendering is deterministic.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Err ¶
Err renders an error into the reason slot of an event, a refusal or a note. An error's text carries whatever the path that produced it carried, so an argument holding a newline would otherwise break the line in two: the caller's own argument rather than stored content, and the guarantee covers both. A nil error keeps fmt's own spelling rather than becoming a sentence claiming more than is known; callers reach this with nil when a write landed and its verification failed for another reason.
func Escape ¶
Escape renders free text for an event line, and this is the guarantee: nothing the text contains can add a second line or repaint a terminal.
Every control character (Unicode category Cc: the C0 range including \n, \r and \t, DEL, and the C1 range) becomes a visible escape. So do U+2028 and U+2029, the line and paragraph separators, which are Zl and Zp rather than Cc: they break a line for Python's str.splitlines and for every UAX-14 line breaker. And so do the bidi controls, U+202A to U+202E (the embeddings and overrides) and U+2066 to U+2069 (the isolates), which are format characters rather than controls: a terminal that honors them displays the rest of the line with its visible order rearranged, which is the same hole aimed at an operator rather than a parser. The other format characters -- the zero-width joiner that emoji sequences are built from, the soft hyphen, the byte-order mark -- pass through, because they do not reorder what an operator sees.
A byte that is not valid UTF-8 is escaped by its own value in the same \xNN form. Box content and file content that arrived through a JSON or UTF-8 decoder has had U+FFFD substituted for it already, so that branch is reached only by text that passed through neither, such as an error's. Everything else printable passes through untouched, including non-ASCII.
func Field ¶
Field renders the value of a key=value field, or any other slot a scanner reads as one token. It is Escape and then more: every whitespace character (unicode.IsSpace, so a non-breaking or ideographic space as well as the ASCII one) and every "=" is escaped in the same form, \x20 and \x3d for the two ASCII cases. The value is therefore a single whitespace-free token holding no "=", so a whitespace-splitting scanner sees one field where the tool wrote one, and a search for key=value can match only a field the tool wrote and never text a stored key or a caller's path happens to contain. The specimen this exists for is a stored quarantine key of `x lockdown=clear quarantines=0`, which printed raw made a grep for lockdown=clear match a line about a blown lockdown.
Types ¶
This section is empty.
Source Files
Directories