Theia-Modula-2/extensions/modula2-language/FORMATTING.md

Modula-2 formatting

Format Document (Shift+Alt+F) normalises a whole file through the language server (textDocument/formatting), and Format Selection does the same for the selected lines (textDocument/rangeFormatting). Every rule below is settable under modula2.format.* in Settings; changes apply live, no reload.

What the formatter does

• Indentation from block structure (BEGIN/IF/CASE/LOOP/ RECORD/…END), using indentSize spaces or tabs.
• Keyword case (upper, the default, or preserve).
• Spacing: operators, commas, colons, .. ranges.
• Blank lines collapsed to emptyLineLimit; trailing whitespace trimmed; file ends with exactly one newline (all settable).

Line structure is deliberately preserved: statements are never joined or split, so formatting a file you didn't write can't scramble its layout. Comments are preserved verbatim (only repositioned). Formatting is idempotent and token-exact: running it twice changes nothing, and it never adds, removes or renames code — verified across real-world sources, whose formatted output still compiles with gm2.

Settings

Setting	Default	Effect
modula2.format.indentSize	2	Spaces per level (0–8; unused with tabs).
modula2.format.useTabs	false	Indent with tabs.
modula2.format.keywordCase	"upper"	"upper" uppercases reserved words, "preserve" leaves case alone. There is intentionally no "lower": lowercase keywords do not compile with gm2.
modula2.format.spaceAroundOperators	true	a := b, x + y. Off gives compact a:=b, x+y.
modula2.format.spaceAfterComma	true	a, b vs a,b.
modula2.format.spaceBeforeColon	false	x: INTEGER vs x : INTEGER.
modula2.format.spaceAroundRange	true	[0 .. 9] vs [0..9].
modula2.format.emptyLineLimit	1	Max consecutive blank lines (0–10).
modula2.format.trimTrailingWhitespace	true	Strip trailing spaces.
modula2.format.insertFinalNewline	true	Exactly one newline at end of file.

Notes

• keywordCase covers reserved words only. Predefined identifiers (INTEGER, TRUE, NIL, …) can legally be redeclared, so they are never retouched — same as the typing-time auto-uppercasing.
• Identifiers that merely look like keywords (mod, In, Type are all real identifiers in the wild and accepted by gm2) are resolved first and left alone. Unresolvable ones follow the keyword rule, matching the editor's auto-uppercasing.
• CLIENT tab/indent settings (editor.tabSize) do not drive Modula-2 formatting; modula2.format.* always wins.
• Format Selection formats whole lines intersecting the selection, using full-document context (indentation levels depend on preceding lines) while leaving everything outside the selection byte-identical — including collapsing surplus blank lines and the final newline when the selection reaches end of file. With an empty selection, the cursor line is formatted.