Formatting
Sun ships with a built-in source formatter, available as the fmt subcommand
of the sun binary. It enforces one canonical style — there are no
configuration options.
sun fmt file.sun other.sun # rewrite files in place
sun fmt . # format every .sun file in the tree
sun fmt --check . # exit 1 if any file would change (for CI)Directory arguments are searched recursively for .sun files; hidden
directories (.git, .cache, …) are skipped. Paths that are not .sun files
are ignored, and files that fail to parse are reported and left untouched
(exit code 2).
Ignoring files
Use sun_fmt.ignore in sun-config.json to exclude generated code, dependencies,
or other files from formatting:
{
"root": true,
"sun_fmt": {
"ignore": ["/build/", "/third_party/", "/tmp/"]
}
}Patterns are relative to the config file's directory. Ancestor configurations
apply first, nearer configurations apply last, and "root": true stops the
upward search. Within an array, the last matching rule wins. An absent setting
or empty array adds no exclusions and does not clear inherited rules.
Patterns use gitignore-style matching:
/build/matches the directory at the config root;build/matches directories with that name at any depth. A trailing/restricts a pattern to directories.*.generated.sunmatches filenames at any depth.*and?do not cross/; character classes such as[ab]are supported.src/**/generated.sunmatches zero or more intermediate directories.build/**excludes the contents ofbuild, leaving the directory itself open.!keep.sunre-includes a matching file. Files inside an excluded directory stay excluded unless the directory is also re-included. For example, use["/build/**", "!/build/keep.sun"]to keep one file selected.- A leading
#marks a comment entry. Backslashes escape pattern characters; write two backslashes in JSON. Spaces in a pattern are literal.
The same rules apply to sun fmt, sun fmt --check, and explicitly named files
or directories, even when running from a subdirectory. Explicit ignored inputs
are reported as skipped. Excluded directories are not traversed. .gitignore
is not read.
Use sun fmt --no-ignore path to bypass configured exclusions. This does not
change the existing hidden-directory and .inja.sun template exclusions during
directory scans. These settings control file selection for the command; they do
not change formatting style or the editor's single-document formatting request.
Style
- 2-space indentation, K&R braces (
function f() i32 {). - One statement per line; a single space around binary operators.
- Comments are preserved: own-line comments keep their position, trailing
comments stay on their line (two spaces before
//). - Blank lines between statements are preserved, collapsed to at most one.
- Non-empty modules have one blank line after the opening brace, before any
leading comments. Empty modules remain
{}. - A group of
usingdeclarations is separated from a following function, class, interface, enum, or module by a blank line before its documentation comments. - Adjacent function, class, interface, enum, and module declarations are separated by a blank line, placed before any leading documentation comments. Methods, constructors, and destructors are also separated from each other and from fields. Consecutive fields stay together.
- Bracketed lists (call arguments, array literals) stay on one line if they were written on one line; multi-line lists get one element per line.
- Parentheses are never added or removed.
- Literals keep their exact source spelling (float forms, string escapes).
// before
function main()i32{
var x:i32=40;
x+=2; // bump
return x;}
// after
function main() i32 {
var x: i32 = 40;
x += 2; // bump
return x;
}Editor integration
The language server (sun-lsp) implements textDocument/formatting, so
"Format Document" and format-on-save work in any LSP-enabled editor. Code
that does not parse is left unchanged.