Skip to main content

Module event

docspec_core

Module event 

Source
Expand description

Event types for the streaming document pipeline.

DocSpec documents are streams of typed events. Readers (crate::EventSource) emit events; writers (crate::EventSink) consume them in document order. This module defines every event type and the rules for well-formed streams.

For higher-level design decisions, see the Architecture document.

§Error Handling

Events never carry errors; errors flow out-of-band via crate::Result. See crate::EventSource::next_event for full semantics. Readers recover silently when possible (missing optional attributes, unrecognized elements, unsupported features) and return Err only on fatal conditions (malformed structure, truncated stream, invalid encoding).

§Asset References

Event::Image carries an crate::ImageSource (asset id or URI), not bytes. Writers resolve bytes lazily via crate::AssetProvider; assets must remain accessible until Event::EndDocument.

§Well-Formedness Rules

Readers MUST produce well-formed streams; writers MAY assume well-formedness.

  1. Every Start* has exactly one matching End*. They nest but never overlap.
  2. Exactly one root: Event::StartDocument. Empty containers are valid.
  3. Event::Text appears only inside containers, never at root.
  4. Event::StartLink appears inside inline-accepting blocks (paragraphs, headings, list items, cells, definition details) and does not nest.
  5. List items (Event::StartOrderedListItem, Event::StartUnorderedListItem) appear inside block containers and may nest; level is 0-indexed.
  6. Event::StartCaption appears at most once per table, before any rows.
  7. Each footnote id appears in exactly one Event::FootnoteRef and one Event::StartFootnote.
  8. Event::StartTableRow appears only inside Event::StartTable; Event::StartTableCell and Event::StartTableHeader only inside Event::StartTableRow.
  9. Readers MUST normalize overlapping source styles into nested Event::StartTextStyle spans via close-and-reopen.
  10. All open Event::StartTextStyle spans MUST close before the enclosing block-end event (Event::EndParagraph, Event::EndHeading, Event::EndOrderedListItem, Event::EndUnorderedListItem, Event::EndTableCell, Event::EndTableHeader, Event::EndCaption, Event::EndDefinitionTerm, Event::EndDefinitionDetail).
  11. Event::StartTextStyle and Event::StartPreformatted MUST NOT nest inside each other.
  12. Inside a link, Event::StartLink SHOULD be the outer container and Event::StartTextStyle the inner.
  13. Empty Event::StartTextStyle spans MUST NOT be emitted: at least one Event::Text event must appear before the matching Event::EndTextStyle.

Enums§

Event
A streaming document event.
TextStyleKind
The kind of text formatting carried by a Event::StartTextStyle event.