A document's syntax tree laid out the way Dextrin.Text.Formatter
lays out a value -- the top-level collection over lines, one entry per
line, indented; a nested one on one line when that line fits the width
(:width, 80) -- with every comment kept beside the entry it belongs
to (design/comment-retention.md, "The rules"). A nested collection
holding a comment, or a blank line between its entries, is laid out
over lines whatever its width: the comment needs its line, and the
blank line is the author's grouping.
Layout only. Every token is written exactly as it was -- a literal's spelling, a key's form, an escape -- and only the space between tokens changes: indentation, line breaks, commas, and blank lines, of which at most one is kept wherever the source had any between entries. A document with no comments therefore comes out as the pretty printer writes its value.
Where a comment goes, by lines alone: a comment on the line of the
token or entry before it trails that, and so does every comment line
straight after it, aligned under its #; any other block of comment
lines goes above the next entry, or at the end of its collection when
none follows. A comment between a key or a tag and its value stays
between them, and the value moves to the next line.
Summary
Functions
The text of the document tree, laid out. :indent is the spaces per
level (2), :width the columns a nested collection's one line must fit
in (80).
Functions
@spec format(Ichor.Syntax.Node.t(), keyword()) :: String.t()
The text of the document tree, laid out. :indent is the spaces per
level (2), :width the columns a nested collection's one line must fit
in (80).
It ends with a newline exactly when the source did: a formatter run on
save keeps a file's last newline, and a comment-free document without
one comes out exactly as Dextrin.encode(value, pretty: true) writes
its value.