format
format::Format `crates/pseudoscript-format`. The canonical formatter: parse, then pretty-print the tree to one canonical form. The string-to-string entry the CLI and LSP depend on.
Parent
Inbound
- call cli::FmtCmd · format
Outbound
- from → cli::Result
- call → format::Formatter · format
Scenarios
Formatting the output again changes nothing.
- given a parseable .pds source
- when it is formatted and the result is formatted a second time
- then the first pass yields canonical text
- and the second pass returns that text unchanged
Reformatting only touches layout, never meaning.
- given a parseable .pds source
- when it is formatted
- then the result re-parses to a structurally equivalent tree
- but only whitespace and comment layout differ from the source
format::FormatError Why formatting failed. The only failure is unparseable input: `Parse` carries the rendered error messages (one per diagnostic) for context, and the caller keeps its original text.
format::Formatter Drives the headline flow: parse the source, short-circuit to `FormatError::Parse` if any error diagnostic surfaced, else hand the tree to the printer for canonical text.
Parent
- for format::Format
Inbound
- call format::Format · format
Outbound
- call → syntax::Syntax · parse
- from → format::string
- call → format::Printer · print
- call → format::Printer · print
Scenarios
Unparseable source short-circuits and is left untouched.
- given source with at least one error-severity parse diagnostic
- when it is formatted
- then formatting returns FormatError::Parse carrying the rendered messages
- but the source is not rewritten and the caller keeps the original text
Warnings and info never block formatting.
- given source that parses with only warning or info diagnostics
- when it is formatted
- then the tree is pretty-printed to canonical text
- but the non-error diagnostics do not short-circuit the formatter
format::Parse format::Printer The canonical pretty-printer: walks the AST top-down, appending to a buffer, and emits one canonical form. Indentation is a level counter (two spaces each); leading trivia is normalised — blank-line runs collapse to at most one separator and `//` / `/* */` comments reproduce at the current indent in source order. Internals are black-boxed per construct; the top-level `print` flow is disclosed.
Parent
- for format::Format
Inbound
- call format::Formatter · print
- call format::Formatter · print
Outbound
- from → format::string
- from → format::PrinterState
- from → format::string
Scenarios
Records render on one line.
- given a data record declaration
- when it is printed
- then the fields render inline as { a: T, b: U }
- and an empty record renders as { }
Unions stack one variant per line.
- given a data union declaration
- when it is printed
- then the body opens with ` =` on the declaration line
- and each variant prints as `| Name` on its own line, indented one level
Features render one step per line.
- given a feature declaration with given/when/then steps
- when it is printed
- then each step prints on its own line, keyword then prose
- but the keywords are not column-aligned, keeping the form idempotent
Indentation is two spaces per nesting level.
- given a disclosed node, block, union, or feature body
- when its members are printed
- then each nesting level adds two spaces of indentation
Comments and blank-line runs survive; runs collapse to one.
- given source interleaving declarations with comments and runs of blank lines
- when it is printed
- then each comment reproduces on its own line at the current indent
- and a run of blank lines collapses to a single blank separator
- but the first member in a block or file gets no leading blank line
Black-box and disclosed forms are each kept, never converted.
- given a mix of black-box `;` and disclosed `{ }` nodes and callables
- when they are printed
- then a black-box body stays `;`
- and a disclosed body keeps its `{ }`, one member per line
- but an empty disclosed body renders ` { }`
format::PrinterState The running pretty-printer state: the text buffer being built, the current nesting depth (two spaces each), and whether the current line has had its indentation written yet so further writes append in place.
Inbound
- from format::Printer