fson-check reads an FSON file, reports every diagnostic on stderr, and then acts according to the options.
Synopsis
fson-check [options] <file_name>
With no option it writes the pretty-printed document to stdout, even when the parse was only partial — so you always see what parsed.
Output options
| Option | Effect |
|---|---|
| (none) | pretty-print to stdout, partial documents included |
-i, --in-place | rewrite <file_name> — only when no errors were found (warnings tolerated). Cannot be combined with --json / --json5. |
-o, --output <file> | write the result to <file> — again only when error-free. |
-i and --output are mutually exclusive.
Conversion options
| Option | Effect |
|---|---|
--json | strict, fully JSON-compliant output: comments removed, every key quoted, hex → decimal. Infinity / -Infinity / NaN cannot be represented → reported as a write failure (exit 2). Cannot combine with --json5, --bare, or -i. |
--json5 | JSON5-compliant output: comments kept (nested blocks flattened to one // line per source line), bare keys stay bare, number lexemes verbatim. Cannot combine with --json or -i. |
--keep | with --json / --json5: keep -- disabled members as ordinary members, dropping only the prefix. Cannot combine with --drop-disabled. |
--drop-disabled | with --json / --json5: drop -- disabled members entirely. Default for --json; for --json5 the default is instead to turn them into a comment. Cannot combine with --keep. |
--bare | write quoted keys without quotes wherever the name satisfies the bare-name grammar. Cannot combine with --json (JSON keys are always quoted); --json5 supports it. |
-h, --help | show help and exit. |
Write-back modes (-i, -o) write only when nothing worse than a warning was recorded — warnings are lossless, so the output is still faithful.
Exit status
| Code | Meaning |
|---|---|
0 | parsed with nothing worse than warnings |
1 | parse errors found |
2 | usage error or I/O failure |
Diagnostics
Always on stderr, one per line:
config.fson:7:3: syntax error: expected ':' after key
config.fson:12:1: warning: leading zero in number '007'
Severities: syntax error, type error, error, internal error, warning.
Worked examples
# validate and eyeball the canonical form
fson-check config.fson
# reformat in place (no-op if it does not parse cleanly)
fson-check -i config.fson
# canonical form to a different file
fson-check --output config.pretty.fson config.fson
# feed a config to jq
fson-check --json config.fson | jq '.database.host'
# ... keeping the disabled members as real data for the pipeline
fson-check --json --keep config.fson | jq 'keys'
# migrate an FSON file to JSON5, unquoting keys where allowed
fson-check --json5 --bare config.fson --output config.json5
# CI gate: fail the build on any parse error
fson-check config.fson >/dev/null || exit 1
Try it on the files in the Examples gallery — they all parse clean.
Keeping it in sync
The tool's USAGE string (in apps/fson-check/FsonCheck.cpp), the Bash completion, and the Zsh completion are three artefacts that must move together whenever a flag is added, removed, or renamed — see Shell completion.
