xml-syntax-reader 0.1.0

Low-level, callback-based, streaming XML tokenizer
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410

use crate::types::Span;

/// Trait for receiving fine-grained XML parsing events.
///
/// All `&[u8]` slices are references into the caller's buffer.
/// Return `Ok(())` to continue parsing, or `Err(Self::Error)` to abort.
///
/// Default implementations do nothing and return `Ok(())`.
///
/// # Callback sequences
///
/// The parser emits callbacks in these patterns for each XML construct.
/// `*` means zero or more, `+` means one or more, `|` means alternatives.
///
/// ## Start tag
///
/// ```text
/// start_tag_open
///   (attribute_name  attribute-value-sequence  attribute_end)*
///   start_tag_close | empty_element_end
/// ```
///
/// `<img src="a.png" alt="pic"/>`:
/// ```text
/// start_tag_open("img")
/// attribute_name("src")
/// attribute_value("a.png")
/// attribute_end
/// attribute_name("alt")
/// attribute_value("pic")
/// attribute_end
/// empty_element_end
/// ```
///
/// `<p>`:
/// ```text
/// start_tag_open("p")
/// start_tag_close
/// ```
///
/// ## Attribute value sequence
///
/// Between the quotes of a single attribute:
/// ```text
/// (attribute_value | attribute_entity_ref | attribute_char_ref)*
/// ```
///
/// The value is segmented at entity/character reference boundaries and at
/// buffer boundaries. Empty attribute values and values consisting solely
/// of references produce zero `attribute_value` calls. `attribute_end`
/// always fires exactly once per attribute, after the closing quote.
///
/// `class="a&amp;b"`:
/// ```text
/// attribute_name("class")
/// attribute_value("a")
/// attribute_entity_ref("amp")
/// attribute_value("b")
/// attribute_end
/// ```
///
/// `v="&amp;"` (ref-only - no `attribute_value` calls):
/// ```text
/// attribute_name("v")
/// attribute_entity_ref("amp")
/// attribute_end
/// ```
///
/// `v=""` (empty - no `attribute_value` calls):
/// ```text
/// attribute_name("v")
/// attribute_end
/// ```
///
/// ## End tag
///
/// `</div>`:
/// ```text
/// end_tag("div")
/// ```
///
/// ## Text content
///
/// When present between markup:
/// ```text
/// (characters | entity_ref | char_ref)+
/// ```
///
/// Not all elements have text content - e.g. `<p></p>` produces no text
/// events between `start_tag_close` and `end_tag`. When text is present,
/// it is segmented at entity/character reference boundaries and at buffer
/// boundaries. There is no trailing `characters` call after a final
/// reference.
///
/// `hello &amp; world`:
/// ```text
/// characters("hello ")
/// entity_ref("amp")
/// characters(" world")
/// ```
///
/// `&lt;&gt;` (references only - no `characters` calls):
/// ```text
/// entity_ref("lt")
/// entity_ref("gt")
/// ```
///
/// ## CDATA section
///
/// `cdata_start → cdata_content* → cdata_end`
///
/// `<![CDATA[hello]]>`:
/// ```text
/// cdata_start
/// cdata_content("hello")
/// cdata_end
/// ```
///
/// `<![CDATA[]]>` (empty - no `cdata_content` call):
/// ```text
/// cdata_start
/// cdata_end
/// ```
///
/// ## Comment
///
/// `comment_start → comment_content* → comment_end`
///
/// `<!-- hi -->`:
/// ```text
/// comment_start
/// comment_content(" hi ")
/// comment_end
/// ```
///
/// `<!---->` (empty - no `comment_content` call):
/// ```text
/// comment_start
/// comment_end
/// ```
///
/// ## Processing instruction
///
/// `pi_start → pi_content* → pi_end`
///
/// Leading whitespace between the target and content is consumed by the
/// parser and not included in `pi_content`.
///
/// `<?pi data?>`:
/// ```text
/// pi_start("pi")
/// pi_content("data")
/// pi_end
/// ```
///
/// `<?x?>` (no content - no `pi_content` call):
/// ```text
/// pi_start("x")
/// pi_end
/// ```
///
/// ## DOCTYPE declaration
///
/// `doctype_start → doctype_content* → doctype_end`
///
/// Content is opaque (not further parsed).
///
/// `<!DOCTYPE html [<!ENTITY foo "bar">]>`:
/// ```text
/// doctype_start("html")
/// doctype_content(" [<!ENTITY foo \"bar\">]")
/// doctype_end
/// ```
///
/// `<!DOCTYPE html>` (no content - no `doctype_content` call):
/// ```text
/// doctype_start("html")
/// doctype_end
/// ```
///
/// ## XML declaration
///
/// A single `xml_declaration` call (never chunked).
///
/// `<?xml version="1.0" encoding="UTF-8"?>`:
/// ```text
/// xml_declaration(version="1.0", encoding=Some("UTF-8"), standalone=None)
/// ```
///
/// For CDATA, comments, PIs, and DOCTYPE, the content callback may fire
/// more than once when the content spans buffer boundaries.
pub trait Visitor {
    type Error;

