Trait EventReceiver 

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

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 SpannedEventReceiver. Note that EventReceivers implement SpannedEventReceiver automatically. Non-spanned receivers receive Event::Comment(text, placement) like any other event, but without source location. Spanned receivers receive the same comment event plus the comment Span in SpannedEventReceiver::on_event. For comments, that span covers the whole source comment, including # and excluding the line break. When parsing from an input with byte offsets, such as Parser::new_from_str, Span::slice returns that source comment text.

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 data events. Comments can appear in the raw event stream between a key and its value; they are presentation metadata, not YAML data nodes. Consumers building YAML data trees should ignore Event::Comment. Any key/value alternation shortcut applies only after filtering out comments and other presentation metadata. After that filtering, the first event after an Event::MappingStart will be the key, and the following event will be 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::MappingEnd 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 visibility):

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<'input> {
    events: Vec<Event<'input>>,
}

/// Implement `on_event`, pushing into `self.events`.
impl<'input> EventReceiver<'input> for EventSink<'input> {
    fn on_event(&mut self, ev: Event<'input>) {
        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<'input>)

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

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors