fast-yaml-core

Core YAML 1.2.2 parser and emitter for the fast-yaml ecosystem.

[!NOTE] This crate provides three distinct components: Parser (YAML → data), Emitter (data → YAML), and Streaming Formatter (events → YAML, no DOM).

Components

Parser

Purpose: Deserialize YAML text into Rust data structures (DOM).

When to use:

• Need to manipulate YAML data programmatically
• Building APIs that consume YAML config
• Validating YAML structure

Data flow: YAML text → Value (DOM)

Emitter

Purpose: Serialize Rust data structures back to YAML text.

When to use:

• Generating YAML from code
• Config file generation
• Data export

Data flow: Value (DOM) → YAML text

Configuration: EmitterConfig allows customizing indent, line width, flow style, etc.

Streaming Formatter (feature: streaming)

Purpose: Format YAML directly from parser events without building DOM.

When to use:

• Formatting large files (faster, less memory)
• CLI tools (convert, format, validate)
• Processing YAML streams

Data flow: Parser events → YAML text (zero-copy)

Advantages:

• ⚡ 2-3x faster than parse + emit
• 📉 O(1) memory vs O(n) for DOM
• 🎯 Ideal for batch operations

[!TIP] Use Streaming Formatter for CLI batch mode formatting. Use Parser + Emitter when you need to modify YAML data.

Installation

Add to your Cargo.toml:

[dependencies]
fast-yaml-core = "0.3"

Or with cargo-add:

cargo add fast-yaml-core

[!IMPORTANT] Requires Rust 1.88 or later.

Usage

Parser: YAML → Data Structures

use fast_yaml_core::{Parser, Value};

// Parse single document
let yaml = "name: test\nvalue: 123";
let doc = Parser::parse_str(yaml)?;

// Parse multiple documents
let yaml = "---\nfoo: 1\n---\nbar: 2";
let docs = Parser::parse_all_str(yaml)?;
# Ok::<(), Box<dyn std::error::Error>>(())

Emitter: Data Structures → YAML

use fast_yaml_core::{Emitter, EmitterConfig, Value, Map, ScalarOwned};

// Basic emission
let value = Value::Value(ScalarOwned::String("hello".to_string()));
let yaml = Emitter::emit_str(&value)?;

// Custom configuration
let config = EmitterConfig::new()
    .with_indent(4)
    .with_width(120)
    .with_explicit_start(true);
let emitter = Emitter::new(config);
let yaml = emitter.emit_str(&value)?;
# Ok::<(), Box<dyn std::error::Error>>(())

Streaming Formatter: Events → YAML (no DOM)

#[cfg(feature = "streaming")]
use fast_yaml_core::streaming::{format_yaml, FormatterBackend};

#[cfg(feature = "streaming")]
{
    let yaml = "name: test\nvalue: 123";

    // Format without building DOM (faster, less memory)
    let formatted = format_yaml(yaml)?;

    // Result: properly formatted YAML
    assert!(formatted.contains("name: test"));
}
# Ok::<(), Box<dyn std::error::Error>>(())

[!TIP] Enable the streaming feature for formatter: fast-yaml-core = { version = "0.4", features = ["streaming"] }

YAML 1.2.2 Compliance

This library implements the YAML 1.2.2 specification with the Core Schema:

[!NOTE] YAML 1.1 booleans (yes/no/on/off) are treated as strings per YAML 1.2.2 spec.

Features

# Enable streaming formatter
fast-yaml-core = { version = "0.4", features = ["streaming"] }

# Enable arena allocation
fast-yaml-core = { version = "0.4", features = ["arena"] }

# Enable both
fast-yaml-core = { version = "0.4", features = ["streaming", "arena"] }

[!TIP] The arena feature provides 10-15% faster parsing for large documents by reducing allocator overhead.

Related Crates

This crate is part of the fast-yaml workspace:

• fast-yaml-linter — YAML linting with rich diagnostics
• fast-yaml-parallel — Multi-threaded YAML processing

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.