    // --- Element events ---

    /// Start tag opened: `<name`.
    /// `name` is the element name (may include a namespace prefix and `:`).
    fn start_tag_open(&mut self, name: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (name, span);
        Ok(())
    }

    /// Attribute name within a start tag.
    fn attribute_name(&mut self, name: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (name, span);
        Ok(())
    }

    /// Attribute value text (between entity/char ref boundaries or buffer boundaries).
    /// The surrounding quotes are **not** included.
    ///
    /// Called zero or more times per attribute, segmented at entity/char
    /// reference boundaries and buffer boundaries. Not called for empty
    /// segments - an attribute whose value is empty or consists entirely
    /// of references produces zero `attribute_value` calls.
    fn attribute_value(&mut self, value: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (value, span);
        Ok(())
    }

    /// End of an attribute value (the closing quote was consumed).
    fn attribute_end(&mut self, span: Span) -> Result<(), Self::Error> {
        let _ = span;
        Ok(())
    }

    /// Entity reference in attribute value: `&name;`.
    /// `name` is the entity name without `&` and `;`.
    fn attribute_entity_ref(&mut self, name: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (name, span);
        Ok(())
    }

    /// Character reference in attribute value: `&#NNN;` or `&#xHHH;`.
    /// `value` is the raw text between `&#` and `;` (e.g. `"60"` or `"x3C"`).
    fn attribute_char_ref(&mut self, value: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (value, span);
        Ok(())
    }

    /// Start tag closed with `>`.
    fn start_tag_close(&mut self, span: Span) -> Result<(), Self::Error> {
        let _ = span;
        Ok(())
    }

    /// Empty element closed with `/>`.
    fn empty_element_end(&mut self, span: Span) -> Result<(), Self::Error> {
        let _ = span;
        Ok(())
    }

    /// End tag: `</name>`.
    /// `name` is the element name (may include a namespace prefix and `:`).
    fn end_tag(&mut self, name: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (name, span);
        Ok(())
    }

    // --- Text events ---

    /// Character data between markup.
    ///
    /// May be called multiple times for a single run of text content -
    /// interleaved with [`entity_ref`](Self::entity_ref) and
    /// [`char_ref`](Self::char_ref) calls at reference boundaries, and
    /// split at buffer boundaries. For example, `a&amp;b` produces
    /// `characters("a")`, `entity_ref("amp")`, `characters("b")`.
    ///
    /// Each `text` slice is guaranteed to not split a multi-byte UTF-8 character
    /// at its boundaries (except when `is_final` is true and the document ends
    /// mid-sequence). If the input is valid UTF-8, `std::str::from_utf8(text)`
    /// will always succeed.
    fn characters(&mut self, text: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (text, span);
        Ok(())
    }

    /// Entity reference in text content: `&name;`.
    /// `name` is the entity name without `&` and `;`.
    fn entity_ref(&mut self, name: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (name, span);
        Ok(())
    }

