1 // Copyright 2010 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.
7 // JSON value parser state machine.
8 // Just about at the limit of what is reasonable to write by hand.
9 // Some parts are a bit tedious, but overall it nicely factors out the
10 // otherwise common code from the multiple scanning functions
11 // in this package (Compact, Indent, checkValid, nextValue, etc).
13 // This file starts with two simple examples using the scanner
14 // before diving into the scanner itself.
18 // Valid reports whether data is a valid JSON encoding.
19 func Valid(data
[]byte) bool {
20 return checkValid(data
, &scanner
{}) == nil
23 // checkValid verifies that data is valid JSON-encoded data.
24 // scan is passed in for use by checkValid to avoid an allocation.
25 func checkValid(data
[]byte, scan
*scanner
) error
{
27 for _
, c
:= range data
{
29 if scan
.step(scan
, c
) == scanError
{
33 if scan
.eof() == scanError
{
39 // nextValue splits data after the next whole JSON value,
40 // returning that value and the bytes that follow it as separate slices.
41 // scan is passed in for use by nextValue to avoid an allocation.
42 func nextValue(data
[]byte, scan
*scanner
) (value
, rest
[]byte, err error
) {
44 for i
, c
:= range data
{
45 v
:= scan
.step(scan
, c
)
46 if v
>= scanEndObject
{
48 // probe the scanner with a space to determine whether we will
49 // get scanEnd on the next character. Otherwise, if the next character
50 // is not a space, scanEndTop allocates a needless error.
51 case scanEndObject
, scanEndArray
:
52 if scan
.step(scan
, ' ') == scanEnd
{
53 return data
[:i
+1], data
[i
+1:], nil
56 return nil, nil, scan
.err
58 return data
[:i
], data
[i
:], nil
62 if scan
.eof() == scanError
{
63 return nil, nil, scan
.err
68 // A SyntaxError is a description of a JSON syntax error.
69 type SyntaxError
struct {
70 msg
string // description of error
71 Offset
int64 // error occurred after reading Offset bytes
74 func (e
*SyntaxError
) Error() string { return e
.msg
}
76 // A scanner is a JSON scanning state machine.
77 // Callers call scan.reset() and then pass bytes in one at a time
78 // by calling scan.step(&scan, c) for each byte.
79 // The return value, referred to as an opcode, tells the
80 // caller about significant parsing events like beginning
81 // and ending literals, objects, and arrays, so that the
82 // caller can follow along if it wishes.
83 // The return value scanEnd indicates that a single top-level
84 // JSON value has been completed, *before* the byte that
85 // just got passed in. (The indication must be delayed in order
86 // to recognize the end of numbers: is 123 a whole value or
87 // the beginning of 12345e+6?).
89 // The step is a func to be called to execute the next transition.
90 // Also tried using an integer constant and a single func
91 // with a switch, but using the func directly was 10% faster
92 // on a 64-bit Mac Mini, and it's nicer to read.
93 step
func(*scanner
, byte) int
95 // Reached end of top-level value.
98 // Stack of what we're in the middle of - array values, object keys, object values.
101 // Error that happened, if any.
104 // 1-byte redo (see undo method)
107 redoState
func(*scanner
, byte) int
109 // total bytes consumed, updated by decoder.Decode
113 // These values are returned by the state transition functions
114 // assigned to scanner.state and the method scanner.eof.
115 // They give details about the current state of the scan that
116 // callers might be interested to know about.
117 // It is okay to ignore the return value of any particular
118 // call to scanner.state: if one call returns scanError,
119 // every subsequent call will return scanError too.
122 scanContinue
= iota // uninteresting byte
123 scanBeginLiteral
// end implied by next result != scanContinue
124 scanBeginObject
// begin object
125 scanObjectKey
// just finished object key (string)
126 scanObjectValue
// just finished non-last object value
127 scanEndObject
// end object (implies scanObjectValue if possible)
128 scanBeginArray
// begin array
129 scanArrayValue
// just finished array value
130 scanEndArray
// end array (implies scanArrayValue if possible)
131 scanSkipSpace
// space byte; can skip; known to be last "continue" result
134 scanEnd
// top-level value ended *before* this byte; known to be first "stop" result
135 scanError
// hit an error, scanner.err.
138 // These values are stored in the parseState stack.
139 // They give the current state of a composite value
140 // being scanned. If the parser is inside a nested value
141 // the parseState describes the nested state, outermost at entry 0.
143 parseObjectKey
= iota // parsing object key (before colon)
144 parseObjectValue
// parsing object value (after colon)
145 parseArrayValue
// parsing array value
148 // reset prepares the scanner for use.
149 // It must be called before calling s.step.
150 func (s
*scanner
) reset() {
151 s
.step
= stateBeginValue
152 s
.parseState
= s
.parseState
[0:0]
158 // eof tells the scanner that the end of input has been reached.
159 // It returns a scan status just as s.step does.
160 func (s
*scanner
) eof() int {
172 s
.err
= &SyntaxError
{"unexpected end of JSON input", s
.bytes
}
177 // pushParseState pushes a new parse state p onto the parse stack.
178 func (s
*scanner
) pushParseState(p
int) {
179 s
.parseState
= append(s
.parseState
, p
)
182 // popParseState pops a parse state (already obtained) off the stack
183 // and updates s.step accordingly.
184 func (s
*scanner
) popParseState() {
185 n
:= len(s
.parseState
) - 1
186 s
.parseState
= s
.parseState
[0:n
]
192 s
.step
= stateEndValue
196 func isSpace(c
byte) bool {
197 return c
== ' ' || c
== '\t' || c
== '\r' || c
== '\n'
200 // stateBeginValueOrEmpty is the state after reading `[`.
201 func stateBeginValueOrEmpty(s
*scanner
, c
byte) int {
202 if c
<= ' ' && isSpace(c
) {
206 return stateEndValue(s
, c
)
208 return stateBeginValue(s
, c
)
211 // stateBeginValue is the state at the beginning of the input.
212 func stateBeginValue(s
*scanner
, c
byte) int {
213 if c
<= ' ' && isSpace(c
) {
218 s
.step
= stateBeginStringOrEmpty
219 s
.pushParseState(parseObjectKey
)
220 return scanBeginObject
222 s
.step
= stateBeginValueOrEmpty
223 s
.pushParseState(parseArrayValue
)
224 return scanBeginArray
226 s
.step
= stateInString
227 return scanBeginLiteral
230 return scanBeginLiteral
231 case '0': // beginning of 0.123
233 return scanBeginLiteral
234 case 't': // beginning of true
236 return scanBeginLiteral
237 case 'f': // beginning of false
239 return scanBeginLiteral
240 case 'n': // beginning of null
242 return scanBeginLiteral
244 if '1' <= c
&& c
<= '9' { // beginning of 1234.5
246 return scanBeginLiteral
248 return s
.error(c
, "looking for beginning of value")
251 // stateBeginStringOrEmpty is the state after reading `{`.
252 func stateBeginStringOrEmpty(s
*scanner
, c
byte) int {
253 if c
<= ' ' && isSpace(c
) {
257 n
:= len(s
.parseState
)
258 s
.parseState
[n
-1] = parseObjectValue
259 return stateEndValue(s
, c
)
261 return stateBeginString(s
, c
)
264 // stateBeginString is the state after reading `{"key": value,`.
265 func stateBeginString(s
*scanner
, c
byte) int {
266 if c
<= ' ' && isSpace(c
) {
270 s
.step
= stateInString
271 return scanBeginLiteral
273 return s
.error(c
, "looking for beginning of object key string")
276 // stateEndValue is the state after completing a value,
277 // such as after reading `{}` or `true` or `["x"`.
278 func stateEndValue(s
*scanner
, c
byte) int {
279 n
:= len(s
.parseState
)
281 // Completed top-level before the current byte.
284 return stateEndTop(s
, c
)
286 if c
<= ' ' && isSpace(c
) {
287 s
.step
= stateEndValue
290 ps
:= s
.parseState
[n
-1]
294 s
.parseState
[n
-1] = parseObjectValue
295 s
.step
= stateBeginValue
298 return s
.error(c
, "after object key")
299 case parseObjectValue
:
301 s
.parseState
[n
-1] = parseObjectKey
302 s
.step
= stateBeginString
303 return scanObjectValue
309 return s
.error(c
, "after object key:value pair")
310 case parseArrayValue
:
312 s
.step
= stateBeginValue
313 return scanArrayValue
319 return s
.error(c
, "after array element")
321 return s
.error(c
, "")
324 // stateEndTop is the state after finishing the top-level value,
325 // such as after reading `{}` or `[1,2,3]`.
326 // Only space characters should be seen now.
327 func stateEndTop(s
*scanner
, c
byte) int {
328 if c
!= ' ' && c
!= '\t' && c
!= '\r' && c
!= '\n' {
329 // Complain about non-space byte on next call.
330 s
.error(c
, "after top-level value")
335 // stateInString is the state after reading `"`.
336 func stateInString(s
*scanner
, c
byte) int {
338 s
.step
= stateEndValue
342 s
.step
= stateInStringEsc
346 return s
.error(c
, "in string literal")
351 // stateInStringEsc is the state after reading `"\` during a quoted string.
352 func stateInStringEsc(s
*scanner
, c
byte) int {
354 case 'b', 'f', 'n', 'r', 't', '\\', '/', '"':
355 s
.step
= stateInString
358 s
.step
= stateInStringEscU
361 return s
.error(c
, "in string escape code")
364 // stateInStringEscU is the state after reading `"\u` during a quoted string.
365 func stateInStringEscU(s
*scanner
, c
byte) int {
366 if '0' <= c
&& c
<= '9' ||
'a' <= c
&& c
<= 'f' ||
'A' <= c
&& c
<= 'F' {
367 s
.step
= stateInStringEscU1
371 return s
.error(c
, "in \\u hexadecimal character escape")
374 // stateInStringEscU1 is the state after reading `"\u1` during a quoted string.
375 func stateInStringEscU1(s
*scanner
, c
byte) int {
376 if '0' <= c
&& c
<= '9' ||
'a' <= c
&& c
<= 'f' ||
'A' <= c
&& c
<= 'F' {
377 s
.step
= stateInStringEscU12
381 return s
.error(c
, "in \\u hexadecimal character escape")
384 // stateInStringEscU12 is the state after reading `"\u12` during a quoted string.
385 func stateInStringEscU12(s
*scanner
, c
byte) int {
386 if '0' <= c
&& c
<= '9' ||
'a' <= c
&& c
<= 'f' ||
'A' <= c
&& c
<= 'F' {
387 s
.step
= stateInStringEscU123
391 return s
.error(c
, "in \\u hexadecimal character escape")
394 // stateInStringEscU123 is the state after reading `"\u123` during a quoted string.
395 func stateInStringEscU123(s
*scanner
, c
byte) int {
396 if '0' <= c
&& c
<= '9' ||
'a' <= c
&& c
<= 'f' ||
'A' <= c
&& c
<= 'F' {
397 s
.step
= stateInString
401 return s
.error(c
, "in \\u hexadecimal character escape")
404 // stateNeg is the state after reading `-` during a number.
405 func stateNeg(s
*scanner
, c
byte) int {
410 if '1' <= c
&& c
<= '9' {
414 return s
.error(c
, "in numeric literal")
417 // state1 is the state after reading a non-zero integer during a number,
418 // such as after reading `1` or `100` but not `0`.
419 func state1(s
*scanner
, c
byte) int {
420 if '0' <= c
&& c
<= '9' {
427 // state0 is the state after reading `0` during a number.
428 func state0(s
*scanner
, c
byte) int {
433 if c
== 'e' || c
== 'E' {
437 return stateEndValue(s
, c
)
440 // stateDot is the state after reading the integer and decimal point in a number,
441 // such as after reading `1.`.
442 func stateDot(s
*scanner
, c
byte) int {
443 if '0' <= c
&& c
<= '9' {
447 return s
.error(c
, "after decimal point in numeric literal")
450 // stateDot0 is the state after reading the integer, decimal point, and subsequent
451 // digits of a number, such as after reading `3.14`.
452 func stateDot0(s
*scanner
, c
byte) int {
453 if '0' <= c
&& c
<= '9' {
456 if c
== 'e' || c
== 'E' {
460 return stateEndValue(s
, c
)
463 // stateE is the state after reading the mantissa and e in a number,
464 // such as after reading `314e` or `0.314e`.
465 func stateE(s
*scanner
, c
byte) int {
466 if c
== '+' || c
== '-' {
470 return stateESign(s
, c
)
473 // stateESign is the state after reading the mantissa, e, and sign in a number,
474 // such as after reading `314e-` or `0.314e+`.
475 func stateESign(s
*scanner
, c
byte) int {
476 if '0' <= c
&& c
<= '9' {
480 return s
.error(c
, "in exponent of numeric literal")
483 // stateE0 is the state after reading the mantissa, e, optional sign,
484 // and at least one digit of the exponent in a number,
485 // such as after reading `314e-2` or `0.314e+1` or `3.14e0`.
486 func stateE0(s
*scanner
, c
byte) int {
487 if '0' <= c
&& c
<= '9' {
490 return stateEndValue(s
, c
)
493 // stateT is the state after reading `t`.
494 func stateT(s
*scanner
, c
byte) int {
499 return s
.error(c
, "in literal true (expecting 'r')")
502 // stateTr is the state after reading `tr`.
503 func stateTr(s
*scanner
, c
byte) int {
508 return s
.error(c
, "in literal true (expecting 'u')")
511 // stateTru is the state after reading `tru`.
512 func stateTru(s
*scanner
, c
byte) int {
514 s
.step
= stateEndValue
517 return s
.error(c
, "in literal true (expecting 'e')")
520 // stateF is the state after reading `f`.
521 func stateF(s
*scanner
, c
byte) int {
526 return s
.error(c
, "in literal false (expecting 'a')")
529 // stateFa is the state after reading `fa`.
530 func stateFa(s
*scanner
, c
byte) int {
535 return s
.error(c
, "in literal false (expecting 'l')")
538 // stateFal is the state after reading `fal`.
539 func stateFal(s
*scanner
, c
byte) int {
544 return s
.error(c
, "in literal false (expecting 's')")
547 // stateFals is the state after reading `fals`.
548 func stateFals(s
*scanner
, c
byte) int {
550 s
.step
= stateEndValue
553 return s
.error(c
, "in literal false (expecting 'e')")
556 // stateN is the state after reading `n`.
557 func stateN(s
*scanner
, c
byte) int {
562 return s
.error(c
, "in literal null (expecting 'u')")
565 // stateNu is the state after reading `nu`.
566 func stateNu(s
*scanner
, c
byte) int {
571 return s
.error(c
, "in literal null (expecting 'l')")
574 // stateNul is the state after reading `nul`.
575 func stateNul(s
*scanner
, c
byte) int {
577 s
.step
= stateEndValue
580 return s
.error(c
, "in literal null (expecting 'l')")
583 // stateError is the state after reaching a syntax error,
584 // such as after reading `[1}` or `5.1.2`.
585 func stateError(s
*scanner
, c
byte) int {
589 // error records an error and switches to the error state.
590 func (s
*scanner
) error(c
byte, context
string) int {
592 s
.err
= &SyntaxError
{"invalid character " + quoteChar(c
) + " " + context
, s
.bytes
}
596 // quoteChar formats c as a quoted character literal
597 func quoteChar(c
byte) string {
598 // special cases - different from quoted strings
606 // use quoted string with different quotation marks
607 s
:= strconv
.Quote(string(c
))
608 return "'" + s
[1:len(s
)-1] + "'"
611 // undo causes the scanner to return scanCode from the next state transition.
612 // This gives callers a simple 1-byte undo mechanism.
613 func (s
*scanner
) undo(scanCode
int) {
615 panic("json: invalid use of scanner")
617 s
.redoCode
= scanCode
623 // stateRedo helps implement the scanner's 1-byte undo.
624 func stateRedo(s
*scanner
, c
byte) int {