Dextrin.Document.Formatter (Dextrin v0.3.3)

Copy Markdown View Source

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

format(tree, opts \\ [])

@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.