yaml-rust2

To migrate from the unmaintained yaml-rust crate to yaml-rust2, you can use one of three methods depending on how much code you want to change.

Method 1: Update Imports (Recommended)

Update your Cargo.toml and change all occurrences of yaml_rust to yaml_rust2 in your source code.

Method 2: Use a Rust Alias

Update your Cargo.toml to use yaml-rust2 but alias it as yaml_rust in your code using use yaml_rust2 as yaml_rust;.

Method 3: Cargo Package Alias (Zero Code Changes)

You can tell Cargo to treat yaml-rust2 as the provider for the yaml-rust dependency. This allows you to keep using use yaml_rust::... in your code without any modifications.

# Method 1: Direct replacement
-yaml-rust = "0.4.4"
+yaml-rust2 = "0.8.0"

# Method 3: Cargo alias (No code changes required)
-yaml-rust = "0.4.4"
+yaml-rust = { version = "0.6", package = "yaml-rust2" }

The bench_compare tool requires a bench_compare.toml file in the current directory. All fields must be explicitly set; default values are not supported.

Required Configuration Fields:

• yaml_input_dir: Path to the directory containing the input YAML files.
• iterations: Number of iterations to perform (used when running run_bench).
• yaml_output_dir: Directory where run_bench YAML outputs are saved.
• csv_output: Path to the CSV file that aggregates times for each parser and file.
• [[parsers]]: An array of tables defining each parser. Each parser block requires:
  • name: The name of the parser (used for logging).
  • path: The directory containing the parser's run_bench and time_parse binaries.

yaml_input_dir = "bench_yaml"
iterations = 10
yaml_output_dir = "yaml_output"
csv_output = "benchmark.csv"

[[parsers]]
name = "yaml-rust2"
path = "target/release/"

# [[parsers]]
# name = "libfyaml"
# path = "../libfyaml/build"

The Yaml enum is the primary way to interact with parsed YAML data. It represents various YAML types including integers, booleans, strings, arrays, hashes, and nulls.

Key features:

• Type Conversion: Use as_i64(), as_bool(), as_str(), as_vec(), and as_hash() to attempt to access the underlying data. For floating point numbers, use as_f64() which parses the Real variant on demand.
• Safe Access: If you attempt to access a non-existent key in a hash or an out-of-bounds index in an array, the library returns Yaml::BadValue instead of panicking (when using the Index trait).
• Fallback Values: Use .or(other) or .borrowed_or(&other) to provide a default value if the current node is Yaml::Null or Yaml::BadValue.

use yaml_rust2::Yaml;

let foo = Yaml::from_str("-123");
assert_eq!(foo.as_i64().unwrap(), -123);

// Use .or() to handle nulls or missing values
let val = Yaml::Null.or(Yaml::Integer(42));
assert_eq!(val.as_i64().unwrap(), 42);

The yaml-rust2 parser provides a low-level, push-based (event-driven) API via the EventReceiver trait. Instead of loading a full document into memory, you implement this trait to react to individual YAML events as they are emitted.

Event Hierarchy

1. The stream starts with Event::StreamStart.
2. Followed by Event::DocumentStart.
3. Then the document content (e.g., Event::MappingStart, Event::SequenceStart, or Event::Scalar).
4. The stream ends with Event::StreamEnd.

Implementation Patterns

• EventReceiver: Implement this for a simple event stream. It provides on_event(ev: Event).
• MarkedEventReceiver: Implement this if you need to know the location (line/column) of each event. It provides on_event(ev: Event, mark: Marker). Note that all EventReceiver implementations automatically implement MarkedEventReceiver.

# use yaml_rust2::parser::{Event, EventReceiver, Parser};

/// Sink of events. Collects them into an array.
struct EventSink {
    events: Vec<Event>,
}

/// Implement `on_event`, pushing into `self.events`.
impl EventReceiver for EventSink {
    fn on_event(&mut self, ev: Event) {
        self.events.push(ev);
    }
}

/// Load events from a yaml string.
fn str_to_events(yaml: &str) -> Vec<Event> {
    let mut sink = EventSink { events: Vec::new() };
    let mut parser = Parser::new_from_str(yaml);
    // Load events using our sink as the receiver.
    parser.load(&mut sink, true).unwrap();
    sink.events
}

When reading raw bytes (e.g., from a file or network), use YamlDecoder to handle character encoding (UTF-8, UTF-16, etc.) and potential malformations.

Decoding Traps (YAMLDecodingTrap):

• Strict: Returns a LoadError::Decode on malformed sequences.
• Ignore: Skips the offending bytes.
• Replace: Replaces malformed bytes with the Unicode replacement character (�).
• Call(fn): Executes a user-provided callback function to handle the error manually.

Example usage:

use yaml_rust2::yaml::{YamlDecoder, YAMLDecodingTrap};

let bytes = b"a\xa9: 1"; // Contains invalid UTF-8
let mut decoder = YamlDecoder::read(bytes)
    .encoding_trap(YAMLDecodingTrap::Ignore);

let docs = decoder.decode().unwrap();

use yaml_rust2::yaml::{YamlDecoder, YAMLDecodingTrap};

let bytes = b"---\na\xa9: 1\nb: 2.2\nc: [1, 2]\n";
let out = YamlDecoder::read(bytes)
    .encoding_trap(YAMLDecodingTrap::Ignore)
    .decode()
    .unwrap();