# jbeder/yaml-cpp architecture

> Architecture diagram of the GitHub repository jbeder/yaml-cpp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jbeder/yaml-cpp
- Repository: https://github.com/jbeder/yaml-cpp

## Overview

yaml-cpp is a C++ YAML 1.2 parsing and emitting library. Its main workflow accepts an input stream, scans tokens, parses each document into events, and builds a navigable Node graph; clients can convert node values to C++ types and emit nodes back as YAML. The graph also shows the event-based parser extension point and the separate graph-builder adapter. Source excerpts confirm parser dispatch and event semantics; some Node/emitter wiring is inferred from the public API and tree, so uncertain links are omitted.

Main entry points: [`src/parser.cpp`](https://github.com/jbeder/yaml-cpp/blob/master/src/parser.cpp) (Parser), [`src/singledocparser.cpp`](https://github.com/jbeder/yaml-cpp/blob/master/src/singledocparser.cpp) (Document parser), [`include/yaml-cpp/node/node.h`](https://github.com/jbeder/yaml-cpp/blob/master/include/yaml-cpp/node/node.h) (Node API), [`include/yaml-cpp/contrib/graphbuilder.h`](https://github.com/jbeder/yaml-cpp/blob/master/include/yaml-cpp/contrib/graphbuilder.h) (Graph adapter API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_parse["Parsing"]
  node_parser["Parser<br/>[parser.cpp]"]
  node_directives["Directive handling<br/>[directives.cpp]"]
  node_scanner["Scanner<br/>[scanner.cpp]"]
  node_single_doc["Document parser"]
  node_event_api["Event handler API<br/>[eventhandler.h]"]
end

subgraph group_nodes["Node model"]
  node_node_builder["Node builder<br/>[nodebuilder.cpp]"]
  node_node_api["Node API<br/>[node.h]"]
  node_node_storage["Node storage<br/>[node_data.cpp]"]
  node_conversion["Type conversion<br/>[convert.h]"]
end

subgraph group_emit["Emission"]
  node_node_events["Node events<br/>[nodeevents.cpp]"]
  node_emit_api["Emit API<br/>[emit.h]"]
  node_emitter["YAML emitter<br/>[emitter.cpp]"]
end

subgraph group_extensions["Extensions"]
  node_graph_builder["Graph builder<br/>[graphbuilder.cpp]"]
  node_graph_adapter["Graph adapter API<br/>[graphbuilder.h]"]
end

node_client(("C++ client"))
node_input["YAML input"]
node_output["YAML output"]

node_client -->|"loads stream"| node_parser
node_input -->|"provides bytes"| node_scanner
node_parser -->|"reads tokens"| node_scanner
node_parser -->|"parses directives"| node_directives
node_parser -->|"dispatches document"| node_single_doc
node_single_doc -->|"consumes tokens"| node_scanner
node_single_doc -->|"emits events"| node_event_api
node_node_builder -->|"handles events"| node_event_api
node_node_builder -->|"creates nodes"| node_node_storage
node_node_api -->|"accesses graph"| node_node_storage
node_client -->|"reads or edits"| node_node_api
node_node_api -->|"converts values"| node_conversion
node_client -->|"requests emission"| node_emit_api
node_emit_api -->|"traverses nodes"| node_node_events
node_node_events -->|"dispatches events"| node_emitter
node_emitter -->|"writes YAML"| node_output
node_client -.->|"requests graph"| node_graph_adapter
node_graph_adapter -.->|"reads documents"| node_parser
node_graph_adapter -.->|"adapts callbacks"| node_graph_builder

click node_parser "https://github.com/jbeder/yaml-cpp/blob/master/src/parser.cpp"
click node_directives "https://github.com/jbeder/yaml-cpp/blob/master/src/directives.cpp"
click node_scanner "https://github.com/jbeder/yaml-cpp/blob/master/src/scanner.cpp"
click node_single_doc "https://github.com/jbeder/yaml-cpp/blob/master/src/singledocparser.cpp"
click node_event_api "https://github.com/jbeder/yaml-cpp/blob/master/include/yaml-cpp/eventhandler.h"
click node_node_builder "https://github.com/jbeder/yaml-cpp/blob/master/src/nodebuilder.cpp"
click node_node_api "https://github.com/jbeder/yaml-cpp/blob/master/include/yaml-cpp/node/node.h"
click node_node_storage "https://github.com/jbeder/yaml-cpp/blob/master/src/node_data.cpp"
click node_conversion "https://github.com/jbeder/yaml-cpp/blob/master/include/yaml-cpp/node/convert.h"
click node_node_events "https://github.com/jbeder/yaml-cpp/blob/master/src/nodeevents.cpp"
click node_emit_api "https://github.com/jbeder/yaml-cpp/blob/master/include/yaml-cpp/node/emit.h"
click node_emitter "https://github.com/jbeder/yaml-cpp/blob/master/src/emitter.cpp"
click node_graph_builder "https://github.com/jbeder/yaml-cpp/blob/master/src/contrib/graphbuilder.cpp"
click node_graph_adapter "https://github.com/jbeder/yaml-cpp/blob/master/include/yaml-cpp/contrib/graphbuilder.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_parser,node_directives,node_scanner,node_single_doc,node_event_api,node_client toneBlue
class node_node_builder,node_node_api,node_node_storage,node_conversion toneAmber
class node_node_events,node_emit_api,node_emitter toneMint
class node_graph_builder,node_graph_adapter toneRose
class node_input,node_output toneIndigo
```

## Components

### Parsing

- [Parser](https://github.com/jbeder/yaml-cpp/blob/master/src/parser.cpp): `src/parser.cpp`
- [Directive handling](https://github.com/jbeder/yaml-cpp/blob/master/src/directives.cpp): `src/directives.cpp`
- [Scanner](https://github.com/jbeder/yaml-cpp/blob/master/src/scanner.cpp): `src/scanner.cpp`
- [Document parser](https://github.com/jbeder/yaml-cpp/blob/master/src/singledocparser.cpp): `src/singledocparser.cpp`
- [Event handler API](https://github.com/jbeder/yaml-cpp/blob/master/include/yaml-cpp/eventhandler.h): `include/yaml-cpp/eventhandler.h`

### Node model

- [Node builder](https://github.com/jbeder/yaml-cpp/blob/master/src/nodebuilder.cpp): `src/nodebuilder.cpp`
- [Node API](https://github.com/jbeder/yaml-cpp/blob/master/include/yaml-cpp/node/node.h): `include/yaml-cpp/node/node.h`
- [Node storage](https://github.com/jbeder/yaml-cpp/blob/master/src/node_data.cpp): `src/node_data.cpp`
- [Type conversion](https://github.com/jbeder/yaml-cpp/blob/master/include/yaml-cpp/node/convert.h): `include/yaml-cpp/node/convert.h`

### Emission

- [Node events](https://github.com/jbeder/yaml-cpp/blob/master/src/nodeevents.cpp): `src/nodeevents.cpp`
- [Emit API](https://github.com/jbeder/yaml-cpp/blob/master/include/yaml-cpp/node/emit.h): `include/yaml-cpp/node/emit.h`
- [YAML emitter](https://github.com/jbeder/yaml-cpp/blob/master/src/emitter.cpp): `src/emitter.cpp`

### Extensions

- [Graph builder](https://github.com/jbeder/yaml-cpp/blob/master/src/contrib/graphbuilder.cpp): `src/contrib/graphbuilder.cpp`
- [Graph adapter API](https://github.com/jbeder/yaml-cpp/blob/master/include/yaml-cpp/contrib/graphbuilder.h): `include/yaml-cpp/contrib/graphbuilder.h`

### Other components

- **C++ client**
- **YAML input**
- **YAML output**

## Connections

- C++ client → Parser: loads stream
- YAML input → Scanner: provides bytes
- Parser → Scanner: reads tokens
- Parser → Directive handling: parses directives
- Parser → Document parser: dispatches document
- Document parser → Scanner: consumes tokens
- Document parser → Event handler API: emits events
- Node builder → Event handler API: handles events
- Node builder → Node storage: creates nodes
- Node API → Node storage: accesses graph
- C++ client → Node API: reads or edits
- Node API → Type conversion: converts values
- C++ client → Emit API: requests emission
- Emit API → Node events: traverses nodes
- Node events → YAML emitter: dispatches events
- YAML emitter → YAML output: writes YAML
- C++ client → Graph adapter API: requests graph
- Graph adapter API → Parser: reads documents
- Graph adapter API → Graph builder: adapts callbacks