Skip to main content

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<'_> {}