# fson

**FSON** is a human-friendly superset of JSON — and, since v0.9.0.0, a
pragmatic superset of [JSON5](https://json5.org/) too — and `fson` is its
C++ library: parse, query, modify and rewrite FSON files **without losing
a single comment**.

```
// service configuration
{
  database: {
    host: "db.internal.example", // production endpoint
    --user: "root", /* disabled credential, kept for reference */
    "connection timeout": 2.50,
  },
  retries: [1, 2, 5,],
  --debug: false
}
```

## What FSON adds to JSON

- **Comments** — `// line` and nestable `/* block */` comments, anywhere.
- **Bare keys** — `host:` instead of `"host":` for identifier-like names.
- **Disabled members** — prefix any member with `--` to switch it off:
  queries treat it as absent, yet it is preserved and written back intact.
- **JSON5 features** — single-quoted strings, trailing commas, hex/
  `Infinity`/`-Infinity`/`NaN` numbers, and extended whitespace are all
  accepted; the document root may be any value, not just an object.
- Everything else is plain JSON: same values, same strings, same numbers.

Every valid JSON document is already a valid FSON document, and so is
almost every JSON5 document — see `docs/notation.md`, "FSON and JSON5",
for the two narrow, deliberate exceptions.

## What the library guarantees

- **Lossless round-trips.** Comments (with their positions), member order,
  quoted-vs-bare key form, `--` markers and the exact spelling of numbers
  (`1.50` stays `1.50`) all survive a load–modify–save cycle. Output is
  consistently pretty-printed.
- **Robust parsing.** Errors are collected with file/line/column and
  parsing continues at the next safe point, so one typo does not hide the
  rest of the file. Nothing throws on bad input.
- **A practical API.** Dotted-path access with typed getters
  (`doc.getInteger("database.port", 5432)`, `"servers[0].port"`), a full
  document object model underneath, and a one-line façade:

```cpp
#include "fson/Fson.hh"
using namespace fedem::fson;

auto result = Fson::load( "config.json" );
if( result.ok( ) )
{
  long long port = result.document->getInteger( "database.port", 5432 );
  result.document->setPath( "database.host",
                            std::make_unique< String >( "db1" ) );
  Fson::save( *result.document, "config.json" );
}
```

## fson-check

The bundled CLI tool validates and reformats FSON files:

```sh
fson-check config.json                 # report errors, pretty-print to stdout
fson-check -i config.json              # reformat in place (only when error-free)
fson-check --output out.json in.json   # write the result elsewhere
fson-check --json config.json          # convert to plain JSON (for jq, etc.)
fson-check --json5 config.json         # convert to JSON5 (keeps comments and bare keys)
fson-check --bare config.json          # unquote keys where the grammar allows
```

## Building

```sh
git clone <repository-url> fson
cd fson
cmake -B build && cmake --build build
ctest --test-dir build      # optional, needs GoogleTest
cmake --install build
```

Requires CMake ≥ 3.20 and a C++23 compiler (GCC 12+). The installed
public API is C++17-compatible. `cparse` (the parsing core) is a Conan
package — resolve it with `conan install .` first, or make it available
to CMake yourself. See [docs/integration.md](docs/integration.md).

Released source archives (`.tar.gz` / `.zip` + `.sha256`) are on
<https://fson.fedem.eu/downloads>.

## Documentation

| Document | Content |
|---|---|
| [docs/notation.md](docs/notation.md) | the FSON file format, with railroad diagrams in [docs/notation/](docs/notation/) |
| [docs/getting_started.md](docs/getting_started.md) | load → query → modify → save tutorial |
| [docs/reference_manual.md](docs/reference_manual.md) | every class and function |
| [docs/integration.md](docs/integration.md) | adding fson to your build (pkg-config, CMake, packages) |
| generated API | Doxygen tree — `cmake --build build --target docs` (needs Doxygen; `dot` adds the graphs), published at <https://fson.fedem.eu/api> |
| [examples/](examples/) | annotated sample FSON files |

## Repository layout

```
apps/fson-check/        command-line validator / formatter
docs/                   documentation; docs/notation/ holds the grammar
examples/               sample FSON files
libs/internal/sdk/fson/ the fson library
tests/                  GoogleTest suites
```

The parsing core `cparse` is a separate Conan package
(`cparse/[>=1.0 <2]`), not a vendored tree.

## License

MIT — Copyright © Fehmi Demiralp (FEDEM). See [`LICENSE`](LICENSE). The
name **FSON** and the FEDEM branding are not covered by the code licence —
see [`TRADEMARKS.md`](TRADEMARKS.md).

Homepage: https://fson.fedem.eu