radFormatter / docs / cli

radFormatter CLI

A non-destructive Delphi source code formatter.

radFormatter tokenizes your source, builds a full Concrete Syntax Tree, and runs an owned-decision pipeline that assigns spacing, line breaks, indentation, and alignment — then renders the result without ever losing or altering a token beyond whitespace and casing.

Key features

Non-destructive. Every format is validated with a non-whitespace content hash and a re-lexed token fingerprint. If anything beyond whitespace or casing would change, the output is discarded and your original source is returned untouched.

CST-aware. Indentation, case structure, generic parameters, and nested control flow are driven by real parse data, not line heuristics.

72 configuration options across nine sections (casing, spacing, indent, line breaks, reshaping, alignment, output, conditional, input). Commit one radFormatter.json and every developer and CI job formats identically. See the configuration options reference.

Built-in profiles. Start from Default, FormatterExe (RAD Studio formatter compatibility), Embarcadero, or NoOp, then override.

CI-ready. -check reports files that need formatting and exits 1 when any do; -diff shows the unified diff of what would change.

Supported file types

.pas.dpr.dpk.dpkw.inc

Usage

radFormatter <file|pattern> [<file|pattern> ...] [-b] [-profile <name>] [-config <file>]
radFormatter -d <directory> [-r] [-b] [-profile <name>] [-config <file>]
radFormatter <file|pattern> [...] -check [-profile <name>] [-config <file>]
radFormatter <file|pattern> [...] -diff  [-profile <name>] [-config <file>]
radFormatter -writeDefaultConfig <file>

Running with no arguments prints usage (exit 2). An unrecognized -/-- token is a usage error (Error: unknown option "...", exit 2) — a mistyped flag is never silently treated as a filename.

Options

Grouped to match the radFormatter --help sections.

General

Actions (default: format in place)

Files are formatted in place by default (single file, multiple files, or -d); use -check or -diff to inspect changes without modifying files.

Input and scope

Supported extensions: *.pas, *.dpr, *.dpk, *.dpkw, *.inc. Wildcards (*, ?) are supported in file arguments.

Configuration

Parse errors

Conditional compilation / build context

These flags apply only to activeBranch mode; allBranches and preserveConditionals ignore the build context.

Source encoding

Output and safety rules

• Format in place (default): every successful run rewrites the source file(s) directly — a single file, multiple files, and -d/-d -r all format in place with no flag required. Use -b to keep a .bak backup.
• Inspect without modifying: use -check (report which files need formatting; exit code 1 if any) or -diff (print a unified diff). Both are read-only and never write.
• -check and -diff are mutually exclusive.
• Files radFormatter cannot format are their own category: one that cannot be parsed into a compilation unit (an incomplete unit, or {$IFDEF} branches that cannot be resolved without a build context) or a detected non-Delphi dialect (Free Pascal {$mode} with unsupported constructs) is left unformatted and reported to stderr — never silently counted as “already formatted”, and never rewritten best-effort. -onParseError skip (default) warns and continues (exit unaffected); -onParseError fail treats it as an error (exit 1). Under -check/-diff it is listed as skipped (could not parse) or skipped (unsupported dialect), distinct from “would format” and from “no change.”
• The reason is specific where the parser can tell: when it is due to an unrecognized language element, the message names the construct and its location and points at the right fix — “looks like an FPC/other-dialect source” (radFormatter targets Delphi) versus “if this is valid newer Delphi, update radFormatter” (the message includes the bundled parser version) — rather than the generic missing-build-context hint.
• Auto config: when -config is not given, radFormatter looks for a radFormatter.json next to the executable and uses it if present.
• End-of-run summary: a multi-file run prints one trailing tally line, e.g. Summary: 42 formatted, 3 skipped, 1 error (46 files) (-check/-diff say would format). It is additive and does not affect the exit code. A single-file run prints no summary (its one progress line already says everything). For -diff the summary is written to stderr so stdout stays a clean patch stream; the other modes print it to stdout with their per-file progress.

Source encoding

radFormatter reads and rewrites your files, so it is deliberately the strictest reader: it only formats a file whose encoding it can determine with confidence, and it never guesses. A wrong guess would re-encode identifiers to different bytes and write mojibake back to disk.

