Source file src/encoding/json/jsontext/decode.go

     1  // Copyright 2020 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  //go:build goexperiment.jsonv2
     6  
     7  package jsontext
     8  
     9  import (
    10  	"bytes"
    11  	"errors"
    12  	"io"
    13  
    14  	"encoding/json/internal/jsonflags"
    15  	"encoding/json/internal/jsonopts"
    16  	"encoding/json/internal/jsonwire"
    17  )
    18  
    19  // NOTE: The logic for decoding is complicated by the fact that reading from
    20  // an io.Reader into a temporary buffer means that the buffer may contain a
    21  // truncated portion of some valid input, requiring the need to fetch more data.
    22  //
    23  // This file is structured in the following way:
    24  //
    25  //   - consumeXXX functions parse an exact JSON token from a []byte.
    26  //     If the buffer appears truncated, then it returns io.ErrUnexpectedEOF.
    27  //     The consumeSimpleXXX functions are so named because they only handle
    28  //     a subset of the grammar for the JSON token being parsed.
    29  //     They do not handle the full grammar to keep these functions inlinable.
    30  //
    31  //   - Decoder.consumeXXX methods parse the next JSON token from Decoder.buf,
    32  //     automatically fetching more input if necessary. These methods take
    33  //     a position relative to the start of Decoder.buf as an argument and
    34  //     return the end of the consumed JSON token as a position,
    35  //     also relative to the start of Decoder.buf.
    36  //
    37  //   - In the event of an I/O error or state machine violations,
    38  //     the implementation avoids mutating the state of Decoder
    39  //     (aside from the book-keeping needed to implement Decoder.fetch).
    40  //     For this reason, only Decoder.ReadToken and Decoder.ReadValue are
    41  //     responsible for updating Decoder.prevStart and Decoder.prevEnd.
    42  //
    43  //   - For performance, much of the implementation uses the pattern of calling
    44  //     the inlinable consumeXXX functions first, and if more work is necessary,
    45  //     then it calls the slower Decoder.consumeXXX methods.
    46  //     TODO: Revisit this pattern if the Go compiler provides finer control
    47  //     over exactly which calls are inlined or not.
    48  
    49  // Decoder is a streaming decoder for raw JSON tokens and values.
    50  // It is used to read a stream of top-level JSON values,
    51  // each separated by optional whitespace characters.
    52  //
    53  // [Decoder.ReadToken] and [Decoder.ReadValue] calls may be interleaved.
    54  // For example, the following JSON value:
    55  //
    56  //	{"name":"value","array":[null,false,true,3.14159],"object":{"k":"v"}}
    57  //
    58  // can be parsed with the following calls (ignoring errors for brevity):
    59  //
    60  //	d.ReadToken() // {
    61  //	d.ReadToken() // "name"
    62  //	d.ReadToken() // "value"
    63  //	d.ReadValue() // "array"
    64  //	d.ReadToken() // [
    65  //	d.ReadToken() // null
    66  //	d.ReadToken() // false
    67  //	d.ReadValue() // true
    68  //	d.ReadToken() // 3.14159
    69  //	d.ReadToken() // ]
    70  //	d.ReadValue() // "object"
    71  //	d.ReadValue() // {"k":"v"}
    72  //	d.ReadToken() // }
    73  //
    74  // The above is one of many possible sequences of calls and
    75  // may not represent the most sensible method to call for any given token/value.
    76  // For example, it is probably more common to call [Decoder.ReadToken] to obtain a
    77  // string token for object names.
    78  type Decoder struct {
    79  	s decoderState
    80  }
    81  
    82  // decoderState is the low-level state of Decoder.
    83  // It has exported fields and methods for use by the "json" package.
    84  type decoderState struct {
    85  	state
    86  	decodeBuffer
    87  	jsonopts.Struct
    88  
    89  	StringCache *[256]string // only used when unmarshaling; identical to json.stringCache
    90  }
    91  
    92  // decodeBuffer is a buffer split into 4 segments:
    93  //
    94  //   - buf[0:prevEnd]         // already read portion of the buffer
    95  //   - buf[prevStart:prevEnd] // previously read value
    96  //   - buf[prevEnd:len(buf)]  // unread portion of the buffer
    97  //   - buf[len(buf):cap(buf)] // unused portion of the buffer
    98  //
    99  // Invariants:
   100  //
   101  //	0 ≤ prevStart ≤ prevEnd ≤ len(buf) ≤ cap(buf)
   102  type decodeBuffer struct {
   103  	peekPos int   // non-zero if valid offset into buf for start of next token
   104  	peekErr error // implies peekPos is -1
   105  
   106  	buf       []byte // may alias rd if it is a bytes.Buffer
   107  	prevStart int
   108  	prevEnd   int
   109  
   110  	// baseOffset is added to prevStart and prevEnd to obtain
   111  	// the absolute offset relative to the start of io.Reader stream.
   112  	baseOffset int64
   113  
   114  	rd io.Reader
   115  }
   116  
   117  // NewDecoder constructs a new streaming decoder reading from r.
   118  //
   119  // If r is a [bytes.Buffer], then the decoder parses directly from the buffer
   120  // without first copying the contents to an intermediate buffer.
   121  // Additional writes to the buffer must not occur while the decoder is in use.
   122  func NewDecoder(r io.Reader, opts ...Options) *Decoder {
   123  	d := new(Decoder)
   124  	d.Reset(r, opts...)
   125  	return d
   126  }
   127  
   128  // Reset resets a decoder such that it is reading afresh from r and
   129  // configured with the provided options. Reset must not be called on
   130  // a Decoder passed to the [encoding/json/v2.UnmarshalerFrom.UnmarshalJSONFrom] method
   131  // or the [encoding/json/v2.UnmarshalFromFunc] function.
   132  func (d *Decoder) Reset(r io.Reader, opts ...Options) {
   133  	switch {
   134  	case d == nil:
   135  		panic("jsontext: invalid nil Decoder")
   136  	case r == nil:
   137  		panic("jsontext: invalid nil io.Reader")
   138  	case d.s.Flags.Get(jsonflags.WithinArshalCall):
   139  		panic("jsontext: cannot reset Decoder passed to json.UnmarshalerFrom")
   140  	}
   141  	// Reuse the buffer if it does not alias a previous [bytes.Buffer].
   142  	b := d.s.buf[:0]
   143  	if _, ok := d.s.rd.(*bytes.Buffer); ok {
   144  		b = nil
   145  	}
   146  	d.s.reset(b, r, opts...)
   147  }
   148  
   149  func (d *decoderState) reset(b []byte, r io.Reader, opts ...Options) {
   150  	d.state.reset()
   151  	d.decodeBuffer = decodeBuffer{buf: b, rd: r}
   152  	opts2 := jsonopts.Struct{} // avoid mutating d.Struct in case it is part of opts
   153  	opts2.Join(opts...)
   154  	d.Struct = opts2
   155  }
   156  
   157  // Options returns the options used to construct the decoder and
   158  // may additionally contain semantic options passed to a
   159  // [encoding/json/v2.UnmarshalDecode] call.
   160  //
   161  // If operating within
   162  // a [encoding/json/v2.UnmarshalerFrom.UnmarshalJSONFrom] method call or
   163  // a [encoding/json/v2.UnmarshalFromFunc] function call,
   164  // then the returned options are only valid within the call.
   165  func (d *Decoder) Options() Options {
   166  	return &d.s.Struct
   167  }
   168  
   169  func (d *decoderState) options() *jsonopts.Struct { return &d.Struct }
   170  
   171  var errBufferWriteAfterNext = errors.New("invalid bytes.Buffer.Write call after calling bytes.Buffer.Next")
   172  
   173  // fetch reads at least 1 byte from the underlying io.Reader.
   174  // It returns io.ErrUnexpectedEOF if zero bytes were read and io.EOF was seen.
   175  func (d *decoderState) fetch() error {
   176  	if d.rd == nil {
   177  		return io.ErrUnexpectedEOF
   178  	}
   179  
   180  	// Inform objectNameStack that we are about to fetch new buffer content.
   181  	d.Names.copyQuotedBuffer(d.buf)
   182  
   183  	// Specialize bytes.Buffer for better performance.
   184  	if bb, ok := d.rd.(*bytes.Buffer); ok {
   185  		switch {
   186  		case bb.Len() == 0:
   187  			return io.ErrUnexpectedEOF
   188  		case len(d.buf) == 0:
   189  			d.buf = bb.Next(bb.Len()) // "read" all data in the buffer
   190  			return nil
   191  		default:
   192  			// This only occurs if a partially filled bytes.Buffer was provided
   193  			// and more data is written to it while Decoder is reading from it.
   194  			// This practice will lead to data corruption since future writes
   195  			// may overwrite the contents of the current buffer.
   196  			//
   197  			// The user is trying to use a bytes.Buffer as a pipe,
   198  			// but a bytes.Buffer is a poor implementation of a pipe,
   199  			// the purpose-built io.Pipe should be used instead.
   200  			return &ioError{action: "read", err: errBufferWriteAfterNext}
   201  		}
   202  	}
   203  
   204  	// Allocate initial buffer if empty.
   205  	if cap(d.buf) == 0 {
   206  		d.buf = make([]byte, 0, 64)
   207  	}
   208  
   209  	// Check whether to grow the buffer.
   210  	const maxBufferSize = 4 << 10
   211  	const growthSizeFactor = 2 // higher value is faster
   212  	const growthRateFactor = 2 // higher value is slower
   213  	// By default, grow if below the maximum buffer size.
   214  	grow := cap(d.buf) <= maxBufferSize/growthSizeFactor
   215  	// Growing can be expensive, so only grow
   216  	// if a sufficient number of bytes have been processed.
   217  	grow = grow && int64(cap(d.buf)) < d.previousOffsetEnd()/growthRateFactor
   218  	// If prevStart==0, then fetch was called in order to fetch more data
   219  	// to finish consuming a large JSON value contiguously.
   220  	// Grow if less than 25% of the remaining capacity is available.
   221  	// Note that this may cause the input buffer to exceed maxBufferSize.
   222  	grow = grow || (d.prevStart == 0 && len(d.buf) >= 3*cap(d.buf)/4)
   223  
   224  	if grow {
   225  		// Allocate a new buffer and copy the contents of the old buffer over.
   226  		// TODO: Provide a hard limit on the maximum internal buffer size?
   227  		buf := make([]byte, 0, cap(d.buf)*growthSizeFactor)
   228  		d.buf = append(buf, d.buf[d.prevStart:]...)
   229  	} else {
   230  		// Move unread portion of the data to the front.
   231  		n := copy(d.buf[:cap(d.buf)], d.buf[d.prevStart:])
   232  		d.buf = d.buf[:n]
   233  	}
   234  	d.baseOffset += int64(d.prevStart)
   235  	d.prevEnd -= d.prevStart
   236  	d.prevStart = 0
   237  
   238  	// Read more data into the internal buffer.
   239  	for {
   240  		n, err := d.rd.Read(d.buf[len(d.buf):cap(d.buf)])
   241  		switch {
   242  		case n > 0:
   243  			d.buf = d.buf[:len(d.buf)+n]
   244  			return nil // ignore errors if any bytes are read
   245  		case err == io.EOF:
   246  			return io.ErrUnexpectedEOF
   247  		case err != nil:
   248  			return &ioError{action: "read", err: err}
   249  		default:
   250  			continue // Read returned (0, nil)
   251  		}
   252  	}
   253  }
   254  
   255  const invalidateBufferByte = '#' // invalid starting character for JSON grammar
   256  
   257  // invalidatePreviousRead invalidates buffers returned by Peek and Read calls
   258  // so that the first byte is an invalid character.
   259  // This Hyrum-proofs the API against faulty application code that assumes
   260  // values returned by ReadValue remain valid past subsequent Read calls.
   261  func (d *decodeBuffer) invalidatePreviousRead() {
   262  	// Avoid mutating the buffer if d.rd is nil which implies that d.buf
   263  	// is provided by the user code and may not expect mutations.
   264  	isBytesBuffer := func(r io.Reader) bool {
   265  		_, ok := r.(*bytes.Buffer)
   266  		return ok
   267  	}
   268  	if d.rd != nil && !isBytesBuffer(d.rd) && d.prevStart < d.prevEnd && uint(d.prevStart) < uint(len(d.buf)) {
   269  		d.buf[d.prevStart] = invalidateBufferByte
   270  		d.prevStart = d.prevEnd
   271  	}
   272  }
   273  
   274  // needMore reports whether there are no more unread bytes.
   275  func (d *decodeBuffer) needMore(pos int) bool {
   276  	// NOTE: The arguments and logic are kept simple to keep this inlinable.
   277  	return pos == len(d.buf)
   278  }
   279  
   280  func (d *decodeBuffer) offsetAt(pos int) int64     { return d.baseOffset + int64(pos) }
   281  func (d *decodeBuffer) previousOffsetStart() int64 { return d.baseOffset + int64(d.prevStart) }
   282  func (d *decodeBuffer) previousOffsetEnd() int64   { return d.baseOffset + int64(d.prevEnd) }
   283  func (d *decodeBuffer) previousBuffer() []byte     { return d.buf[d.prevStart:d.prevEnd] }
   284  func (d *decodeBuffer) unreadBuffer() []byte       { return d.buf[d.prevEnd:len(d.buf)] }
   285  
   286  // PreviousTokenOrValue returns the previously read token or value
   287  // unless it has been invalidated by a call to PeekKind.
   288  // If a token is just a delimiter, then this returns a 1-byte buffer.
   289  // This method is used for error reporting at the semantic layer.
   290  func (d *decodeBuffer) PreviousTokenOrValue() []byte {
   291  	b := d.previousBuffer()
   292  	// If peek was called, then the previous token or buffer is invalidated.
   293  	if d.peekPos > 0 || len(b) > 0 && b[0] == invalidateBufferByte {
   294  		return nil
   295  	}
   296  	// ReadToken does not preserve the buffer for null, bools, or delimiters.
   297  	// Manually re-construct that buffer.
   298  	if len(b) == 0 {
   299  		b = d.buf[:d.prevEnd] // entirety of the previous buffer
   300  		for _, tok := range []string{"null", "false", "true", "{", "}", "[", "]"} {
   301  			if len(b) >= len(tok) && string(b[len(b)-len(tok):]) == tok {
   302  				return b[len(b)-len(tok):]
   303  			}
   304  		}
   305  	}
   306  	return b
   307  }
   308  
   309  // PeekKind retrieves the next token kind, but does not advance the read offset.
   310  //
   311  // It returns [KindInvalid] if an error occurs. Any such error is cached until
   312  // the next read call and it is the caller's responsibility to eventually
   313  // follow up a PeekKind call with a read call.
   314  func (d *Decoder) PeekKind() Kind {
   315  	return d.s.PeekKind()
   316  }
   317  func (d *decoderState) PeekKind() Kind {
   318  	// Check whether we have a cached peek result.
   319  	if d.peekPos > 0 {
   320  		return Kind(d.buf[d.peekPos]).normalize()
   321  	}
   322  
   323  	var err error
   324  	d.invalidatePreviousRead()
   325  	pos := d.prevEnd
   326  
   327  	// Consume leading whitespace.
   328  	pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
   329  	if d.needMore(pos) {
   330  		if pos, err = d.consumeWhitespace(pos); err != nil {
   331  			if err == io.ErrUnexpectedEOF && d.Tokens.Depth() == 1 {
   332  				err = io.EOF // EOF possibly if no Tokens present after top-level value
   333  			}
   334  			d.peekPos, d.peekErr = -1, wrapSyntacticError(d, err, pos, 0)
   335  			return invalidKind
   336  		}
   337  	}
   338  
   339  	// Consume colon or comma.
   340  	var delim byte
   341  	if c := d.buf[pos]; c == ':' || c == ',' {
   342  		delim = c
   343  		pos += 1
   344  		pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
   345  		if d.needMore(pos) {
   346  			if pos, err = d.consumeWhitespace(pos); err != nil {
   347  				err = wrapSyntacticError(d, err, pos, 0)
   348  				d.peekPos, d.peekErr = -1, d.checkDelimBeforeIOError(delim, err)
   349  				return invalidKind
   350  			}
   351  		}
   352  	}
   353  	next := Kind(d.buf[pos]).normalize()
   354  	if d.Tokens.needDelim(next) != delim {
   355  		d.peekPos, d.peekErr = -1, d.checkDelim(delim, next)
   356  		return invalidKind
   357  	}
   358  
   359  	// This may set peekPos to zero, which is indistinguishable from
   360  	// the uninitialized state. While a small hit to performance, it is correct
   361  	// since ReadValue and ReadToken will disregard the cached result and
   362  	// recompute the next kind.
   363  	d.peekPos, d.peekErr = pos, nil
   364  	return next
   365  }
   366  
   367  // checkDelimBeforeIOError checks whether the delim is even valid
   368  // before returning an IO error, which occurs after the delim.
   369  func (d *decoderState) checkDelimBeforeIOError(delim byte, err error) error {
   370  	// Since an IO error occurred, we do not know what the next kind is.
   371  	// However, knowing the next kind is necessary to validate
   372  	// whether the current delim is at least potentially valid.
   373  	// Since a JSON string is always valid as the next token,
   374  	// conservatively assume that is the next kind for validation.
   375  	const next = Kind('"')
   376  	if d.Tokens.needDelim(next) != delim {
   377  		err = d.checkDelim(delim, next)
   378  	}
   379  	return err
   380  }
   381  
   382  // CountNextDelimWhitespace counts the number of upcoming bytes of
   383  // delimiter or whitespace characters.
   384  // This method is used for error reporting at the semantic layer.
   385  func (d *decoderState) CountNextDelimWhitespace() int {
   386  	d.PeekKind() // populate unreadBuffer
   387  	return len(d.unreadBuffer()) - len(bytes.TrimLeft(d.unreadBuffer(), ",: \n\r\t"))
   388  }
   389  
   390  // checkDelim checks whether delim is valid for the given next kind.
   391  func (d *decoderState) checkDelim(delim byte, next Kind) error {
   392  	where := "at start of value"
   393  	switch d.Tokens.needDelim(next) {
   394  	case delim:
   395  		return nil
   396  	case ':':
   397  		where = "after object name (expecting ':')"
   398  	case ',':
   399  		if d.Tokens.Last.isObject() {
   400  			where = "after object value (expecting ',' or '}')"
   401  		} else {
   402  			where = "after array element (expecting ',' or ']')"
   403  		}
   404  	}
   405  	pos := d.prevEnd // restore position to right after leading whitespace
   406  	pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
   407  	err := jsonwire.NewInvalidCharacterError(d.buf[pos:], where)
   408  	return wrapSyntacticError(d, err, pos, 0)
   409  }
   410  
   411  // SkipValue is semantically equivalent to calling [Decoder.ReadValue] and discarding
   412  // the result, except that memory is not wasted trying to hold the entire result.
   413  func (d *Decoder) SkipValue() error {
   414  	return d.s.SkipValue()
   415  }
   416  
   417  func (d *decoderState) SkipValue() error {
   418  	switch d.PeekKind() {
   419  	case '{', '[':
   420  		// For JSON objects and arrays, keep skipping all tokens
   421  		// until the depth matches the starting depth.
   422  		depth := d.Tokens.Depth()
   423  		for {
   424  			if _, err := d.ReadToken(); err != nil {
   425  				return err
   426  			}
   427  			if depth >= d.Tokens.Depth() {
   428  				return nil
   429  			}
   430  		}
   431  	default:
   432  		// Trying to skip a value when the next token is a '}' or ']'
   433  		// will result in an error being returned here.
   434  		var flags jsonwire.ValueFlags
   435  		if _, err := d.ReadValue(&flags); err != nil {
   436  			return err
   437  		}
   438  		return nil
   439  	}
   440  }
   441  
   442  // SkipValueRemainder skips the remainder of a value
   443  // after reading a '{' or '[' token.
   444  func (d *decoderState) SkipValueRemainder() error {
   445  	if d.Tokens.Depth()-1 > 0 && d.Tokens.Last.Length() == 0 {
   446  		for n := d.Tokens.Depth(); d.Tokens.Depth() >= n; {
   447  			if _, err := d.ReadToken(); err != nil {
   448  				return err
   449  			}
   450  		}
   451  	}
   452  	return nil
   453  }
   454  
   455  // SkipUntil skips all tokens until the state machine
   456  // is at or past the specified depth and length.
   457  func (d *decoderState) SkipUntil(depth int, length int64) error {
   458  	for d.Tokens.Depth() > depth || (d.Tokens.Depth() == depth && d.Tokens.Last.Length() < length) {
   459  		if _, err := d.ReadToken(); err != nil {
   460  			return err
   461  		}
   462  	}
   463  	return nil
   464  }
   465  
   466  // ReadToken reads the next [Token], advancing the read offset.
   467  // The returned token is only valid until the next Peek, Read, or Skip call.
   468  // It returns [io.EOF] if there are no more tokens.
   469  func (d *Decoder) ReadToken() (Token, error) {
   470  	return d.s.ReadToken()
   471  }
   472  func (d *decoderState) ReadToken() (Token, error) {
   473  	// Determine the next kind.
   474  	var err error
   475  	var next Kind
   476  	pos := d.peekPos
   477  	if pos != 0 {
   478  		// Use cached peek result.
   479  		if d.peekErr != nil {
   480  			err := d.peekErr
   481  			d.peekPos, d.peekErr = 0, nil // possibly a transient I/O error
   482  			return Token{}, err
   483  		}
   484  		next = Kind(d.buf[pos]).normalize()
   485  		d.peekPos = 0 // reset cache
   486  	} else {
   487  		d.invalidatePreviousRead()
   488  		pos = d.prevEnd
   489  
   490  		// Consume leading whitespace.
   491  		pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
   492  		if d.needMore(pos) {
   493  			if pos, err = d.consumeWhitespace(pos); err != nil {
   494  				if err == io.ErrUnexpectedEOF && d.Tokens.Depth() == 1 {
   495  					err = io.EOF // EOF possibly if no Tokens present after top-level value
   496  				}
   497  				return Token{}, wrapSyntacticError(d, err, pos, 0)
   498  			}
   499  		}
   500  
   501  		// Consume colon or comma.
   502  		var delim byte
   503  		if c := d.buf[pos]; c == ':' || c == ',' {
   504  			delim = c
   505  			pos += 1
   506  			pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
   507  			if d.needMore(pos) {
   508  				if pos, err = d.consumeWhitespace(pos); err != nil {
   509  					err = wrapSyntacticError(d, err, pos, 0)
   510  					return Token{}, d.checkDelimBeforeIOError(delim, err)
   511  				}
   512  			}
   513  		}
   514  		next = Kind(d.buf[pos]).normalize()
   515  		if d.Tokens.needDelim(next) != delim {
   516  			return Token{}, d.checkDelim(delim, next)
   517  		}
   518  	}
   519  
   520  	// Handle the next token.
   521  	var n int
   522  	switch next {
   523  	case 'n':
   524  		if jsonwire.ConsumeNull(d.buf[pos:]) == 0 {
   525  			pos, err = d.consumeLiteral(pos, "null")
   526  			if err != nil {
   527  				return Token{}, wrapSyntacticError(d, err, pos, +1)
   528  			}
   529  		} else {
   530  			pos += len("null")
   531  		}
   532  		if err = d.Tokens.appendLiteral(); err != nil {
   533  			return Token{}, wrapSyntacticError(d, err, pos-len("null"), +1) // report position at start of literal
   534  		}
   535  		d.prevStart, d.prevEnd = pos, pos
   536  		return Null, nil
   537  
   538  	case 'f':
   539  		if jsonwire.ConsumeFalse(d.buf[pos:]) == 0 {
   540  			pos, err = d.consumeLiteral(pos, "false")
   541  			if err != nil {
   542  				return Token{}, wrapSyntacticError(d, err, pos, +1)
   543  			}
   544  		} else {
   545  			pos += len("false")
   546  		}
   547  		if err = d.Tokens.appendLiteral(); err != nil {
   548  			return Token{}, wrapSyntacticError(d, err, pos-len("false"), +1) // report position at start of literal
   549  		}
   550  		d.prevStart, d.prevEnd = pos, pos
   551  		return False, nil
   552  
   553  	case 't':
   554  		if jsonwire.ConsumeTrue(d.buf[pos:]) == 0 {
   555  			pos, err = d.consumeLiteral(pos, "true")
   556  			if err != nil {
   557  				return Token{}, wrapSyntacticError(d, err, pos, +1)
   558  			}
   559  		} else {
   560  			pos += len("true")
   561  		}
   562  		if err = d.Tokens.appendLiteral(); err != nil {
   563  			return Token{}, wrapSyntacticError(d, err, pos-len("true"), +1) // report position at start of literal
   564  		}
   565  		d.prevStart, d.prevEnd = pos, pos
   566  		return True, nil
   567  
   568  	case '"':
   569  		var flags jsonwire.ValueFlags // TODO: Preserve this in Token?
   570  		if n = jsonwire.ConsumeSimpleString(d.buf[pos:]); n == 0 {
   571  			oldAbsPos := d.baseOffset + int64(pos)
   572  			pos, err = d.consumeString(&flags, pos)
   573  			newAbsPos := d.baseOffset + int64(pos)
   574  			n = int(newAbsPos - oldAbsPos)
   575  			if err != nil {
   576  				return Token{}, wrapSyntacticError(d, err, pos, +1)
   577  			}
   578  		} else {
   579  			pos += n
   580  		}
   581  		if d.Tokens.Last.NeedObjectName() {
   582  			if !d.Flags.Get(jsonflags.AllowDuplicateNames) {
   583  				if !d.Tokens.Last.isValidNamespace() {
   584  					return Token{}, wrapSyntacticError(d, errInvalidNamespace, pos-n, +1)
   585  				}
   586  				if d.Tokens.Last.isActiveNamespace() && !d.Namespaces.Last().insertQuoted(d.buf[pos-n:pos], flags.IsVerbatim()) {
   587  					err = wrapWithObjectName(ErrDuplicateName, d.buf[pos-n:pos])
   588  					return Token{}, wrapSyntacticError(d, err, pos-n, +1) // report position at start of string
   589  				}
   590  			}
   591  			d.Names.ReplaceLastQuotedOffset(pos - n) // only replace if insertQuoted succeeds
   592  		}
   593  		if err = d.Tokens.appendString(); err != nil {
   594  			return Token{}, wrapSyntacticError(d, err, pos-n, +1) // report position at start of string
   595  		}
   596  		d.prevStart, d.prevEnd = pos-n, pos
   597  		return Token{raw: &d.decodeBuffer, num: uint64(d.previousOffsetStart())}, nil
   598  
   599  	case '0':
   600  		// NOTE: Since JSON numbers are not self-terminating,
   601  		// we need to make sure that the next byte is not part of a number.
   602  		if n = jsonwire.ConsumeSimpleNumber(d.buf[pos:]); n == 0 || d.needMore(pos+n) {
   603  			oldAbsPos := d.baseOffset + int64(pos)
   604  			pos, err = d.consumeNumber(pos)
   605  			newAbsPos := d.baseOffset + int64(pos)
   606  			n = int(newAbsPos - oldAbsPos)
   607  			if err != nil {
   608  				return Token{}, wrapSyntacticError(d, err, pos, +1)
   609  			}
   610  		} else {
   611  			pos += n
   612  		}
   613  		if err = d.Tokens.appendNumber(); err != nil {
   614  			return Token{}, wrapSyntacticError(d, err, pos-n, +1) // report position at start of number
   615  		}
   616  		d.prevStart, d.prevEnd = pos-n, pos
   617  		return Token{raw: &d.decodeBuffer, num: uint64(d.previousOffsetStart())}, nil
   618  
   619  	case '{':
   620  		if err = d.Tokens.pushObject(); err != nil {
   621  			return Token{}, wrapSyntacticError(d, err, pos, +1)
   622  		}
   623  		d.Names.push()
   624  		if !d.Flags.Get(jsonflags.AllowDuplicateNames) {
   625  			d.Namespaces.push()
   626  		}
   627  		d.Flags.Clear(jsonflags.TagFlags) // tags only apply to current depth
   628  		pos += 1
   629  		d.prevStart, d.prevEnd = pos, pos
   630  		return BeginObject, nil
   631  
   632  	case '}':
   633  		if err = d.Tokens.popObject(); err != nil {
   634  			return Token{}, wrapSyntacticError(d, err, pos, +1)
   635  		}
   636  		d.Names.pop()
   637  		if !d.Flags.Get(jsonflags.AllowDuplicateNames) {
   638  			d.Namespaces.pop()
   639  		}
   640  		pos += 1
   641  		d.prevStart, d.prevEnd = pos, pos
   642  		return EndObject, nil
   643  
   644  	case '[':
   645  		if err = d.Tokens.pushArray(); err != nil {
   646  			return Token{}, wrapSyntacticError(d, err, pos, +1)
   647  		}
   648  		d.Flags.Clear(jsonflags.TagFlags) // tags only apply to current depth
   649  		pos += 1
   650  		d.prevStart, d.prevEnd = pos, pos
   651  		return BeginArray, nil
   652  
   653  	case ']':
   654  		if err = d.Tokens.popArray(); err != nil {
   655  			return Token{}, wrapSyntacticError(d, err, pos, +1)
   656  		}
   657  		pos += 1
   658  		d.prevStart, d.prevEnd = pos, pos
   659  		return EndArray, nil
   660  
   661  	default:
   662  		err = jsonwire.NewInvalidCharacterError(d.buf[pos:], "at start of value")
   663  		return Token{}, wrapSyntacticError(d, err, pos, +1)
   664  	}
   665  }
   666  
   667  // ReadValue returns the next raw JSON value, advancing the read offset.
   668  // The value is stripped of any leading or trailing whitespace and
   669  // contains the exact bytes of the input, which may contain invalid UTF-8
   670  // if [AllowInvalidUTF8] is specified.
   671  //
   672  // The returned value is only valid until the next Peek, Read, or Skip call and
   673  // may not be mutated while the Decoder remains in use.
   674  // If the decoder is currently at the end token for an object or array,
   675  // then it reports a [SyntacticError] and the internal state remains unchanged.
   676  // It returns [io.EOF] if there are no more values.
   677  func (d *Decoder) ReadValue() (Value, error) {
   678  	var flags jsonwire.ValueFlags
   679  	return d.s.ReadValue(&flags)
   680  }
   681  func (d *decoderState) ReadValue(flags *jsonwire.ValueFlags) (Value, error) {
   682  	// Determine the next kind.
   683  	var err error
   684  	var next Kind
   685  	pos := d.peekPos
   686  	if pos != 0 {
   687  		// Use cached peek result.
   688  		if d.peekErr != nil {
   689  			err := d.peekErr
   690  			d.peekPos, d.peekErr = 0, nil // possibly a transient I/O error
   691  			return nil, err
   692  		}
   693  		next = Kind(d.buf[pos]).normalize()
   694  		d.peekPos = 0 // reset cache
   695  	} else {
   696  		d.invalidatePreviousRead()
   697  		pos = d.prevEnd
   698  
   699  		// Consume leading whitespace.
   700  		pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
   701  		if d.needMore(pos) {
   702  			if pos, err = d.consumeWhitespace(pos); err != nil {
   703  				if err == io.ErrUnexpectedEOF && d.Tokens.Depth() == 1 {
   704  					err = io.EOF // EOF possibly if no Tokens present after top-level value
   705  				}
   706  				return nil, wrapSyntacticError(d, err, pos, 0)
   707  			}
   708  		}
   709  
   710  		// Consume colon or comma.
   711  		var delim byte
   712  		if c := d.buf[pos]; c == ':' || c == ',' {
   713  			delim = c
   714  			pos += 1
   715  			pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
   716  			if d.needMore(pos) {
   717  				if pos, err = d.consumeWhitespace(pos); err != nil {
   718  					err = wrapSyntacticError(d, err, pos, 0)
   719  					return nil, d.checkDelimBeforeIOError(delim, err)
   720  				}
   721  			}
   722  		}
   723  		next = Kind(d.buf[pos]).normalize()
   724  		if d.Tokens.needDelim(next) != delim {
   725  			return nil, d.checkDelim(delim, next)
   726  		}
   727  	}
   728  
   729  	// Handle the next value.
   730  	oldAbsPos := d.baseOffset + int64(pos)
   731  	pos, err = d.consumeValue(flags, pos, d.Tokens.Depth())
   732  	newAbsPos := d.baseOffset + int64(pos)
   733  	n := int(newAbsPos - oldAbsPos)
   734  	if err != nil {
   735  		return nil, wrapSyntacticError(d, err, pos, +1)
   736  	}
   737  	switch next {
   738  	case 'n', 't', 'f':
   739  		err = d.Tokens.appendLiteral()
   740  	case '"':
   741  		if d.Tokens.Last.NeedObjectName() {
   742  			if !d.Flags.Get(jsonflags.AllowDuplicateNames) {
   743  				if !d.Tokens.Last.isValidNamespace() {
   744  					err = errInvalidNamespace
   745  					break
   746  				}
   747  				if d.Tokens.Last.isActiveNamespace() && !d.Namespaces.Last().insertQuoted(d.buf[pos-n:pos], flags.IsVerbatim()) {
   748  					err = wrapWithObjectName(ErrDuplicateName, d.buf[pos-n:pos])
   749  					break
   750  				}
   751  			}
   752  			d.Names.ReplaceLastQuotedOffset(pos - n) // only replace if insertQuoted succeeds
   753  		}
   754  		err = d.Tokens.appendString()
   755  	case '0':
   756  		err = d.Tokens.appendNumber()
   757  	case '{':
   758  		if err = d.Tokens.pushObject(); err != nil {
   759  			break
   760  		}
   761  		if err = d.Tokens.popObject(); err != nil {
   762  			panic("BUG: popObject should never fail immediately after pushObject: " + err.Error())
   763  		}
   764  	case '[':
   765  		if err = d.Tokens.pushArray(); err != nil {
   766  			break
   767  		}
   768  		if err = d.Tokens.popArray(); err != nil {
   769  			panic("BUG: popArray should never fail immediately after pushArray: " + err.Error())
   770  		}
   771  	}
   772  	if err != nil {
   773  		return nil, wrapSyntacticError(d, err, pos-n, +1) // report position at start of value
   774  	}
   775  	d.prevEnd = pos
   776  	d.prevStart = pos - n
   777  	return d.buf[pos-n : pos : pos], nil
   778  }
   779  
   780  // CheckNextValue checks whether the next value is syntactically valid,
   781  // but does not advance the read offset.
   782  // If last, it verifies that the stream cleanly terminates with [io.EOF].
   783  func (d *decoderState) CheckNextValue(last bool) error {
   784  	d.PeekKind() // populates d.peekPos and d.peekErr
   785  	pos, err := d.peekPos, d.peekErr
   786  	d.peekPos, d.peekErr = 0, nil
   787  	if err != nil {
   788  		return err
   789  	}
   790  
   791  	var flags jsonwire.ValueFlags
   792  	if pos, err := d.consumeValue(&flags, pos, d.Tokens.Depth()); err != nil {
   793  		return wrapSyntacticError(d, err, pos, +1)
   794  	} else if last {
   795  		return d.checkEOF(pos)
   796  	}
   797  	return nil
   798  }
   799  
   800  // AtEOF reports whether the decoder is at EOF.
   801  func (d *decoderState) AtEOF() bool {
   802  	_, err := d.consumeWhitespace(d.prevEnd)
   803  	return err == io.ErrUnexpectedEOF
   804  }
   805  
   806  // CheckEOF verifies that the input has no more data.
   807  func (d *decoderState) CheckEOF() error {
   808  	return d.checkEOF(d.prevEnd)
   809  }
   810  func (d *decoderState) checkEOF(pos int) error {
   811  	switch pos, err := d.consumeWhitespace(pos); err {
   812  	case nil:
   813  		err := jsonwire.NewInvalidCharacterError(d.buf[pos:], "after top-level value")
   814  		return wrapSyntacticError(d, err, pos, 0)
   815  	case io.ErrUnexpectedEOF:
   816  		return nil
   817  	default:
   818  		return err
   819  	}
   820  }
   821  
   822  // consumeWhitespace consumes all whitespace starting at d.buf[pos:].
   823  // It returns the new position in d.buf immediately after the last whitespace.
   824  // If it returns nil, there is guaranteed to at least be one unread byte.
   825  //
   826  // The following pattern is common in this implementation:
   827  //
   828  //	pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
   829  //	if d.needMore(pos) {
   830  //		if pos, err = d.consumeWhitespace(pos); err != nil {
   831  //			return ...
   832  //		}
   833  //	}
   834  //
   835  // It is difficult to simplify this without sacrificing performance since
   836  // consumeWhitespace must be inlined. The body of the if statement is
   837  // executed only in rare situations where we need to fetch more data.
   838  // Since fetching may return an error, we also need to check the error.
   839  func (d *decoderState) consumeWhitespace(pos int) (newPos int, err error) {
   840  	for {
   841  		pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
   842  		if d.needMore(pos) {
   843  			absPos := d.baseOffset + int64(pos)
   844  			err = d.fetch() // will mutate d.buf and invalidate pos
   845  			pos = int(absPos - d.baseOffset)
   846  			if err != nil {
   847  				return pos, err
   848  			}
   849  			continue
   850  		}
   851  		return pos, nil
   852  	}
   853  }
   854  
   855  // consumeValue consumes a single JSON value starting at d.buf[pos:].
   856  // It returns the new position in d.buf immediately after the value.
   857  func (d *decoderState) consumeValue(flags *jsonwire.ValueFlags, pos, depth int) (newPos int, err error) {
   858  	for {
   859  		var n int
   860  		var err error
   861  		switch next := Kind(d.buf[pos]).normalize(); next {
   862  		case 'n':
   863  			if n = jsonwire.ConsumeNull(d.buf[pos:]); n == 0 {
   864  				n, err = jsonwire.ConsumeLiteral(d.buf[pos:], "null")
   865  			}
   866  		case 'f':
   867  			if n = jsonwire.ConsumeFalse(d.buf[pos:]); n == 0 {
   868  				n, err = jsonwire.ConsumeLiteral(d.buf[pos:], "false")
   869  			}
   870  		case 't':
   871  			if n = jsonwire.ConsumeTrue(d.buf[pos:]); n == 0 {
   872  				n, err = jsonwire.ConsumeLiteral(d.buf[pos:], "true")
   873  			}
   874  		case '"':
   875  			if n = jsonwire.ConsumeSimpleString(d.buf[pos:]); n == 0 {
   876  				return d.consumeString(flags, pos)
   877  			}
   878  		case '0':
   879  			// NOTE: Since JSON numbers are not self-terminating,
   880  			// we need to make sure that the next byte is not part of a number.
   881  			if n = jsonwire.ConsumeSimpleNumber(d.buf[pos:]); n == 0 || d.needMore(pos+n) {
   882  				return d.consumeNumber(pos)
   883  			}
   884  		case '{':
   885  			return d.consumeObject(flags, pos, depth)
   886  		case '[':
   887  			return d.consumeArray(flags, pos, depth)
   888  		default:
   889  			if (d.Tokens.Last.isObject() && next == ']') || (d.Tokens.Last.isArray() && next == '}') {
   890  				return pos, errMismatchDelim
   891  			}
   892  			return pos, jsonwire.NewInvalidCharacterError(d.buf[pos:], "at start of value")
   893  		}
   894  		if err == io.ErrUnexpectedEOF {
   895  			absPos := d.baseOffset + int64(pos)
   896  			err = d.fetch() // will mutate d.buf and invalidate pos
   897  			pos = int(absPos - d.baseOffset)
   898  			if err != nil {
   899  				return pos + n, err
   900  			}
   901  			continue
   902  		}
   903  		return pos + n, err
   904  	}
   905  }
   906  
   907  // consumeLiteral consumes a single JSON literal starting at d.buf[pos:].
   908  // It returns the new position in d.buf immediately after the literal.
   909  func (d *decoderState) consumeLiteral(pos int, lit string) (newPos int, err error) {
   910  	for {
   911  		n, err := jsonwire.ConsumeLiteral(d.buf[pos:], lit)
   912  		if err == io.ErrUnexpectedEOF {
   913  			absPos := d.baseOffset + int64(pos)
   914  			err = d.fetch() // will mutate d.buf and invalidate pos
   915  			pos = int(absPos - d.baseOffset)
   916  			if err != nil {
   917  				return pos + n, err
   918  			}
   919  			continue
   920  		}
   921  		return pos + n, err
   922  	}
   923  }
   924  
   925  // consumeString consumes a single JSON string starting at d.buf[pos:].
   926  // It returns the new position in d.buf immediately after the string.
   927  func (d *decoderState) consumeString(flags *jsonwire.ValueFlags, pos int) (newPos int, err error) {
   928  	var n int
   929  	for {
   930  		n, err = jsonwire.ConsumeStringResumable(flags, d.buf[pos:], n, !d.Flags.Get(jsonflags.AllowInvalidUTF8))
   931  		if err == io.ErrUnexpectedEOF {
   932  			absPos := d.baseOffset + int64(pos)
   933  			err = d.fetch() // will mutate d.buf and invalidate pos
   934  			pos = int(absPos - d.baseOffset)
   935  			if err != nil {
   936  				return pos + n, err
   937  			}
   938  			continue
   939  		}
   940  		return pos + n, err
   941  	}
   942  }
   943  
   944  // consumeNumber consumes a single JSON number starting at d.buf[pos:].
   945  // It returns the new position in d.buf immediately after the number.
   946  func (d *decoderState) consumeNumber(pos int) (newPos int, err error) {
   947  	var n int
   948  	var state jsonwire.ConsumeNumberState
   949  	for {
   950  		n, state, err = jsonwire.ConsumeNumberResumable(d.buf[pos:], n, state)
   951  		// NOTE: Since JSON numbers are not self-terminating,
   952  		// we need to make sure that the next byte is not part of a number.
   953  		if err == io.ErrUnexpectedEOF || d.needMore(pos+n) {
   954  			mayTerminate := err == nil
   955  			absPos := d.baseOffset + int64(pos)
   956  			err = d.fetch() // will mutate d.buf and invalidate pos
   957  			pos = int(absPos - d.baseOffset)
   958  			if err != nil {
   959  				if mayTerminate && err == io.ErrUnexpectedEOF {
   960  					return pos + n, nil
   961  				}
   962  				return pos, err
   963  			}
   964  			continue
   965  		}
   966  		return pos + n, err
   967  	}
   968  }
   969  
   970  // consumeObject consumes a single JSON object starting at d.buf[pos:].
   971  // It returns the new position in d.buf immediately after the object.
   972  func (d *decoderState) consumeObject(flags *jsonwire.ValueFlags, pos, depth int) (newPos int, err error) {
   973  	var n int
   974  	var names *objectNamespace
   975  	if !d.Flags.Get(jsonflags.AllowDuplicateNames) {
   976  		d.Namespaces.push()
   977  		defer d.Namespaces.pop()
   978  		names = d.Namespaces.Last()
   979  	}
   980  
   981  	// Handle before start.
   982  	if uint(pos) >= uint(len(d.buf)) || d.buf[pos] != '{' {
   983  		panic("BUG: consumeObject must be called with a buffer that starts with '{'")
   984  	} else if depth == maxNestingDepth+1 {
   985  		return pos, errMaxDepth
   986  	}
   987  	pos++
   988  
   989  	// Handle after start.
   990  	pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
   991  	if d.needMore(pos) {
   992  		if pos, err = d.consumeWhitespace(pos); err != nil {
   993  			return pos, err
   994  		}
   995  	}
   996  	if d.buf[pos] == '}' {
   997  		pos++
   998  		return pos, nil
   999  	}
  1000  
  1001  	depth++
  1002  	for {
  1003  		// Handle before name.
  1004  		pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
  1005  		if d.needMore(pos) {
  1006  			if pos, err = d.consumeWhitespace(pos); err != nil {
  1007  				return pos, err
  1008  			}
  1009  		}
  1010  		var flags2 jsonwire.ValueFlags
  1011  		if n = jsonwire.ConsumeSimpleString(d.buf[pos:]); n == 0 {
  1012  			oldAbsPos := d.baseOffset + int64(pos)
  1013  			pos, err = d.consumeString(&flags2, pos)
  1014  			newAbsPos := d.baseOffset + int64(pos)
  1015  			n = int(newAbsPos - oldAbsPos)
  1016  			flags.Join(flags2)
  1017  			if err != nil {
  1018  				return pos, err
  1019  			}
  1020  		} else {
  1021  			pos += n
  1022  		}
  1023  		quotedName := d.buf[pos-n : pos]
  1024  		if !d.Flags.Get(jsonflags.AllowDuplicateNames) && !names.insertQuoted(quotedName, flags2.IsVerbatim()) {
  1025  			return pos - n, wrapWithObjectName(ErrDuplicateName, quotedName)
  1026  		}
  1027  
  1028  		// Handle after name.
  1029  		pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
  1030  		if d.needMore(pos) {
  1031  			if pos, err = d.consumeWhitespace(pos); err != nil {
  1032  				return pos, wrapWithObjectName(err, quotedName)
  1033  			}
  1034  		}
  1035  		if d.buf[pos] != ':' {
  1036  			err := jsonwire.NewInvalidCharacterError(d.buf[pos:], "after object name (expecting ':')")
  1037  			return pos, wrapWithObjectName(err, quotedName)
  1038  		}
  1039  		pos++
  1040  
  1041  		// Handle before value.
  1042  		pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
  1043  		if d.needMore(pos) {
  1044  			if pos, err = d.consumeWhitespace(pos); err != nil {
  1045  				return pos, wrapWithObjectName(err, quotedName)
  1046  			}
  1047  		}
  1048  		pos, err = d.consumeValue(flags, pos, depth)
  1049  		if err != nil {
  1050  			return pos, wrapWithObjectName(err, quotedName)
  1051  		}
  1052  
  1053  		// Handle after value.
  1054  		pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
  1055  		if d.needMore(pos) {
  1056  			if pos, err = d.consumeWhitespace(pos); err != nil {
  1057  				return pos, err
  1058  			}
  1059  		}
  1060  		switch d.buf[pos] {
  1061  		case ',':
  1062  			pos++
  1063  			continue
  1064  		case '}':
  1065  			pos++
  1066  			return pos, nil
  1067  		default:
  1068  			return pos, jsonwire.NewInvalidCharacterError(d.buf[pos:], "after object value (expecting ',' or '}')")
  1069  		}
  1070  	}
  1071  }
  1072  
  1073  // consumeArray consumes a single JSON array starting at d.buf[pos:].
  1074  // It returns the new position in d.buf immediately after the array.
  1075  func (d *decoderState) consumeArray(flags *jsonwire.ValueFlags, pos, depth int) (newPos int, err error) {
  1076  	// Handle before start.
  1077  	if uint(pos) >= uint(len(d.buf)) || d.buf[pos] != '[' {
  1078  		panic("BUG: consumeArray must be called with a buffer that starts with '['")
  1079  	} else if depth == maxNestingDepth+1 {
  1080  		return pos, errMaxDepth
  1081  	}
  1082  	pos++
  1083  
  1084  	// Handle after start.
  1085  	pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
  1086  	if d.needMore(pos) {
  1087  		if pos, err = d.consumeWhitespace(pos); err != nil {
  1088  			return pos, err
  1089  		}
  1090  	}
  1091  	if d.buf[pos] == ']' {
  1092  		pos++
  1093  		return pos, nil
  1094  	}
  1095  
  1096  	var idx int64
  1097  	depth++
  1098  	for {
  1099  		// Handle before value.
  1100  		pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
  1101  		if d.needMore(pos) {
  1102  			if pos, err = d.consumeWhitespace(pos); err != nil {
  1103  				return pos, err
  1104  			}
  1105  		}
  1106  		pos, err = d.consumeValue(flags, pos, depth)
  1107  		if err != nil {
  1108  			return pos, wrapWithArrayIndex(err, idx)
  1109  		}
  1110  
  1111  		// Handle after value.
  1112  		pos += jsonwire.ConsumeWhitespace(d.buf[pos:])
  1113  		if d.needMore(pos) {
  1114  			if pos, err = d.consumeWhitespace(pos); err != nil {
  1115  				return pos, err
  1116  			}
  1117  		}
  1118  		switch d.buf[pos] {
  1119  		case ',':
  1120  			pos++
  1121  			idx++
  1122  			continue
  1123  		case ']':
  1124  			pos++
  1125  			return pos, nil
  1126  		default:
  1127  			return pos, jsonwire.NewInvalidCharacterError(d.buf[pos:], "after array element (expecting ',' or ']')")
  1128  		}
  1129  	}
  1130  }
  1131  
  1132  // InputOffset returns the current input byte offset. It gives the location
  1133  // of the next byte immediately after the most recently returned token or value.
  1134  // The number of bytes actually read from the underlying [io.Reader] may be more
  1135  // than this offset due to internal buffering.
  1136  func (d *Decoder) InputOffset() int64 {
  1137  	return d.s.previousOffsetEnd()
  1138  }
  1139  
  1140  // UnreadBuffer returns the data remaining in the unread buffer,
  1141  // which may contain zero or more bytes.
  1142  // This is the data already consumed from the input [io.Reader],
  1143  // but not yet read by a [Decoder.ReadToken] or [Decoder.ReadValue] call.
  1144  // It may contain bytes that do not form valid JSON, since it has not yet
  1145  // been validated according to the JSON grammar.
  1146  // The exact amount of buffered data is an implementation detail
  1147  // of the Decoder and may change over time.
  1148  //
  1149  // It is the caller's responsibility to concatenate this buffer with
  1150  // the remainder of the input Reader to obtain the full sequence
  1151  // of bytes after the last read JSON token or value.
  1152  //
  1153  // The returned buffer must not be mutated while Decoder continues to be used.
  1154  // The buffer contents are valid until the next Peek, Read, or Skip call.
  1155  func (d *Decoder) UnreadBuffer() []byte {
  1156  	return d.s.unreadBuffer()
  1157  }
  1158  
  1159  // StackDepth returns the depth of the state machine for JSON data
  1160  // that has already been read.
  1161  // Each level on the stack represents a nested JSON object or array.
  1162  // It is incremented whenever a [BeginObject] or [BeginArray] token is encountered
  1163  // and decremented whenever an [EndObject] or [EndArray] token is encountered.
  1164  //
  1165  // StackDepth returns 0 when not inside any object or array.
  1166  // In particular, it returns 0 before any tokens have been read,
  1167  // after any top-level value has been read, and between values
  1168  // when decoding a stream of top-level values (e.g., NDJSON).
  1169  // StackDepth returns 1 inside a top-level object or array,
  1170  // 2 inside a nested object or array, and so on.
  1171  //
  1172  // For example, consider decoding the following JSON:
  1173  //
  1174  //	{"a": [1, 2], "b": {"c": 3}}
  1175  //
  1176  // While decoding, StackDepth would report the following:
  1177  //
  1178  //   - At the start, StackDepth reports 0.
  1179  //   - After decoding the outer '{', StackDepth reports 1.
  1180  //   - After decoding the inner '[', StackDepth reports 2.
  1181  //   - After decoding the inner ']', StackDepth reports 1.
  1182  //   - After decoding the outer '}', StackDepth reports 0.
  1183  func (d *Decoder) StackDepth() int {
  1184  	// NOTE: Keep in sync with Encoder.StackDepth.
  1185  	return d.s.Tokens.Depth() - 1
  1186  }
  1187  
  1188  // StackIndex returns information about the specified stack level.
  1189  // It must be a number between 0 and [Decoder.StackDepth], inclusive.
  1190  // For each level, it reports the kind:
  1191  //
  1192  //   - [KindInvalid] for a level of zero,
  1193  //   - [KindBeginObject] for a level representing a JSON object, and
  1194  //   - [KindBeginArray] for a level representing a JSON array.
  1195  //
  1196  // It also reports the length of that JSON object or array decoded so far.
  1197  // Each name and value in a JSON object is counted separately,
  1198  // so the effective number of members is half the length.
  1199  // A complete JSON object must have an even length.
  1200  func (d *Decoder) StackIndex(i int) (Kind, int64) {
  1201  	// NOTE: Keep in sync with Encoder.StackIndex.
  1202  	switch s := d.s.Tokens.index(i); {
  1203  	case i > 0 && s.isObject():
  1204  		return '{', s.Length()
  1205  	case i > 0 && s.isArray():
  1206  		return '[', s.Length()
  1207  	default:
  1208  		return 0, s.Length()
  1209  	}
  1210  }
  1211  
  1212  // StackPointer returns a JSON Pointer (RFC 6901) to the most recently read value.
  1213  func (d *Decoder) StackPointer() Pointer {
  1214  	return Pointer(d.s.AppendStackPointer(nil, -1))
  1215  }
  1216  
  1217  func (d *decoderState) AppendStackPointer(b []byte, where int) []byte {
  1218  	d.Names.copyQuotedBuffer(d.buf)
  1219  	return d.state.appendStackPointer(b, where)
  1220  }
  1221  

View as plain text