# Boost.LEAF Diagnostic Propagation Examples

Three small C++ programs demonstrating how [Boost.LEAF](https://boostorg.github.io/leaf/)
propagates rich diagnostic information together with an error code, without throwing
exceptions and without exceptions needing to be enabled in the codebase.

- `src/leaf_on_error_example.cpp` — distinct context structs attached per scope with
  `leaf::on_error`; handlers matched by the exact set of available types.
- `src/leaf_mutable_block.cpp` — a single mutable `diagnostic_context` struct, re-registered
  with `leaf::on_error` as the operation progresses, so the handler receives the latest
  snapshot of all fields.
- `src/leaf_universal_handler.cpp` — handler selection: specific handlers first, generic
  "universal" handlers later, plus a final fallback. Shows how LEAF picks the best match.

## Core idea

LEAF returns errors as values of type `leaf::result<T>` instead of throwing exceptions.
At each point where an error can occur, arbitrary diagnostic values (file names, user info,
chunk numbers, timestamps, ...) are registered with `leaf::on_error(value)`. If
`leaf::new_error(...)` is returned, all registered values are captured into the current
error context, and the top level uses `leaf::try_handle_all(try_block, handlers...)` to let
the handlers inspect whichever context types were active when the error was created.

Handler matching is done purely on types: a handler requesting
`(write_error const&, file_context const&, user_context const&)` will only run if the error
carries exactly those registered values; a more general handler is used otherwise. This
gives exception-like separation between "raising" a failure and "dealing with" it, but with
explicit `result` values, no exceptions, and no RTTI dependency.

The examples intentionally return distinct exit codes from the handlers so each one
reports which handler actually matched.

## Local build

Requirements: CMake >= 3.21, a C++17 compiler, and [vcpkg](https://vcpkg.io) (git clone +
bootstrap). The dependency is header-only `boost-leaf`.

```bash
git clone https://github.com/microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh

cmake -S . -B build \
  -DCMAKE_TOOLCHAIN_FILE=$PWD/vcpkg/scripts/buildsystems/vcpkg.cmake \
  -DCMAKE_BUILD_TYPE=Release
cmake --build build
```

Run one of the examples:

```bash
./build/leaf_on_error_example
```

If you already have Boost (>= 1.75) installed at the system level, plain
`cmake -S . -B build` also works; the CMake project picks `Boost::leaf` from a vcpkg
toolchain when available and falls back to the system header target otherwise.

## Docker

```bash
docker build -t leaf-examples .
docker run --rm leaf-examples
```

The first (build) stage installs the toolchain, clones vcpkg, downloads `boost-leaf`
through the `vcpkg.json` manifest and builds all three examples. The second (run)
stage copies the binaries into a slim image and executes them one after another,
printing the exit code of each.

## Docker Compose (v2)

```bash
docker compose up --build
```

runs the same build and then starts a container that executes all three examples.
`docker compose build` builds without running; `docker compose run --rm leaf-examples`
works too.