From 46393b3aa2ff7a6035d3967378553e2d22214b71 Mon Sep 17 00:00:00 2001 From: Mihaela Mihaljevic Date: Tue, 9 Jun 2026 02:24:02 +0200 Subject: [PATCH] docs: document the pull/push/SAX/tree consumption modes Make explicit that input is consumed step by step with bounded memory via the pull cursor (EventReader/TextReader), push/feed, and SAX, and that only the tree mode materializes the whole document. --- README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/README.md b/README.md index c4f1d20..253197a 100644 --- a/README.md +++ b/README.md @@ -125,6 +125,27 @@ currently runs **632 tests in 97 suites** (`swift test`). library, eval-time namespace bindings) and XPointer (`element()`, `xpointer()`, `xpath1()`, `xmlns()`). +### Consumption modes + +You choose how the document is consumed; only the tree mode materializes the whole +document. The input itself never has to be a whole string: every mode below also +accepts an incremental character or byte source (`pulling:` / `pullingBytes:`), so +the engine advances step by step with bounded memory and the bytes are pulled on +demand. The `String` overloads are a convenience for when you already hold the text. + +- **Pull cursor (step by step)**: `events(_:)` / `events(pulling:)` returns an + `EventReader`; call `next()` to get one `Event` at a time. `TextReader` is the + node cursor (the libxml2 `xmlTextReader` model): `read()` advances to the next + node, you inspect it, `read()` again. Bounded state, no tree. +- **Push / feed**: `PushParser.feed(_:)`/`finish()` accepts the document in + arbitrary chunks (a socket, a generator); `events(feeding:)` exposes the same + over an `AsyncSequence`. It retains only the current incomplete token and the + open-element stack. +- **SAX**: `parse(_:sax:)` delivers SAX2-style callbacks, no tree. +- **Tree**: `parse`/`parseTree` build a `Model.Node` / `TreeNode` tree for + random access, mutation, validation, XPath, and XSLT. This mode (like libxml2's + DOM) holds the whole document, because those operations need the full structure. + ### Safe defaults By default the parser rejects `` and refuses every external reference