README
¶
Jseq - streaming JSON parser
This is jseq, a streaming JSON parser.
It relies on the encoding/json/jsontext package in the Go standard library,
which in Go 1.25 (the latest version as of this writing) is still experimental.
To enable it, you must build with the environment variable GOEXPERIMENT set to jsonv2.
This package is expected to become a fully fledged part of the stdlib in Go 1.26,
at which point setting GOEXPERIMENT will not be necessary.
For more details, please see A new experimental Go API for JSON.
The main function in this package, Values,
produces JSON values from its input as soon as they are encountered.
This means, for example,
that it will produce the members of an array one by one first,
followed by the complete array.
For more information and a working example,
see the Go doc for this package.
Documentation
¶
Overview ¶
Package jseq supplies streaming parsers for JSON tokens and values.
This package relies on encoding/json/jsontext, which is new and experimental in Go 1.25 and expected to become standard in Go 1.26. To use this package with Go 1.25 you must set GOEXPERIMENT=jsonv2. For more on this, see https://go.dev/blog/jsonv2-exp#experimenting-with-jsonv2
Example ¶
package main
import (
"errors"
"fmt"
"strings"
"github.com/bobg/jseq"
)
func main() {
r := strings.NewReader(example_input)
tokens, errptr1 := jseq.Tokens(r)
values, errptr2 := jseq.Values(tokens)
for pointer, value := range values {
fmt.Printf("%q: %v\n", pointer.Text(), value)
}
if err := errors.Join(*errptr1, *errptr2); err != nil {
panic(err)
}
}
var example_input = `{"hello": [1, 2]} {"world": [3, 4]}`
Output: "/hello/0": 1 "/hello/1": 2 "/hello": [1 2] "": map[hello:[1 2]] "/world/0": 3 "/world/1": 4 "/world": [3 4] "": map[world:[3 4]]
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Tokens ¶
Tokens parses JSON tokens from r and returns them as an iter.Seq. This sequence is suitable as input to Values.
After consuming the resulting sequence, the caller may check for errors by dereferencing the returned error pointer.
func Values ¶
Values consumes a sequence of JSON tokens and produces a sequence of JSON values, each paired with the Pointer that can locate it within its top-level object.
The input to this function may be supplied by a call to Tokens.
Values are produced as they are encountered, in depth-first fashion, making this a "streaming" or "event-based" parser. For example, given a sequence of tokens representing this input:
{"hello": [1, 2], "world": [3, 4]}
Values will produce pointer/value pairs in this order:
"/hello/0" 1
"/hello/1" 2
"/hello" [1, 2]
"/world/0" 3
"/world/1" 4
"/world" [3, 4]
"" {"hello": [1, 2], "world": [3, 4]}
Note that object keys are not considered values to be separately emitted.
Value types in the resulting sequence are:
- []any for arrays
- map[string]any for objects
- strings for strings
- boolean for booleans
- Null for null
- Number for numbers
The input may contain multiple top-level JSON values, each of which will be paired with the empty pointer "". If the input ends in the middle of a JSON value, Values produces an io.ErrUnexpectedEOF error.
After consuming the resulting sequence, the caller may check for errors by dereferencing the returned error pointer.
Types ¶
type Number ¶
type Number struct {
// contains filtered or unexported fields
}
Number is the type of a JSON number if the [StringNum] option is used.
type Pointer ¶
type Pointer []any
Pointer is the type of a JSON pointer produced by Values. It can be converted to a jsontext.Pointer via its Text method. Object keys are represented as strings, and array indexes are represented as ints. This allows the caller to distinguish between an array member at position X and an object member with key X, which jsontext.Pointer cannot do.
Source Files