`fmt`

ilusm code formatter - tokenise source into typed tokens, reconstruct with consistent indentation and operator spacing, format a source string or file in place, check whether a file is already formatted, compute a line diff of changes, lint for style issues (line length, trailing whitespace, tabs, excess blank lines), and sort use imports alphabetically.

Load with: use fmt

What this module does

fmt is ilusm's built-in code formatter, analogous to gofmt or prettier. It works in two passes: first a tokeniser (fmtto) breaks the source into a flat list of typed tokens (newlines, comments, strings, numbers, identifiers, keywords, and operators), then the formatter (fmtfo) reconstructs indented source lines by tracking brace depth and applying spacing rules.

Key formatting rules: spaces around binary operators, spaces after commas, configurable indent string (default 4 spaces), 100-character soft line limit, and a trailing newline. The linter checks for rule violations without modifying the file.

Quick example

use fmt

# Format a source string
src = "x=1+2\nif x>0:\n  prn(x)"
formatted = fmt(src, nil)  # uses default config

# Format a file in place
fmtfi("src/app.ilu", nil)

# Check if a file is already formatted
r = fmtch("src/app.ilu", nil)
prn(r.ok)   # tru if already clean
prn(r.diff) # list of {line, original, formatted} if not

# Lint for style issues
issues = fmtli(src)
# [{line, severity:"warning"/"error", message}, ...]

# Sort use imports
clean = fmtso(src)

Functions

Configuration

fmtcf(indent, max_line_len, trailing_newline)

Creates a formatter config object. indent is the indent string (e.g. " "), max_line_len is the soft column limit (integer), trailing_newline is a boolean. Also sets space_around_ops: tru, space_after_comma: tru, and blank_lines_between_fns: 1.

fmtde()

Returns the default config: 4-space indent, 100-character max line length, trailing newline enabled.

Formatting

fmt(source, config)

Formats an ilusm source string. If config is nil, uses the default config. Tokenises the source, reconstructs indented lines, and returns the formatted string. Appends a trailing newline if configured.

fmtfi(path, config)

Reads the file at path, formats it, and writes the result back in place.

fmtso(source)

Sorts use imports alphabetically. Collects all leading use declarations, sorts them, and prepends the sorted block before the rest of the file. Returns the reordered source string.

Checking and diffing

fmtch(path, config)

Checks whether a file is already correctly formatted. Returns {ok: tru} if unchanged, or {ok: fls, diff: [...]} where diff is a list of {line, original, formatted} records for each differing line. Useful in CI to enforce formatting.

fmtdi(original, formatted)

Computes a line-by-line diff between two strings. Returns a list of {line, original, formatted} records for all lines that differ.

Linting

fmtli(source)

Lints a source string for style issues. Returns a list of issue records {line, severity, message}. Checks for:

Lines exceeding 100 characters (warning)
Trailing whitespace (warning)
More than 2 consecutive blank lines (warning)
Tabs used for indentation instead of spaces (error)

Notes

The formatter uses a token-based approach - it does not parse a full AST, so complex multi-line expressions may not be perfectly indented in all cases.
Requires trl, txt, and fs.