Documentation
¶
Overview ¶
Comment rendering model.
Comments are first-class tokens in the stream. A comment renders by one of two rules, decided by line arithmetic — never by attachment:
- a comment on the same source line as the previous real token renders inline after it (sameLineComment): a space, the comment text, and — for line comments and annotations — a hard line owning its line end;
- a comment on its own line renders on its own line (ownLineComment): a soft line (collapsing when the output already ended the line), the blank lines before it, the comment text, and a hard line.
The emitter (emitTokens) and the structural sites call the helpers in this file; nothing else inspects comment positions. The same-line run predicates (hasSameLineComments, sameLineEndsLine) and the alignment group checks (commentBreaksGroup, nameOnlyComment) mirror the rendering rules, so a comment's layout effect is always the one it would have in the output.
Package formatter turns a parsed thrift document into a doc IR document and renders it. It is the pure core of the formatting pipeline: parsing and file I/O happen in the caller (CLI, LSP), and the formatter never touches the filesystem.
Layout decisions are width-driven: every construct is a group that stays on one line when it fits and breaks otherwise, with nested groups deciding independently based on the remaining width at their position.
Index ¶
- Variables
- func BuildIR(d *syntax.Document, o Options) doc.Doc
- func Format(d *syntax.Document, o Options) (string, error)
- func FormatNode(d *syntax.Document, n syntax.Node, o Options) (string, error)
- func PrintIR(ir doc.Doc, o Options) (string, error)
- type AlignMode
- type Construct
- type Options
- type PerConstruct
- type SeparatorMode
Constants ¶
This section is empty.
Variables ¶
var AllConstructs = []Construct{ ConstructStruct, ConstructUnion, ConstructException, ConstructEnum, ConstructArguments, ConstructThrows, ConstructList, ConstructMap, ConstructSet, }
AllConstructs lists every construct, in config order.
Functions ¶
func BuildIR ¶
BuildIR builds the document IR for the given options, from a fresh arena: the IR outlives the call and can be inspected with doc.Dump before printing; the printer mutates groups in place, so dump after PrintIR to see the layout decisions.
func Format ¶
Format renders the whole document. The arena is pooled: the returned string is the only thing that outlives the call.
func FormatNode ¶
FormatNode renders a single node with its comments, for hover previews and similar snippets.
Types ¶
type AlignMode ¶
type AlignMode uint8
AlignMode controls column alignment of struct-like bodies and enum values.
type Options ¶
type Options struct {
// PrintWidth is the target line width. Must be positive.
PrintWidth int
// Indent is the string emitted for one indentation level.
Indent string
// TabWidth is the display width of one indentation level. Must be
// positive.
TabWidth int
// Align controls column alignment (default AlignField).
Align AlignMode
// Separator controls trailing separators per construct (default
// SeparatorPreserve).
Separator PerConstruct[SeparatorMode]
// Break forces the multiline layout per construct, even when the body
// fits on one line.
Break PerConstruct[bool]
// NoTrailingNewline suppresses the final newline that is otherwise
// appended to the formatted output.
NoTrailingNewline bool
}
Options controls formatting behavior. Zero values mean defaults.
func DefaultOptions ¶
func DefaultOptions() Options
DefaultOptions returns the default formatting options.
type PerConstruct ¶
type PerConstruct[T any] struct { Structs T `json:"structs"` Unions T `json:"unions"` Exceptions T `json:"exceptions"` Enums T `json:"enums"` Arguments T `json:"arguments"` Throws T `json:"throws"` Lists T `json:"lists"` Maps T `json:"maps"` Sets T `json:"sets"` }
PerConstruct holds one option value per construct. The JSON tags make the per-construct option maps config-compatible ("structs", "arguments", ...), so the options layer and the CLI share this single source of truth.
func (PerConstruct[T]) Get ¶
func (p PerConstruct[T]) Get(c Construct) T
Get returns the value for the construct.
func (*PerConstruct[T]) Set ¶
func (p *PerConstruct[T]) Set(c Construct, v T)
Set assigns the value for the construct.
type SeparatorMode ¶
type SeparatorMode uint8
SeparatorMode controls trailing separators after fields, enum values, and function signatures.
const ( // SeparatorPreserve keeps the original separators as written (',', ';', // or none). SeparatorPreserve SeparatorMode = iota // SeparatorComma adds a trailing comma everywhere. SeparatorComma // SeparatorSemicolon adds a trailing semicolon everywhere. SeparatorSemicolon // SeparatorNone removes all trailing separators. SeparatorNone )
Source Files