Module readable 

Readable, indented Links Notation representation.

This module implements the default output of crate::encode: a plain-text, indented projection where keys and values are written as they are, so the file can be read, grepped and reviewed without decoding anything.

Shape

One construct — ( ) — is used for both objects and arrays, at every level including the root. What distinguishes them is the content of the lines: key value pairs make an object, bare values make an array.

(
  type "RouterState"
  server (
    host "127.0.0.1"
    port 18878
  )
  models (
    "claude-haiku"
    "claude-opus"
  )
)

Value mapping

LinoValue	Readable form
Object	( ) with one key value pair per line
Array	( ) with one value per line
String	quoted, never encoded
Int / Float / Bool / Null	bare, so the type survives the round trip

Empty containers keep their type: an empty array is () on one line, while an empty object is written as ( and ) on two lines.

Text is written as text. A string keeps every character a reader would grep for, including newlines and tabs, and is quoted with a run of delimiters — """say "hi"""" — when it holds the delimiter itself. Only the characters a form cannot carry are escaped, and only they: the value is then written as (escaped "…"), where %XX stands for one escaped byte. The indented form escapes the carriage return, which CRLF normalisation would otherwise rewrite, and the other control characters; the single-line form escapes the newline as well, because there a record ends at the end of the line. Nothing else is encoded: base64 lives in crate::encode_compact, which a caller asks for by name.

Single-line form

encode_line writes the same document on one line, so one record is one line and an append-only log stays greppable, tailable and countable by wc -l. Rows can no longer be told apart by line breaks there, so an object names itself with the o link id the notation already has, and its pairs are written as their own links:

(o: (type "RouterState") (server (o: (host "127.0.0.1") (port 18878))) (models ("claude-haiku" "claude-opus")))

Value	Single-line form
Object	(o: (key value) …)
empty Object	(o:)
Array	(value …)
empty Array	()
scalars	exactly as in the indented form

The marker is what answers the ambiguity a flat layout otherwise has: without it ((key value)) reads both as the one-pair object and as the array holding the two-element array, and an empty key makes it worse. With it, a bare ( ) is always an array and a marked one is always an object, so every value — empty key included — survives the round trip. Consequently a hand-written one-line link such as (a 1) is the two-element array, not the one-pair object: on one line, objects say so.

Constants

BASE64_MARKER

Marker of a base64 payload. Written by crate::encode_compact and by versions up to 0.6.0 of the readable form, which is why it is still read.

DEFAULT_INDENT

Default indentation used by encode.

ESCAPED_MARKER

Marker of a string whose unwritable characters are percent-escaped.

OBJECT_MARKER

Link id naming an object in the single-line form, written as (o: …).

Functions

decode

Decode the readable, indented Links Notation form back into a value.

decode_line

Decode the readable, single-line Links Notation form back into a value.

encode

Encode a value into the readable, indented Links Notation form.

encode_line

Encode a value into the readable, single-line Links Notation form.