This guide walks through the typical lifecycle of an FSON file with the fson library: load, inspect, modify, save — losing nothing. Every type is in namespace fedem::fson. Build instructions are on the Install page; the file format itself is the Notation section; the full API is the Reference Manual.

Suppose config.fson contains:

// service configuration
{
  database: {
    host: "localhost", // dev default
    port: 5432
  },
  retries: [1, 2, 5],
  --debug: true
}

Load a file

#include <iostream>
#include "fson/Fson.hh"

using namespace fedem::fson;

int main()
{
  Fson::LoadResult result = Fson::load( "config.fson" );

  for( auto const& error : result.errors )
    std::cerr << error.filename << ':' << error.line << ':' << error.col
              << ": " << error.message << '\n';

  if( !result.ok() )        // ok() tolerates warnings, not errors
    return 1;

  Document& document = *result.document;
  // ...
}

Fson::load() never throws. The returned document is null only when the file could not be opened; parse errors still produce a partial document plus the error list, so you can report precisely what is wrong and still work with what parsed. See Fson::load and LoadResult.

Read a value

The quickest way is the dotted-path API with typed getters; the second argument is the fallback for a missing path or a type mismatch:

std::string host = document.getString ( "database.host", "localhost" );
long long   port = document.getInteger( "database.port", 5432 );
long long   r0   = document.getInteger( "retries[0]", 0 );   // array element
bool        dbg  = document.getBoolean( "debug", false );    // false — disabled!

The last line matters: --debug is a disabled member, so the query API treats it as absent — exactly what the -- prefix is for. More on reading in Querying.

Modify and save

#include "fson/Number.hh"
#include "fson/String.hh"

document.setPath( "database.host", std::make_unique<String>( "db1" ) );
document.setPath( "database.pool.size", std::make_unique<Number>( 8LL ) );
document.removePath( "retries[1]" );

Fson::save( document, "config.fson" );

The writer pretty-prints and writes back everything the parser captured: comments in all positions, member order, quoted-vs-bare key form, -- markers, and numbers exactly as written. More in Modifying & Saving.

Where next

Task	Page
dotted paths, typed getters, walking the model	Querying
setPath / removePath / disable, the writer, round-trip rules	Modifying & Saving
%include merge / alias, provenance	Include Files
--json / --json5 conversion	Converting to JSON / JSON5
reload only when something changed	Reloading Changed Files
the CLI	Tools › fson-check