jsonx_lib/reader.rs
1//! The pull reader: a document as a stream of events, without building a tree.
2
3use alloc::{borrow::Cow, vec::Vec};
4use core::iter::FusedIterator;
5
6use crate::{
7 DuplicateKeys, Limits, Number, Value,
8 error::{Error, ErrorKind},
9 lexer, parser, scan,
10};
11
12/// One step through a document, from [`Reader::next_event`].
13///
14/// A document is one value. A scalar value is one event; an array is
15/// [`StartArray`](Self::StartArray), its items, then [`EndArray`](Self::EndArray);
16/// an object is [`StartObject`](Self::StartObject), then for each member a
17/// [`Key`](Self::Key) followed by the member's value, then
18/// [`EndObject`](Self::EndObject).
19///
20/// # Examples
21///
22/// ```
23/// use jsonx_lib::{Event, Reader};
24///
25/// let events: Vec<Event> = Reader::new(r#"{"a": [true]}"#).collect::<Result<_, _>>()?;
26/// assert_eq!(events, [
27/// Event::StartObject,
28/// Event::Key("a".into()),
29/// Event::StartArray,
30/// Event::Bool(true),
31/// Event::EndArray,
32/// Event::EndObject,
33/// ]);
34/// # Ok::<(), jsonx_lib::Error>(())
35/// ```
36#[derive(Clone, Debug, PartialEq, Eq)]
37pub enum Event<'a> {
38 /// `{`: an object begins.
39 StartObject,
40 /// `}`: the innermost open object ends.
41 EndObject,
42 /// `[`: an array begins.
43 StartArray,
44 /// `]`: the innermost open array ends.
45 EndArray,
46 /// A member's key (the `:` after it has been read too). Borrowed unless it
47 /// had escapes.
48 Key(Cow<'a, str>),
49 /// A string value. Borrowed unless it had escapes.
50 String(Cow<'a, str>),
51 /// A number value, as its exact text.
52 Number(Number<'a>),
53 /// `true` or `false`.
54 Bool(bool),
55 /// `null`.
56 Null,
57}
58
59/// What the reader expects next.
60#[derive(Clone, Copy, Debug, PartialEq, Eq)]
61enum State {
62 /// A value: at the start, or after a member's `:`.
63 Value,
64 /// A value after `,` in an array; `]` here is a trailing comma.
65 Element,
66 /// Just after `[`: a value or `]`.
67 ArrayFirst,
68 /// After an array item: `,` or `]`.
69 ArrayNext,
70 /// Just after `{`: a key or `}`.
71 ObjectFirst,
72 /// After `,` in an object: a key; `}` here is a trailing comma.
73 Key,
74 /// After a member's value: `,` or `}`.
75 ObjectNext,
76 /// The document's value is complete: only whitespace may follow.
77 End,
78 /// The end was reached and reported.
79 Done,
80}
81
82/// Which container is open.
83#[derive(Clone, Copy, Debug, PartialEq, Eq)]
84enum Container {
85 Array,
86 Object,
87}
88
89/// A pull parser: reads a document one [`Event`] at a time, building nothing.
90///
91/// The reader is the layer every parse in this crate goes through: it checks
92/// the full RFC 8259 grammar and every budget in [`Limits`] as it goes, with
93/// the same errors and byte offsets as [`parse`](crate::parse). Use it to pick
94/// a few fields out of a large document, to stream a document's contents
95/// somewhere without holding a tree, or to keep part of a message as raw text
96/// to be read later ([`read_raw`](Self::read_raw)).
97///
98/// The reader works over a complete document held in memory, and borrows
99/// strings and numbers from it exactly as [`parse`](crate::parse) does.
100/// Reading is iterative: depth costs one byte of reader state per level, never
101/// stack. The reader does not look for duplicate keys, which needs memory
102/// proportional to an object's size; [`read_value`](Self::read_value) applies
103/// the configured [`DuplicateKeys`] policy to the values it builds.
104///
105/// After an error the reader is finished: every later call returns the same
106/// error.
107///
108/// # Examples
109///
110/// Read a JSON-RPC envelope, keeping `params` as raw text for later:
111///
112/// ```
113/// use jsonx_lib::{Event, Reader};
114///
115/// let message = r#"{"jsonrpc": "2.0", "id": 4, "method": "hover", "params": {"line": 3}}"#;
116/// let mut reader = Reader::new(message);
117/// let (mut method, mut params) = (None, None);
118/// assert_eq!(reader.next_event()?, Some(Event::StartObject));
119/// while let Some(Event::Key(key)) = reader.next_event()? {
120/// match &*key {
121/// "method" => method = reader.read_value()?,
122/// "params" => params = reader.read_raw()?,
123/// _ => { let _skipped = reader.read_raw()?; }
124/// }
125/// }
126/// reader.finish()?; // the rest of the document must be valid too
127/// assert_eq!(method.as_ref().and_then(|m| m.as_str()), Some("hover"));
128/// assert_eq!(params, Some(r#"{"line": 3}"#));
129/// # Ok::<(), jsonx_lib::Error>(())
130/// ```
131#[derive(Clone, Debug)]
132pub struct Reader<'a> {
133 src: &'a str,
134 pos: usize,
135 /// Where the most recent event's token began.
136 last: usize,
137 state: State,
138 stack: Vec<Container>,
139 elements: usize,
140 limits: Limits,
141 duplicates: DuplicateKeys,
142 failed: Option<Error>,
143 /// Set while [`Reader::read_raw`] skips a value: strings are not decoded.
144 skipping: bool,
145}
146
147impl<'a> Reader<'a> {
148 /// A reader over `text` with the default [`Limits`].
149 ///
150 /// # Examples
151 ///
152 /// ```
153 /// use jsonx_lib::{Event, Reader};
154 ///
155 /// let mut r = Reader::new(" 42 ");
156 /// assert_eq!(r.next_event()?.map(|e| e == Event::Number(42.into())), Some(true));
157 /// assert_eq!(r.next_event()?, None);
158 /// # Ok::<(), jsonx_lib::Error>(())
159 /// ```
160 #[must_use]
161 pub fn new(text: &'a str) -> Self {
162 Self::with_config(text, Limits::new(), DuplicateKeys::Error)
163 }
164
165 /// A reader with the given budgets and duplicate-key policy; see
166 /// [`Parser::reader`](crate::Parser::reader).
167 pub(crate) fn with_config(text: &'a str, limits: Limits, duplicates: DuplicateKeys) -> Self {
168 let failed = (text.len() > limits.max_input_bytes)
169 .then(|| Error::new(ErrorKind::InputTooLarge, limits.max_input_bytes));
170 Self {
171 src: text,
172 pos: 0,
173 last: 0,
174 state: State::Value,
175 stack: Vec::new(),
176 elements: 0,
177 limits,
178 duplicates,
179 failed,
180 skipping: false,
181 }
182 }
183
184 /// Reads the next event, or `Ok(None)` once the document's value is
185 /// complete and nothing but whitespace follows it.
186 ///
187 /// # Errors
188 ///
189 /// The first syntax error or exceeded budget, at its byte offset (see
190 /// [`Error`]). Once an error is returned, every later call returns it too.
191 ///
192 /// # Examples
193 ///
194 /// ```
195 /// use jsonx_lib::{ErrorKind, Event, Reader};
196 ///
197 /// let mut r = Reader::new("[1,]");
198 /// assert_eq!(r.next_event()?, Some(Event::StartArray));
199 /// assert!(r.next_event()?.is_some()); // 1
200 /// let err = r.next_event().unwrap_err();
201 /// assert_eq!((err.kind(), err.offset()), (ErrorKind::TrailingComma, 3));
202 /// # Ok::<(), jsonx_lib::Error>(())
203 /// ```
204 pub fn next_event(&mut self) -> Result<Option<Event<'a>>, Error> {
205 if let Some(e) = self.failed {
206 return Err(e);
207 }
208 self.step().inspect_err(|&e| self.failed = Some(e))
209 }
210
211 /// Reads the next value whole and returns its exact source text, without
212 /// decoding or allocating anything.
213 ///
214 /// Call it where a value comes next: at the start, after a [`Key`](Event::Key),
215 /// or between array items. The value is fully validated. If no value comes
216 /// next (the current array or object ends, or the document already ended),
217 /// returns `Ok(None)` and consumes nothing, so the next
218 /// [`next_event`](Self::next_event) returns the end event as usual. Calling
219 /// it where a key comes next also returns `Ok(None)`.
220 ///
221 /// The text is a slice of the input: it can be stored, compared, or parsed
222 /// later, as `serde_json`'s `RawValue` is used.
223 ///
224 /// # Errors
225 ///
226 /// As [`next_event`](Self::next_event), for any error inside the value.
227 ///
228 /// # Examples
229 ///
230 /// ```
231 /// use jsonx_lib::{Event, Reader};
232 ///
233 /// let mut r = Reader::new(r#"[{"deep": [1, 2]}, "x"]"#);
234 /// assert_eq!(r.next_event()?, Some(Event::StartArray));
235 /// assert_eq!(r.read_raw()?, Some(r#"{"deep": [1, 2]}"#));
236 /// assert_eq!(r.read_raw()?, Some(r#""x""#));
237 /// assert_eq!(r.read_raw()?, None); // the array ends here
238 /// assert_eq!(r.next_event()?, Some(Event::EndArray));
239 /// # Ok::<(), jsonx_lib::Error>(())
240 /// ```
241 pub fn read_raw(&mut self) -> Result<Option<&'a str>, Error> {
242 if let Some(e) = self.failed {
243 return Err(e);
244 }
245 if !self.at_value()? {
246 return Ok(None);
247 }
248 self.skipping = true;
249 let result = self.skip_value();
250 self.skipping = false;
251 result.map(Some)
252 }
253
254 /// Reads the next value whole and builds it as a [`Value`], applying the
255 /// reader's [`DuplicateKeys`] policy.
256 ///
257 /// Positioning is as for [`read_raw`](Self::read_raw): `Ok(None)`, with
258 /// nothing consumed, when no value comes next.
259 ///
260 /// # Errors
261 ///
262 /// As [`next_event`](Self::next_event), plus [`ErrorKind::DuplicateKey`]
263 /// under [`DuplicateKeys::Error`].
264 ///
265 /// # Examples
266 ///
267 /// ```
268 /// use jsonx_lib::{Event, Reader};
269 ///
270 /// let mut r = Reader::new(r#"{"skip": [0], "keep": {"a": 1}}"#);
271 /// r.next_event()?; // {
272 /// r.next_event()?; // "skip"
273 /// r.read_raw()?;
274 /// assert_eq!(r.next_event()?, Some(Event::Key("keep".into())));
275 /// let keep = r.read_value()?.unwrap_or_default();
276 /// assert_eq!(keep["a"], 1);
277 /// # Ok::<(), jsonx_lib::Error>(())
278 /// ```
279 pub fn read_value(&mut self) -> Result<Option<Value<'a>>, Error> {
280 if let Some(e) = self.failed {
281 return Err(e);
282 }
283 if !self.at_value()? {
284 return Ok(None);
285 }
286 let duplicates = self.duplicates;
287 parser::build(self, duplicates)
288 .inspect_err(|&e| self.failed = Some(e))
289 .map(Some)
290 }
291
292 /// Reads to the end of the document, checking that the rest of it is
293 /// valid and that nothing but whitespace follows its value.
294 ///
295 /// # Errors
296 ///
297 /// The first error in the rest of the document.
298 ///
299 /// # Examples
300 ///
301 /// ```
302 /// use jsonx_lib::{ErrorKind, Event, Reader};
303 ///
304 /// let mut r = Reader::new(r#"{"id": 1, "x": [} "#);
305 /// assert_eq!(r.next_event()?, Some(Event::StartObject));
306 /// let err = r.finish().unwrap_err();
307 /// assert_eq!((err.kind(), err.offset()), (ErrorKind::ExpectedValue, 16));
308 /// # Ok::<(), jsonx_lib::Error>(())
309 /// ```
310 pub fn finish(mut self) -> Result<(), Error> {
311 while self.next_event()?.is_some() {}
312 Ok(())
313 }
314
315 /// The number of arrays and objects open at this point.
316 ///
317 /// # Examples
318 ///
319 /// ```
320 /// let mut r = jsonx_lib::Reader::new("[[]]");
321 /// r.next_event()?;
322 /// r.next_event()?;
323 /// assert_eq!(r.depth(), 2);
324 /// # Ok::<(), jsonx_lib::Error>(())
325 /// ```
326 #[inline]
327 #[must_use]
328 pub fn depth(&self) -> usize {
329 self.stack.len()
330 }
331
332 /// The byte offset just past the input consumed so far.
333 ///
334 /// # Examples
335 ///
336 /// ```
337 /// let mut r = jsonx_lib::Reader::new("[10, 20]");
338 /// r.next_event()?;
339 /// r.next_event()?;
340 /// assert_eq!(r.offset(), 3);
341 /// # Ok::<(), jsonx_lib::Error>(())
342 /// ```
343 #[inline]
344 #[must_use]
345 pub fn offset(&self) -> usize {
346 self.pos
347 }
348
349 /// The byte offset where the most recent event's token began: the quote of
350 /// a key or string, the first byte of a number or literal, the bracket or
351 /// brace of a start or end event. Useful for pointing a diagnostic of your
352 /// own at the value it is about.
353 ///
354 /// # Examples
355 ///
356 /// ```
357 /// let mut r = jsonx_lib::Reader::new(r#"{ "a" : 1 }"#);
358 /// r.next_event()?;
359 /// r.next_event()?;
360 /// assert_eq!(r.event_offset(), 2); // the key's opening quote
361 /// r.next_event()?;
362 /// assert_eq!(r.event_offset(), 8); // the number
363 /// # Ok::<(), jsonx_lib::Error>(())
364 /// ```
365 #[inline]
366 #[must_use]
367 pub fn event_offset(&self) -> usize {
368 self.last
369 }
370
371 // ---- internals -----------------------------------------------------------
372
373 #[inline]
374 fn bytes(&self) -> &'a [u8] {
375 self.src.as_bytes()
376 }
377
378 #[inline]
379 fn skip_whitespace(&mut self) {
380 let bytes = self.bytes();
381 while bytes
382 .get(self.pos)
383 .copied()
384 .is_some_and(scan::is_whitespace)
385 {
386 self.pos += 1;
387 }
388 }
389
390 #[inline]
391 fn end_error(&self) -> Error {
392 Error::new(ErrorKind::UnexpectedEnd, self.src.len())
393 }
394
395 /// Moves past whitespace and a separating `,` and reports whether a value
396 /// comes next, without consuming any token of the value.
397 fn at_value(&mut self) -> Result<bool, Error> {
398 self.skip_whitespace();
399 let next = self.bytes().get(self.pos).copied();
400 Ok(match self.state {
401 State::Value | State::Element => true,
402 State::ArrayFirst => next != Some(b']'),
403 State::ArrayNext if next == Some(b',') => {
404 self.pos += 1;
405 self.state = State::Element;
406 true
407 }
408 _ => false,
409 })
410 }
411
412 /// Consumes one whole value (the reader is positioned at it) and returns
413 /// its text.
414 fn skip_value(&mut self) -> Result<&'a str, Error> {
415 let depth = self.stack.len();
416 let first = self.next_event()?;
417 let start = self.last;
418 if matches!(first, Some(Event::StartArray | Event::StartObject)) {
419 while self.stack.len() > depth {
420 if self.next_event()?.is_none() {
421 return Err(self.end_error());
422 }
423 }
424 }
425 Ok(self.src.get(start..self.pos).unwrap_or(""))
426 }
427
428 /// The state after a value completes in the current container.
429 #[inline]
430 fn after_value(&mut self) {
431 self.state = match self.stack.last() {
432 None => State::End,
433 Some(Container::Array) => State::ArrayNext,
434 Some(Container::Object) => State::ObjectNext,
435 };
436 }
437
438 /// Closes the innermost container, whose closing byte is at `at`.
439 #[inline]
440 fn close(&mut self, at: usize, event: Event<'a>) -> Event<'a> {
441 self.pos = at + 1;
442 self.last = at;
443 let _closed = self.stack.pop();
444 self.after_value();
445 event
446 }
447
448 fn step(&mut self) -> Result<Option<Event<'a>>, Error> {
449 loop {
450 self.skip_whitespace();
451 let at = self.pos;
452 let next = self.bytes().get(at).copied();
453 let err = |kind| Err(Error::new(kind, at));
454 match self.state {
455 State::Value | State::Element | State::ArrayFirst => match next {
456 None => return Err(self.end_error()),
457 Some(b']') if self.state == State::ArrayFirst => {
458 return Ok(Some(self.close(at, Event::EndArray)));
459 }
460 Some(b']') if self.state == State::Element => {
461 return err(ErrorKind::TrailingComma);
462 }
463 Some(b) => return self.value(b, at).map(Some),
464 },
465 State::ArrayNext => match next {
466 None => return Err(self.end_error()),
467 Some(b',') => {
468 self.pos += 1;
469 self.state = State::Element;
470 }
471 Some(b']') => return Ok(Some(self.close(at, Event::EndArray))),
472 Some(_) => return err(ErrorKind::ExpectedCommaOrBracket),
473 },
474 State::ObjectFirst | State::Key => match next {
475 None => return Err(self.end_error()),
476 Some(b'"') => return self.key(at).map(Some),
477 Some(b'}') if self.state == State::ObjectFirst => {
478 return Ok(Some(self.close(at, Event::EndObject)));
479 }
480 Some(b'}') => return err(ErrorKind::TrailingComma),
481 Some(_) => return err(ErrorKind::ExpectedKey),
482 },
483 State::ObjectNext => match next {
484 None => return Err(self.end_error()),
485 Some(b',') => {
486 self.pos += 1;
487 self.state = State::Key;
488 }
489 Some(b'}') => return Ok(Some(self.close(at, Event::EndObject))),
490 Some(_) => return err(ErrorKind::ExpectedCommaOrBrace),
491 },
492 State::End => {
493 return match next {
494 None => {
495 self.state = State::Done;
496 Ok(None)
497 }
498 Some(_) => err(ErrorKind::TrailingCharacters),
499 };
500 }
501 State::Done => return Ok(None),
502 }
503 }
504 }
505
506 /// Counts one more value, refusing it if the budget is spent.
507 #[inline]
508 fn count_value(&mut self, at: usize) -> Result<(), Error> {
509 if self.elements >= self.limits.max_elements {
510 return Err(Error::new(ErrorKind::TooManyElements, at));
511 }
512 self.elements += 1;
513 Ok(())
514 }
515
516 /// Reads the value starting with byte `b` at `at`.
517 fn value(&mut self, b: u8, at: usize) -> Result<Event<'a>, Error> {
518 let bytes = self.bytes();
519 let event = match b {
520 b'{' | b'[' => {
521 self.count_value(at)?;
522 if self.stack.len() >= self.limits.max_depth {
523 return Err(Error::new(ErrorKind::DepthLimitExceeded, at));
524 }
525 self.pos = at + 1;
526 if b == b'{' {
527 self.stack.push(Container::Object);
528 self.state = State::ObjectFirst;
529 Event::StartObject
530 } else {
531 self.stack.push(Container::Array);
532 self.state = State::ArrayFirst;
533 Event::StartArray
534 }
535 }
536 b'"' => {
537 self.count_value(at)?;
538 Event::String(self.string(at)?)
539 }
540 b'-' | b'0'..=b'9' => {
541 self.count_value(at)?;
542 let end = lexer::scan_number(bytes, at, self.limits.max_number_bytes)?;
543 self.pos = end;
544 self.after_value();
545 Event::Number(Number::from_valid(self.src.get(at..end).unwrap_or("0")))
546 }
547 b't' | b'f' | b'n' => {
548 self.count_value(at)?;
549 let (word, event): (&[u8], _) = match b {
550 b't' => (b"true", Event::Bool(true)),
551 b'f' => (b"false", Event::Bool(false)),
552 _ => (b"null", Event::Null),
553 };
554 self.pos = lexer::scan_literal(bytes, at, word)?;
555 self.after_value();
556 event
557 }
558 _ => return Err(Error::new(ErrorKind::ExpectedValue, at)),
559 };
560 self.last = at;
561 Ok(event)
562 }
563
564 /// Reads the string value whose quote is at `at`.
565 fn string(&mut self, at: usize) -> Result<Cow<'a, str>, Error> {
566 let text = self.string_body(at)?;
567 self.after_value();
568 Ok(text)
569 }
570
571 /// Reads the key whose quote is at `at`, and the `:` after it.
572 fn key(&mut self, at: usize) -> Result<Event<'a>, Error> {
573 let key = self.string_body(at)?;
574 self.skip_whitespace();
575 match self.bytes().get(self.pos) {
576 Some(b':') => self.pos += 1,
577 Some(_) => return Err(Error::new(ErrorKind::ExpectedColon, self.pos)),
578 None => return Err(self.end_error()),
579 }
580 self.state = State::Value;
581 self.last = at;
582 Ok(Event::Key(key))
583 }
584
585 /// Scans the string at `at` and returns its contents: borrowed when it has
586 /// no escapes (or while skipping), decoded otherwise.
587 fn string_body(&mut self, at: usize) -> Result<Cow<'a, str>, Error> {
588 let token = lexer::scan_string(self.bytes(), at, self.limits.max_string_bytes)?;
589 self.pos = token.end;
590 let body = self.src.get(at + 1..token.end - 1).unwrap_or("");
591 Ok(if token.escaped && !self.skipping {
592 Cow::Owned(lexer::decode(body))
593 } else {
594 Cow::Borrowed(body)
595 })
596 }
597}
598
599impl<'a> Iterator for Reader<'a> {
600 type Item = Result<Event<'a>, Error>;
601
602 /// The next event; after the end or an error, `None`. An error is yielded
603 /// once.
604 fn next(&mut self) -> Option<Self::Item> {
605 if self.failed.is_some() && self.state == State::Done {
606 return None;
607 }
608 match self.next_event() {
609 Ok(Some(event)) => Some(Ok(event)),
610 Ok(None) => None,
611 Err(e) => {
612 // Yield the error once, then stop.
613 self.state = State::Done;
614 Some(Err(e))
615 }
616 }
617 }
618}
619
620impl FusedIterator for Reader<'_> {}