    /// Character reference in text content: `&#NNN;` or `&#xHHH;`.
    /// `value` is the raw text between `&#` and `;` (e.g. `"60"` or `"x3C"`).
    fn char_ref(&mut self, value: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (value, span);
        Ok(())
    }

    // --- CDATA ---

    /// Start of a CDATA section: `<![CDATA[`.
    fn cdata_start(&mut self, span: Span) -> Result<(), Self::Error> {
        let _ = span;
        Ok(())
    }

    /// Content within a CDATA section.
    /// Called zero or more times for a single CDATA section - zero for
    /// empty sections (`<![CDATA[]]>`), and possibly more than once when
    /// content spans buffer boundaries. Consecutive calls have contiguous
    /// spans.
    fn cdata_content(&mut self, text: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (text, span);
        Ok(())
    }

    /// End of a CDATA section: `]]>`.
    fn cdata_end(&mut self, span: Span) -> Result<(), Self::Error> {
        let _ = span;
        Ok(())
    }

    // --- Comments ---

    /// Start of a comment: `<!--`.
    fn comment_start(&mut self, span: Span) -> Result<(), Self::Error> {
        let _ = span;
        Ok(())
    }

    /// Content within a comment.
    /// Called zero or more times for a single comment - zero for empty
    /// comments (`<!---->`), and possibly more than once when content
    /// spans buffer boundaries. Consecutive calls have contiguous spans.
    fn comment_content(&mut self, text: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (text, span);
        Ok(())
    }

    /// End of a comment: `-->`.
    fn comment_end(&mut self, span: Span) -> Result<(), Self::Error> {
        let _ = span;
        Ok(())
    }

    // --- XML Declaration ---

    /// XML declaration: `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`.
    ///
    /// Fired instead of PI callbacks when `<?xml ...?>` appears at the document
    /// start. Per the XML specification, the XML declaration is NOT a processing
    /// instruction - it is a distinct construct.
    ///
    /// `version` is always present (e.g. `b"1.0"`).
    /// `encoding` and `standalone` are optional.
    fn xml_declaration(
        &mut self,
        version: &[u8],
        encoding: Option<&[u8]>,
        standalone: Option<bool>,
        span: Span,
    ) -> Result<(), Self::Error> {
        let _ = (version, encoding, standalone, span);
        Ok(())
    }

    // --- Processing Instructions ---

    /// Start of a processing instruction: `<?target`.
    /// `target` is the PI target name.
    fn pi_start(&mut self, target: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (target, span);
        Ok(())
    }

    /// Content of a processing instruction (everything between target and `?>`).
    /// Called zero or more times for a single PI - zero when the PI has no
    /// content (`<?target?>`), and possibly more than once when content
    /// spans buffer boundaries. Consecutive calls have contiguous spans.
    fn pi_content(&mut self, data: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (data, span);
        Ok(())
    }

    /// End of a processing instruction: `?>`.
    fn pi_end(&mut self, span: Span) -> Result<(), Self::Error> {
        let _ = span;
        Ok(())
    }

    // --- DOCTYPE ---

    /// Start of a DOCTYPE declaration: `<!DOCTYPE name`.
    /// `name` is the root element name.
    fn doctype_start(&mut self, name: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (name, span);
        Ok(())
    }

    /// Content within a DOCTYPE declaration (opaque).
    /// Called zero or more times for a single DOCTYPE - zero for simple
    /// declarations (`<!DOCTYPE html>`), and possibly more than once when
    /// content spans buffer boundaries. Consecutive calls have contiguous
    /// spans.
    fn doctype_content(&mut self, content: &[u8], span: Span) -> Result<(), Self::Error> {
        let _ = (content, span);
        Ok(())
    }

    /// End of a DOCTYPE declaration: `>`.
    fn doctype_end(&mut self, span: Span) -> Result<(), Self::Error> {
        let _ = span;
        Ok(())
    }
}