Trait EventReceiver

pub trait EventReceiver {
    // Required method
    fn on_event(&mut self, ev: Event);
}

Trait to be implemented in order to use the low-level parsing API.

The low-level parsing API is event-based (a push parser), calling EventReceiver::on_event for each YAML Event that occurs. The EventReceiver trait only receives events. In order to receive both events and their location in the source, use MarkedEventReceiver. Note that EventReceivers implement MarkedEventReceiver automatically.

Event hierarchy

The event stream starts with an Event::StreamStart event followed by an Event::DocumentStart event. If the YAML document starts with a mapping (an object), an Event::MappingStart event is emitted. If it starts with a sequence (an array), an Event::SequenceStart event is emitted. Otherwise, an Event::Scalar event is emitted.

In a mapping, key-values are sent as consecutive events. The first event after an Event::MappingStart will be the key, and following its value. If the mapping contains no sub-mapping or sub-sequence, then even events (starting from 0) will always be keys and odd ones will always be values. The mapping ends when an Event::MappingEnd event is received.

In a sequence, values are sent consecutively until the Event::SequenceEnd event.

If a value is a sub-mapping or a sub-sequence, an Event::MappingStart or Event::SequenceStart event will be sent respectively. Following events until the associated Event::MappingStart or Event::SequenceEnd (beware of nested mappings or sequences) will be part of the value and not another key-value pair or element in the sequence.

For instance, the following yaml:

a: b
c:
  d: e
f:
  - g
  - h

will emit (indented and commented for lisibility):

StreamStart, DocumentStart, MappingStart,
  Scalar("a", ..), Scalar("b", ..)
  Scalar("c", ..), MappingStart, Scalar("d", ..), Scalar("e", ..), MappingEnd,
  Scalar("f", ..), SequenceStart, Scalar("g", ..), Scalar("h", ..), SequenceEnd,
MappingEnd, DocumentEnd, StreamEnd

Example

/// 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
}

Required Methods

fn on_event(&mut self, ev: Event)

Handler called for each YAML event that is emitted by the parser.

Implementors