# libfyaml Examples
This directory contains practical examples demonstrating various features of libfyaml.
## Building the Examples
### Using CMake (Recommended)
```bash
cd examples
mkdir build && cd build
cmake ..
cmake --build .
```
The compiled examples will be in the `build/` directory.
### Using Make
```bash
cd examples
make
```
The compiled examples will be in the current directory.
### Manual Compilation
```bash
gcc -o quick-start quick-start.c $(pkg-config --cflags --libs libfyaml)
gcc -o basic-parsing basic-parsing.c $(pkg-config --cflags --libs libfyaml)
# ... and so on for other examples
```
## Examples Overview
### 1. quick-start.c
Example showing:
- Parsing YAML from a file
- Extracting values using `fy_document_scanf()` (path-based queries)
- Modifying the document with `fy_document_insert_at()`
- Emitting the updated YAML
**Usage**:
```bash
./quick-start [config.yaml]
```
**Required YAML structure** (for config.yaml):
```yaml
server:
host: localhost
port: 8080
```
---
### 2. basic-parsing.c
Basic YAML parsing and different output formats:
- Parse YAML from file
- Emit as compact flow format
- Emit as standard block YAML
- Emit as JSON
**Usage**:
```bash
./basic-parsing [file.yaml]
```
Works with any valid YAML file.
---
### 3. path-queries.c
Query YAML documents using path expressions:
- Extract multiple values with `fy_document_scanf()`
- Query individual nodes with `fy_node_by_path()`
- Compare node values with strings
- Handle missing paths gracefully
**Usage**:
```bash
./path-queries
```
This example uses inline YAML, so no external file is needed.
---
### 4. document-manipulation.c
Example of document manipulation:
- Read existing values from YAML
- Update values (replace invoice number)
- Add new fields (spouse, delivery address)
- Emit with sorted keys
**Usage**:
```bash
./document-manipulation [invoice.yaml]
```
**Expected YAML structure** (for invoice.yaml):
```yaml
invoice: 34843
date: 2001-01-23
bill-to:
given: Chris
family: Dumars
address:
lines: |
458 Walkman Dr.
Suite #292
```
If no file is provided, the example uses built-in default data.
---
### 5. event-streaming.c
Demonstrates the low-level event-based API:
- Create parser and set input
- Process events one by one
- Handle different event types (scalars, mappings, sequences)
- Memory-efficient parsing for large files
**Usage**:
```bash
./event-streaming [file.yaml]
```
This is the most memory-efficient way to parse YAML, suitable for very large files.
---
### 6. build-from-scratch.c
Create YAML documents from scratch:
- Create empty document
- Build complex structures using `fy_node_buildf()` with printf-style formatting
- Add fields programmatically
- Emit as both JSON and YAML
**Usage**:
```bash
./build-from-scratch
```
No input file needed - generates a complete configuration document.
---
## Sample YAML Files
Sample YAML files are provided for testing:
- **config.yaml** - Simple server configuration
- **invoice.yaml** - Invoice document for manipulation example
Create these files in the examples directory, or the programs will use sensible defaults.
### Sample config.yaml
```yaml
server:
host: localhost
port: 8080
ssl: true
max_connections: 100
database:
host: db.example.com
port: 5432
name: production_db
logging:
level: info
file: /var/log/app.log
```
### Sample invoice.yaml
```yaml
invoice: 34843
date: 2001-01-23
bill-to:
given: Chris
family: Dumars
address:
lines: |
458 Walkman Dr.
Suite #292
city: Royal Oak
state: MI
postal: 48046
ship-to:
given: Chris
family: Dumars
product:
- sku: BL394D
quantity: 4
description: Basketball
price: 450.00
- sku: BL4438H
quantity: 1
description: Super Hoop
price: 2392.00
tax: 251.42
total: 4443.52
comments: >
Late afternoon is best.
Backup contact is Nancy
Billsmer @ 338-4338.
```
## API Reference
For complete API documentation, visit: https://pantoniou.github.io/libfyaml/
## Common Patterns
### Error Handling
All examples demonstrate proper error handling:
```c
struct fy_document *fyd = fy_document_build_from_file(NULL, "file.yaml");
if (!fyd) {
fprintf(stderr, "Failed to parse YAML\n");
return EXIT_FAILURE;
}
// ... use document ...
fy_document_destroy(fyd); // Always clean up
```
### Path-Based Queries
Extract multiple values efficiently:
```c
int count = fy_document_scanf(fyd,
"/path1 %s "
"/path2 %d",
string_var, &int_var);
if (count != 2) {
// Handle error
}
```
### Document Modification
Add or update fields:
```c
fy_document_insert_at(fyd, "/parent/path", FY_NT,
fy_node_buildf(fyd, "key: value"));
```
### Output Formatting
Choose output mode based on needs:
```c
// Compact JSON
fy_emit_document_to_fp(fyd, FYECF_MODE_JSON, stdout);
// Pretty YAML with sorted keys
// One-line flow format
fy_emit_document_to_fp(fyd, FYECF_MODE_FLOW_ONELINE, stdout);
```
## License
All examples are released under the MIT License, same as libfyaml.
Copyright (c) 2019-2025 Pantelis Antoniou <pantelis.antoniou@konsulko.com>