Driver for Serialization

[mitsuhiko]

Currently the main interface to serialize is the for_each_event method. This is frustratingly limiting. Right now this is the interface provided as used in the tests:

fn capture_events(s: &dyn Serialize) -> Vec<Event<'static>> {
    let mut events = Vec::new();
    for_each_event(s, |event, _, _| {
        events.push(event.to_static());
        Ok(())
    })
    .unwrap();
    events
}

The biggest challenge here is that you can't suspend what for_each_event does. A better model would be something like this:

fn capture_events(s: &dyn Serialize) -> Vec<Event<'static>> {
    let mut events = Vec::new();
    let mut driver = Driver::new(s);
    while let Some((event, _, _)) = driver.next().unwrap() {
        events.push(event.to_static());
    }
    events
}

The driver can't be an iterator as it would have to return borrows to itself and the next method also needs to return a result to communicate errors.