← Index

x/tool/fmt

Comment-preserving s-expression formatter on the Fmt class.

Formatting logic is %-private (the mutually-recursive printers call each other directly); the Fmt class is the API.

Class Fmt

Comment-preserving, data-driven pretty printer for x-lang s-expressions.

Build a formatter table from construct declarations with (Fmt build-table …), then (Fmt tokens toks table) prints them. A form under 60 chars wide prints as-is; wider ones indent per the table’s fmt property (head-1 / head-kw / body / default).

(Fmt build-table constructs)

Build a formatter lookup table from construct declarations.

Parameters:

• constructs : LIST — Construct declarations (from XEON)

Returns: ALIST — Lookup table mapping names to property lists

Examples:

(Fmt build-table '((def (fmt . head-1)))) => (("def" ('fmt . 'head-1)))

(Fmt lookup name table)

Look up formatting properties for a construct name.

Parameters:

• name : SYMBOL — Form name to look up
• table : ALIST — Table from (Fmt build-table)

Returns: LIST — Property list, or nil

Examples:

(Fmt lookup 'def (Fmt build-table '((def (fmt . head-1))))) => (('fmt . 'head-1))
(null? (Fmt lookup 'when (Fmt build-table '((def (fmt . head-1)))))) => #t

(Fmt get-prop key props)

Get a specific property from a construct property list.

Parameters:

• key : SYMBOL — Property key
• props : LIST — Property list from (Fmt lookup)

Returns: ANY — Property value, or nil

Examples:

(Fmt get-prop 'fmt '((fmt . body))) => 'body

(Fmt comment? tok)

Test whether a token is a comment token.

Parameters:

• tok : ANY — Token to test

Returns: BOOL — True if tok is a (%comment …) token

Examples:

(Fmt comment? (list '%comment "; note")) => #t
(Fmt comment? '(def x 1)) => #f

(Fmt width form)

Estimate the display width of a form in CODE POINTS (via write-to-str; a comment counts as 80). Code points approximate display columns except for double-width/combining glyphs (wcwidth is a known gap).

Parameters:

• form : ANY — Form to measure

Returns: INTEGER — Estimated width in code points

Examples:

(Fmt width '(def x 1)) => 11

(Fmt expr form col)

Format any expression, writing the result to output.

Parameters:

• form : ANY — Expression to format
• col : INTEGER — Current indentation column

Returns: ANY — nil (output via display)

Examples:

(Fmt expr '(def x 'y) 0) => (def x 'y)

(Fmt list form col table)

Format a list form with indentation-aware pretty printing, writing the result.

Parameters:

• form : LIST — List form to format
• col : INTEGER — Current indentation column
• table : ALIST — Formatter table

Returns: ANY — nil (output via display)

Examples:

(Fmt list '(def x 1) 0 ()) => (def x 1)

(Fmt body forms col)

Format a sequence of body forms, one per line, writing the result.

Parameters:

• forms : LIST — Body forms
• col : INTEGER — Current indentation column

Returns: ANY — nil (output via display)

Examples:

(Fmt body '((a 1)) 0) => (a 1)

(Fmt tokens tokens table)

Format a list of top-level tokens with the given construct table, writing the result.

Parameters:

• tokens : LIST — Token list from the tokenizer
• table : ALIST — Formatter table from (Fmt build-table)

Returns: ANY — nil (output via display)

Examples:

(Fmt tokens '((def x 1)) ()) => (def x 1)

(Fmt fold-sugar! on)

Set whether (lit x) / (quasi x) / (unquote x) fold to ‘ ` , sugar in output. ON is the docs/syntax.md ruling for post-boot code; a driver formatting a BOOT-CONSTRAINED file (its text loads before the quote reader arms) must turn it OFF or the output cannot boot (#307).

Parameters:

• on : BOOL — Fold lit/quasi/unquote forms to reader sugar?

Returns: ANY — nil