attach spans to events

The main abstraction is the new function `Emitter::move_position`.
The `CallbackEmitter` uses this to track positions and spans.
For that, the tokenizer has to do some more work and emit more events,
so that the `Emitter` can track the position accurately.

An alternative was to add a `Reader` parameter to all emitter methods,
which can be used by `CallbackEmitter` to get spans from the reader.
We decided for this approach as it introduces less breaking changes and
clutter for the users which don't want to consume spans.

Author: Akida31

Cargo.toml

@@ -26,6 +26,7 @@ markup5ever_rcdom = "0.5.0-unofficial"
 # required for examples/scraper.rs
 scraper = "0.21.0"
 argh = "0.1.12"
+annotate-snippets = "0.11.5"
 
 [features]
 # By default this crate depends on the jetscii library for best performance.
@@ -74,5 +75,8 @@ name = "callback_emitter"
 name = "scraper"
 required-features = ["tree-builder"]
 
+[[example]]
+name = "spans"
+
 [lib]
 bench = false

examples/callback_emitter.rs

@@ -11,27 +11,29 @@
 //! link: foo
 //! ```
 use html5gum::emitters::callback::{CallbackEmitter, CallbackEvent};
-use html5gum::{Emitter, IoReader, Tokenizer};
+use html5gum::{Emitter, IoReader, Span, Tokenizer};
 
 fn get_emitter() -> impl Emitter<Token = String> {
     let mut is_anchor_tag = false;
     let mut is_href_attr = false;
 
-    CallbackEmitter::new(move |event: CallbackEvent<'_>| match event {
-        CallbackEvent::OpenStartTag { name } => {
-            is_anchor_tag = name == b"a";
-            is_href_attr = false;
-            None
-        }
-        CallbackEvent::AttributeName { name } => {
-            is_href_attr = name == b"href";
-            None
-        }
-        CallbackEvent::AttributeValue { value } if is_anchor_tag && is_href_attr => {
-            Some(String::from_utf8_lossy(value).into_owned())
-        }
-        _ => None,
-    })
+    CallbackEmitter::new(
+        move |event: CallbackEvent<'_>, _span: Span<()>| match event {
+            CallbackEvent::OpenStartTag { name } => {
+                is_anchor_tag = name == b"a";
+                is_href_attr = false;
+                None
+            }
+            CallbackEvent::AttributeName { name } => {
+                is_href_attr = name == b"href";
+                None
+            }
+            CallbackEvent::AttributeValue { value } if is_anchor_tag && is_href_attr => {
+                Some(String::from_utf8_lossy(value).into_owned())
+            }
+            _ => None,
+        },
+    )
 }
 
 fn main() {

examples/spans.rs

@@ -0,0 +1,77 @@
+//! A modified version of `examples/callback_emitter.rs` which prints the location of all links in
+//! the input.
+//!
+//! ```text
+//! printf '<h1>Hello world!</h1><a href="foo">bar</a>' | cargo run --example=spans
+//! ```
+//!
+//! Output:
+//!
+//! ```text
+//! link: foo
+//! ```
+use annotate_snippets::{Level, Renderer, Snippet};
+use html5gum::emitters::callback::{CallbackEmitter, CallbackEvent};
+use html5gum::{Emitter, IoReader, Span, Tokenizer};
+
+fn get_emitter() -> impl Emitter<Token = (String, Span<usize>)> {
+    let mut is_anchor_tag = false;
+    let mut is_href_attr = false;
+
+    CallbackEmitter::new(
+        move |event: CallbackEvent<'_>, span: Span<usize>| match event {
+            CallbackEvent::OpenStartTag { name } => {
+                is_anchor_tag = name == b"a";
+                is_href_attr = false;
+                None
+            }
+            CallbackEvent::AttributeName { name } => {
+                is_href_attr = name == b"href";
+                None
+            }
+            CallbackEvent::AttributeValue { value } if is_anchor_tag && is_href_attr => Some((
+                format!(
+                    "found link with content `{}` here",
+                    String::from_utf8_lossy(value)
+                ),
+                span,
+            )),
+            _ => None,
+        },
+    )
+}
+
+struct CollectingReader<R> {
+    inner: R,
+    read: Vec<u8>,
+}
+
+impl<R: std::io::Read> std::io::Read for CollectingReader<R> {
+    fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
+        let len = self.inner.read(buf)?;
+        self.read.extend_from_slice(&buf[..len]);
+        Ok(len)
+    }
+}
+
+fn main() {
+    let mut reader = CollectingReader {
+        inner: std::io::stdin().lock(),
+        read: Vec::new(),
+    };
+    let spans = Tokenizer::new_with_emitter(IoReader::new(&mut reader), get_emitter())
+        .flatten()
+        .collect::<Vec<_>>();
+    let source = String::from_utf8_lossy(&reader.read);
+    let mut message = Level::Info.title("found link");
+    for (label, span) in &spans {
+        message = message.snippet(
+            Snippet::source(&source)
+                .origin("<stdin>")
+                .fold(true)
+                .annotation(Level::Info.span(span.start..span.end).label(label)),
+        );
+    }
+    let renderer = Renderer::styled();
+    println!("{}", renderer.render(message));
+}