By default it reads known-encoding-only: a UTF-8/UTF-16 BOM, pure ASCII, BOM-less UTF-16, or valid (BOM-less) UTF-8. Anything else — typically a BOM-less legacy code page (CP1252, CP1251, Shift-JIS, ...) — is skipped with exit code 4 and left byte-for-byte unchanged, rather than mis-decoded. Writes always round-trip the file's original encoding and BOM state; radFormatter never transcodes (there is deliberately no output-encoding option).

To process a legacy tree, declare its encoding:

> radFormatter --assume-encoding cp1252 -d legacy-src -r

--assume-encoding utf8 is the explicit form of the default assumption. For a mixed CJK tree, add a strict fallback ladder (a file that is ambiguous under two or more pages fails rather than being guessed):

> radFormatter --assume-encoding utf8 -fallback 932,936,949,950 -d src -r

-fallback requires --assume-encoding. radFormatter evaluates any fallback strictly and never applies a silent Western (CP1252) catch-all — a single-byte legacy tree is named explicitly with --assume-encoding cp1252, not rescued by a fallback. (Because a writer's fallback is always strict, there is no separate strict-fallback flag.)

These flags follow the shared radProgrammer source-encoding grammar, so the same syntax works across the tool suite. Every one is also settable in radFormatter.json under an input section (assumeEncoding / fallback / heuristic) — the committed, per-directory way to declare a tree's encoding, so a mixed monorepo can give each project its own code page. A CLI flag overrides the config value.

Examples

Format a single file in place using the Default profile:

> radFormatter source/MyUnit.pas

Format a whole tree in place:

> radFormatter -d source -r

Format matching files in place, with backups:

> radFormatter -d source -r -b *.pas

Check formatting in CI without modifying files:

> radFormatter -check -config radFormatter.json -d source -r

Show what would change:

> radFormatter -diff -config radFormatter.json source/MyUnit.pas

Format a tree, excluding generated and vendored code:

> radFormatter -d source -r -exclude "generated;vendor;*.g.pas" *.pas

Use a profile with project overrides:

> radFormatter -profile Embarcadero -config team.json source/MyUnit.pas

Generate a starter configuration:

> radFormatter -writeDefaultConfig radFormatter.json

Configuration

All formatting behavior is set through a JSON config overlaid on the chosen profile. Generate a fully populated default with -writeDefaultConfig and edit to taste. The sections are:

See the configuration options reference for the full option reference, value types, defaults, and a complete example.

Per-directory config (radFormatter.json)

When you format a directory tree with -d, radFormatter also looks for a radFormatter.json in each folder it walks. A config found in a folder applies to that folder and every subfolder beneath it, on top of your -profile + -config + command-line settings. A radFormatter.json deeper in the tree overlays one higher up, so each project (or subtree) can carry its own settings — most usefully its own conditional include search path.

• Overwrite, not append. A per-directory config replaces the setting it names (an includePaths array replaces the inherited list; it does not add to it), so a subtree can never inherit a wrong include path. For its subtree a directory includePaths also overrides a command-line -includePath.
• Relative paths in a radFormatter.json (like ./Source) resolve against that file's own folder.
• Bounded to the -d tree. Discovery does not look above the directory you pass to -d. (Formatting a single file does not search parent folders.)
• Invalid config (bad JSON or an unsupported schema) is reported as a warning and skipped — the enclosing configuration stays in effect and the run continues.

Profiles

Omitting -profile uses Default. A -config file is overlaid on the profile, so you only specify the keys you want to change. See Profiles for a side-by-side comparison with before/after examples.

Exit codes

A run reports the most significant code it reached (4 over 3 over 1); any non-zero code fails a CI gate.

Safety guarantees

Content-hash validation — a whitespace-excluded hash of the source is compared before and after formatting; any mismatch discards the change.

Token fingerprinting — the output is re-lexed and its token fingerprint compared to the original; a mismatch discards the change.

Graceful failure — when validation fails, the original source is returned unchanged. No data loss.

Backups — -b writes a .bak copy before overwriting.

Integration

Pre-commit hook

#!/bin/sh
radFormatter -check -config radFormatter.json -d source -r

GitHub Actions

- name: Check formatting
  run: radFormatter -check -config radFormatter.json -d source -r

Team workflow

Commit radFormatter.json to your repository. Every developer and CI job uses the same configuration — formatting disputes are settled once, in the config file.

CLI reference as of radFormatter v2.7.986 (Alpha) — see release notes