docspec-core 1.21.6

Core event types and traits for DocSpec streaming document conversion
Documentation

docspec-core

Core event types and traits for DocSpec streaming document conversion

docspec-core is the foundation of DocSpec: the Event type that documents stream as, the EventSource and EventSink traits that decouple readers from writers, and the pipe helper that drives one into the other. It reads and writes nothing itself — it defines the contract every other crate speaks. Streaming, like the rest of DocSpec. (See the Manifesto for why.)

Add it

[dependencies]
docspec-core = "1"

Speak the contract

A reader is an EventSource, a writer is an EventSink, and pipe moves events from one into the other until the source runs dry. Implementing a sink is this small — here we count the events flowing through:

use docspec_core::{Event, EventSink, Result};

/// A sink that counts the events flowing through it.
struct CountEvents(usize);

impl EventSink for CountEvents {
    fn handle_event(&mut self, _event: Event) -> Result<()> {
        self.0 += 1;
        Ok(())
    }
    fn finish(self) -> Result<()> {
        Ok(())
    }
}

Pair it with any EventSource — a DOCX, HTML, or Markdown reader from a sibling crate — and drive them with pipe(source, sink). Nothing is buffered; events flow one at a time.

What's inside

  • Event — every document structure DocSpec understands. The event module documents each variant and its well-formedness rules.
  • EventSource / EventSink / AssetHandle — the reader, writer, and streamed-asset contracts.
  • pipe — connect a source to a sink with no buffering.
  • Adapters — SkipEmptyBlocks drops empty heading/blockquote/paragraph pairs with O(1) look-back; StackTrackingSink validates nesting. Each wraps a source or sink without holding the document.

Related