Involved Source Filesdecode.go Package jsontext implements syntactic processing of JSON
as specified in RFC 4627, RFC 7159, RFC 7493, RFC 8259, and RFC 8785.
JSON is a simple data interchange format that can represent
primitive data types such as booleans, strings, and numbers,
in addition to structured data types such as objects and arrays.
The [Encoder] and [Decoder] types are used to encode or decode
a stream of JSON tokens or values.
# Tokens and Values
A JSON token refers to the basic structural elements of JSON:
- a JSON literal (i.e., null, true, or false)
- a JSON string (e.g., "hello, world!")
- a JSON number (e.g., 123.456)
- a start or end delimiter for a JSON object (i.e., '{' or '}')
- a start or end delimiter for a JSON array (i.e., '[' or ']')
A JSON token is represented by the [Token] type in Go. Technically,
there are two additional structural characters (i.e., ':' and ','),
but there is no [Token] representation for them since their presence
can be inferred by the structure of the JSON grammar itself.
For example, there must always be an implicit colon between
the name and value of a JSON object member.
A JSON value refers to a complete unit of JSON data:
- a JSON literal, string, or number
- a JSON object (e.g., `{"name":"value"}`)
- a JSON array (e.g., `[1,2,3,]`)
A JSON value is represented by the [Value] type in Go and is a []byte
containing the raw textual representation of the value. There is some overlap
between tokens and values as both contain literals, strings, and numbers.
However, only a value can represent the entirety of a JSON object or array.
The [Encoder] and [Decoder] types contain methods to read or write the next
[Token] or [Value] in a sequence. They maintain a state machine to validate
whether the sequence of JSON tokens and/or values produces a valid JSON.
[Options] may be passed to the [NewEncoder] or [NewDecoder] constructors
to configure the syntactic behavior of encoding and decoding.
# Terminology
The terms "encode" and "decode" are used for syntactic functionality
that is concerned with processing JSON based on its grammar, and
the terms "marshal" and "unmarshal" are used for semantic functionality
that determines the meaning of JSON values as Go values and vice-versa.
This package (i.e., [jsontext]) deals with JSON at a syntactic layer,
while [encoding/json/v2] deals with JSON at a semantic layer.
The goal is to provide a clear distinction between functionality that
is purely concerned with encoding versus that of marshaling.
For example, one can directly encode a stream of JSON tokens without
needing to marshal a concrete Go value representing them.
Similarly, one can decode a stream of JSON tokens without
needing to unmarshal them into a concrete Go value.
This package uses JSON terminology when discussing JSON, which may differ
from related concepts in Go or elsewhere in computing literature.
- a JSON "object" refers to an unordered collection of name/value members.
- a JSON "array" refers to an ordered sequence of elements.
- a JSON "value" refers to either a literal (i.e., null, false, or true),
string, number, object, or array.
See RFC 8259 for more information.
# Specifications
Relevant specifications include RFC 4627, RFC 7159, RFC 7493, RFC 8259,
and RFC 8785. Each RFC is generally a stricter subset of another RFC.
In increasing order of strictness:
- RFC 4627 and RFC 7159 do not require (but recommend) the use of UTF-8
and also do not require (but recommend) that object names be unique.
- RFC 8259 requires the use of UTF-8,
but does not require (but recommends) that object names be unique.
- RFC 7493 requires the use of UTF-8
and also requires that object names be unique.
- RFC 8785 defines a canonical representation. It requires the use of UTF-8
and also requires that object names be unique and in a specific ordering.
It specifies exactly how strings and numbers must be formatted.
The primary difference between RFC 4627 and RFC 7159 is that the former
restricted top-level values to only JSON objects and arrays, while
RFC 7159 and subsequent RFCs permit top-level values to additionally be
JSON nulls, booleans, strings, or numbers.
By default, this package operates on RFC 7493, but can be configured
to operate according to the other RFC specifications.
RFC 7493 is a stricter subset of RFC 8259 and fully compliant with it.
In particular, it makes specific choices about behavior that RFC 8259
leaves as undefined in order to ensure greater interoperability.encode.goerrors.goexport.gooptions.gopools.goquote.gostate.gotoken.govalue.go
Code Examples
{
page := struct {
Title string
Body string
}{
Title: "Example Embedded Javascript",
Body: `<script> console.log("Hello, world!"); </script>`,
}
b, err := json.Marshal(&page,
jsontext.EscapeForHTML(true),
jsontext.EscapeForJS(true),
jsontext.Multiline(true))
if err != nil {
log.Fatal(err)
}
fmt.Println(string(b))
}
package main
import (
"bytes"
"fmt"
"io"
"log"
"strings"
"encoding/json/jsontext"
)
func main() {
// Example input with non-idiomatic use of "Golang" instead of "Go".
const input = `{
"title": "Golang version 1 is released",
"author": "Andrew Gerrand",
"date": "2012-03-28",
"text": "Today marks a major milestone in the development of the Golang programming language.",
"otherArticles": [
"Twelve Years of Golang",
"The Laws of Reflection",
"Learn Golang from your browser"
]
}`
// Using a Decoder and Encoder, we can parse through every token,
// check and modify the token if necessary, and
// write the token to the output.
var replacements []jsontext.Pointer
in := strings.NewReader(input)
dec := jsontext.NewDecoder(in)
out := new(bytes.Buffer)
enc := jsontext.NewEncoder(out, jsontext.Multiline(true)) // expand for readability
for {
// Read a token from the input.
tok, err := dec.ReadToken()
if err != nil {
if err == io.EOF {
break
}
log.Fatal(err)
}
// Check whether the token contains the string "Golang" and
// replace each occurrence with "Go" instead.
if tok.Kind() == '"' && strings.Contains(tok.String(), "Golang") {
replacements = append(replacements, dec.StackPointer())
tok = jsontext.String(strings.ReplaceAll(tok.String(), "Golang", "Go"))
}
// Write the (possibly modified) token to the output.
if err := enc.WriteToken(tok); err != nil {
log.Fatal(err)
}
}
// Print the list of replacements and the adjusted JSON output.
if len(replacements) > 0 {
fmt.Println(`Replaced "Golang" with "Go" in:`)
for _, where := range replacements {
fmt.Println("\t" + where)
}
fmt.Println()
}
fmt.Println("Result:", out.String())
}
Package-Level Type Names (total 8)
/* sort by: | */
Decoder is a streaming decoder for raw JSON tokens and values.
It is used to read a stream of top-level JSON values,
each separated by optional whitespace characters.
[Decoder.ReadToken] and [Decoder.ReadValue] calls may be interleaved.
For example, the following JSON value:
{"name":"value","array":[null,false,true,3.14159],"object":{"k":"v"}}
can be parsed with the following calls (ignoring errors for brevity):
d.ReadToken() // {
d.ReadToken() // "name"
d.ReadToken() // "value"
d.ReadValue() // "array"
d.ReadToken() // [
d.ReadToken() // null
d.ReadToken() // false
d.ReadValue() // true
d.ReadToken() // 3.14159
d.ReadToken() // ]
d.ReadValue() // "object"
d.ReadValue() // {"k":"v"}
d.ReadToken() // }
The above is one of many possible sequence of calls and
may not represent the most sensible method to call for any given token/value.
For example, it is probably more common to call [Decoder.ReadToken] to obtain a
string token for object names. InputOffset returns the current input byte offset. It gives the location
of the next byte immediately after the most recently returned token or value.
The number of bytes actually read from the underlying [io.Reader] may be more
than this offset due to internal buffering effects. Options returns the options used to construct the encoder and
may additionally contain semantic options passed to a
[encoding/json/v2.UnmarshalDecode] call.
If operating within
a [encoding/json/v2.UnmarshalerFrom.UnmarshalJSONFrom] method call or
a [encoding/json/v2.UnmarshalFromFunc] function call,
then the returned options are only valid within the call. PeekKind retrieves the next token kind, but does not advance the read offset.
It returns 0 if an error occurs. Any such error is cached until
the next read call and it is the caller's responsibility to eventually
follow up a PeekKind call with a read call. ReadToken reads the next [Token], advancing the read offset.
The returned token is only valid until the next Peek, Read, or Skip call.
It returns [io.EOF] if there are no more tokens. ReadValue returns the next raw JSON value, advancing the read offset.
The value is stripped of any leading or trailing whitespace and
contains the exact bytes of the input, which may contain invalid UTF-8
if [AllowInvalidUTF8] is specified.
The returned value is only valid until the next Peek, Read, or Skip call and
may not be mutated while the Decoder remains in use.
If the decoder is currently at the end token for an object or array,
then it reports a [SyntacticError] and the internal state remains unchanged.
It returns [io.EOF] if there are no more values. Reset resets a decoder such that it is reading afresh from r and
configured with the provided options. Reset must not be called on an
a Decoder passed to the [encoding/json/v2.UnmarshalerFrom.UnmarshalJSONFrom] method
or the [encoding/json/v2.UnmarshalFromFunc] function. SkipValue is semantically equivalent to calling [Decoder.ReadValue] and discarding
the result except that memory is not wasted trying to hold the entire result. StackDepth returns the depth of the state machine for read JSON data.
Each level on the stack represents a nested JSON object or array.
It is incremented whenever an [BeginObject] or [BeginArray] token is encountered
and decremented whenever an [EndObject] or [EndArray] token is encountered.
The depth is zero-indexed, where zero represents the top-level JSON value. StackIndex returns information about the specified stack level.
It must be a number between 0 and [Decoder.StackDepth], inclusive.
For each level, it reports the kind:
- 0 for a level of zero,
- '{' for a level representing a JSON object, and
- '[' for a level representing a JSON array.
It also reports the length of that JSON object or array.
Each name and value in a JSON object is counted separately,
so the effective number of members would be half the length.
A complete JSON object must have an even length. StackPointer returns a JSON Pointer (RFC 6901) to the most recently read value. UnreadBuffer returns the data remaining in the unread buffer,
which may contain zero or more bytes.
The returned buffer must not be mutated while Decoder continues to be used.
The buffer contents are valid until the next Peek, Read, or Skip call.
func NewDecoder(r io.Reader, opts ...Options) *Decoder
func encoding/json.(*Number).UnmarshalJSONFrom(dec *Decoder) error
func encoding/json/v2.UnmarshalDecode(in *Decoder, out any, opts ...json.Options) (err error)
func encoding/json/v2.UnmarshalerFrom.UnmarshalJSONFrom(*Decoder) error
Encoder is a streaming encoder from raw JSON tokens and values.
It is used to write a stream of top-level JSON values,
each terminated with a newline character.
[Encoder.WriteToken] and [Encoder.WriteValue] calls may be interleaved.
For example, the following JSON value:
{"name":"value","array":[null,false,true,3.14159],"object":{"k":"v"}}
can be composed with the following calls (ignoring errors for brevity):
e.WriteToken(BeginObject) // {
e.WriteToken(String("name")) // "name"
e.WriteToken(String("value")) // "value"
e.WriteValue(Value(`"array"`)) // "array"
e.WriteToken(BeginArray) // [
e.WriteToken(Null) // null
e.WriteToken(False) // false
e.WriteValue(Value("true")) // true
e.WriteToken(Float(3.14159)) // 3.14159
e.WriteToken(EndArray) // ]
e.WriteValue(Value(`"object"`)) // "object"
e.WriteValue(Value(`{"k":"v"}`)) // {"k":"v"}
e.WriteToken(EndObject) // }
The above is one of many possible sequence of calls and
may not represent the most sensible method to call for any given token/value.
For example, it is probably more common to call [Encoder.WriteToken] with a string
for object names. Options returns the options used to construct the decoder and
may additionally contain semantic options passed to a
[encoding/json/v2.MarshalEncode] call.
If operating within
a [encoding/json/v2.MarshalerTo.MarshalJSONTo] method call or
a [encoding/json/v2.MarshalToFunc] function call,
then the returned options are only valid within the call. OutputOffset returns the current output byte offset. It gives the location
of the next byte immediately after the most recently written token or value.
The number of bytes actually written to the underlying [io.Writer] may be less
than this offset due to internal buffering effects. Reset resets an encoder such that it is writing afresh to w and
configured with the provided options. Reset must not be called on
a Encoder passed to the [encoding/json/v2.MarshalerTo.MarshalJSONTo] method
or the [encoding/json/v2.MarshalToFunc] function. StackDepth returns the depth of the state machine for written JSON data.
Each level on the stack represents a nested JSON object or array.
It is incremented whenever an [BeginObject] or [BeginArray] token is encountered
and decremented whenever an [EndObject] or [EndArray] token is encountered.
The depth is zero-indexed, where zero represents the top-level JSON value. StackIndex returns information about the specified stack level.
It must be a number between 0 and [Encoder.StackDepth], inclusive.
For each level, it reports the kind:
- 0 for a level of zero,
- '{' for a level representing a JSON object, and
- '[' for a level representing a JSON array.
It also reports the length of that JSON object or array.
Each name and value in a JSON object is counted separately,
so the effective number of members would be half the length.
A complete JSON object must have an even length. StackPointer returns a JSON Pointer (RFC 6901) to the most recently written value. UnusedBuffer returns a zero-length buffer with a possible non-zero capacity.
This buffer is intended to be used to populate a [Value]
being passed to an immediately succeeding [Encoder.WriteValue] call.
Example usage:
b := d.UnusedBuffer()
b = append(b, '"')
b = appendString(b, v) // append the string formatting of v
b = append(b, '"')
... := d.WriteValue(b)
It is the user's responsibility to ensure that the value is valid JSON. WriteToken writes the next token and advances the internal write offset.
The provided token kind must be consistent with the JSON grammar.
For example, it is an error to provide a number when the encoder
is expecting an object name (which is always a string), or
to provide an end object delimiter when the encoder is finishing an array.
If the provided token is invalid, then it reports a [SyntacticError] and
the internal state remains unchanged. The offset reported
in [SyntacticError] will be relative to the [Encoder.OutputOffset]. WriteValue writes the next raw value and advances the internal write offset.
The Encoder does not simply copy the provided value verbatim, but
parses it to ensure that it is syntactically valid and reformats it
according to how the Encoder is configured to format whitespace and strings.
If [AllowInvalidUTF8] is specified, then any invalid UTF-8 is mangled
as the Unicode replacement character, U+FFFD.
The provided value kind must be consistent with the JSON grammar
(see examples on [Encoder.WriteToken]). If the provided value is invalid,
then it reports a [SyntacticError] and the internal state remains unchanged.
The offset reported in [SyntacticError] will be relative to the
[Encoder.OutputOffset] plus the offset into v of any encountered syntax error.
func NewEncoder(w io.Writer, opts ...Options) *Encoder
func encoding/json.Number.MarshalJSONTo(enc *Encoder) error
func encoding/json/v2.MarshalEncode(out *Encoder, in any, opts ...json.Options) (err error)
func encoding/json/v2.MarshalerTo.MarshalJSONTo(*Encoder) error
Kind represents each possible JSON token kind with a single byte,
which is conveniently the first byte of that kind's grammar
with the restriction that numbers always be represented with '0':
- 'n': null
- 'f': false
- 't': true
- '"': string
- '0': number
- '{': object start
- '}': object end
- '[': array start
- ']': array end
An invalid kind is usually represented using 0,
but may be non-zero due to invalid JSON data. String prints the kind in a humanly readable fashion.
Kind : expvar.Var
Kind : fmt.Stringer
func (*Decoder).PeekKind() Kind
func (*Decoder).StackIndex(i int) (Kind, int64)
func (*Encoder).StackIndex(i int) (Kind, int64)
func Token.Kind() Kind
func Value.Kind() Kind
Options configures [NewEncoder], [Encoder.Reset], [NewDecoder],
and [Decoder.Reset] with specific features.
Each function takes in a variadic list of options, where properties
set in latter options override the value of previously set properties.
There is a single Options type, which is used with both encoding and decoding.
Some options affect both operations, while others only affect one operation:
- [AllowDuplicateNames] affects encoding and decoding
- [AllowInvalidUTF8] affects encoding and decoding
- [EscapeForHTML] affects encoding only
- [EscapeForJS] affects encoding only
- [PreserveRawStrings] affects encoding only
- [CanonicalizeRawInts] affects encoding only
- [CanonicalizeRawFloats] affects encoding only
- [ReorderRawObjects] affects encoding only
- [SpaceAfterColon] affects encoding only
- [SpaceAfterComma] affects encoding only
- [Multiline] affects encoding only
- [WithIndent] affects encoding only
- [WithIndentPrefix] affects encoding only
Options that do not affect a particular operation are ignored.
The Options type is identical to [encoding/json.Options] and
[encoding/json/v2.Options]. Options from the other packages may
be passed to functionality in this package, but are ignored.
Options from this package may be used with the other packages.
Pointer is a JSON Pointer (RFC 6901) that references a particular JSON value
relative to the root of the top-level JSON value.
A Pointer is a slash-separated list of tokens, where each token is
either a JSON object name or an index to a JSON array element
encoded as a base-10 integer value.
It is impossible to distinguish between an array index and an object name
(that happens to be an base-10 encoded integer) without also knowing
the structure of the top-level JSON value that the pointer refers to.
There is exactly one representation of a pointer to a particular value,
so comparability of Pointer values is equivalent to checking whether
they both point to the exact same value. AppendToken appends a token to the end of p and returns the full pointer. Contains reports whether the JSON value that p points to
is equal to or contains the JSON value that pc points to. IsValid reports whether p is a valid JSON Pointer according to RFC 6901.
Note that the concatenation of two valid pointers produces a valid pointer. LastToken returns the last token in the pointer.
The last token of an empty p is an empty string. Parent strips off the last token and returns the remaining pointer.
The parent of an empty p is an empty string. Tokens returns an iterator over the reference tokens in the JSON pointer,
starting from the first token until the last token (unless stopped early).
Pointer : database/sql/driver.Validator
func (*Decoder).StackPointer() Pointer
func (*Encoder).StackPointer() Pointer
func Pointer.AppendToken(tok string) Pointer
func Pointer.Parent() Pointer
func Pointer.Contains(pc Pointer) bool
SyntacticError is a description of a syntactic error that occurred when
encoding or decoding JSON according to the grammar.
The contents of this error as produced by this package may change over time. ByteOffset indicates that an error occurred after this byte offset. Err is the underlying error. JSONPointer indicates that an error occurred within this JSON value
as indicated using the JSON Pointer notation (see RFC 6901).(*SyntacticError) Error() string(*SyntacticError) Unwrap() error
*SyntacticError : error
Token represents a lexical JSON token, which may be one of the following:
- a JSON literal (i.e., null, true, or false)
- a JSON string (e.g., "hello, world!")
- a JSON number (e.g., 123.456)
- a start or end delimiter for a JSON object (i.e., { or } )
- a start or end delimiter for a JSON array (i.e., [ or ] )
A Token cannot represent entire array or object values, while a [Value] can.
There is no Token to represent commas and colons since
these structural tokens can be inferred from the surrounding context. Bool returns the value for a JSON boolean.
It panics if the token kind is not a JSON boolean. Clone makes a copy of the Token such that its value remains valid
even after a subsequent [Decoder.Read] call. Float returns the floating-point value for a JSON number.
It returns a NaN, +Inf, or -Inf value for any JSON string
with the values "NaN", "Infinity", or "-Infinity".
It panics for all other cases. Int returns the signed integer value for a JSON number.
The fractional component of any number is ignored (truncation toward zero).
Any number beyond the representation of an int64 will be saturated
to the closest representable value.
It panics if the token kind is not a JSON number. Kind returns the token kind. String returns the unescaped string value for a JSON string.
For other JSON kinds, this returns the raw JSON representation. Uint returns the unsigned integer value for a JSON number.
The fractional component of any number is ignored (truncation toward zero).
Any number beyond the representation of an uint64 will be saturated
to the closest representable value.
It panics if the token kind is not a JSON number.
Token : expvar.Var
Token : fmt.Stringer
func Bool(b bool) Token
func Float(n float64) Token
func Int(n int64) Token
func String(s string) Token
func Uint(n uint64) Token
func (*Decoder).ReadToken() (Token, error)
func Token.Clone() Token
func (*Encoder).WriteToken(t Token) error
var BeginArray
var BeginObject
var EndArray
var EndObject
var False
var Null
var True
Value represents a single raw JSON value, which may be one of the following:
- a JSON literal (i.e., null, true, or false)
- a JSON string (e.g., "hello, world!")
- a JSON number (e.g., 123.456)
- an entire JSON object (e.g., {"fizz":"buzz"} )
- an entire JSON array (e.g., [1,2,3] )
Value can represent entire array or object values, while [Token] cannot.
Value may contain leading and/or trailing whitespace. Canonicalize canonicalizes the raw JSON value according to the
JSON Canonicalization Scheme (JCS) as defined by RFC 8785
where it produces a stable representation of a JSON value.
JSON strings are formatted to use their minimal representation,
JSON numbers are formatted as double precision numbers according
to some stable serialization algorithm.
JSON object members are sorted in ascending order by name.
All whitespace is removed.
The output stability is dependent on the stability of the application data
(see RFC 8785, Appendix E). It cannot produce stable output from
fundamentally unstable input. For example, if the JSON value
contains ephemeral data (e.g., a frequently changing timestamp),
then the value is still unstable regardless of whether this is called.
Canonicalize is equivalent to calling [Value.Format] with the following options:
- [CanonicalizeRawInts](true)
- [CanonicalizeRawFloats](true)
- [ReorderRawObjects](true)
Any options specified by the caller are applied after the initial set
and may deliberately override prior options.
Note that JCS treats all JSON numbers as IEEE 754 double precision numbers.
Any numbers with precision beyond what is representable by that form
will lose their precision when canonicalized. For example, integer values
beyond ±2⁵³ will lose their precision. To preserve the original representation
of JSON integers, additionally set [CanonicalizeRawInts] to false:
v.Canonicalize(jsontext.CanonicalizeRawInts(false)) Clone returns a copy of v. Compact removes all whitespace from the raw JSON value.
It does not reformat JSON strings or numbers to use any other representation.
To maximize the set of JSON values that can be formatted,
this permits values with duplicate names and invalid UTF-8.
Compact is equivalent to calling [Value.Format] with the following options:
- [AllowDuplicateNames](true)
- [AllowInvalidUTF8](true)
- [PreserveRawStrings](true)
Any options specified by the caller are applied after the initial set
and may deliberately override prior options. Format formats the raw JSON value in place.
By default (if no options are specified), it validates according to RFC 7493
and produces the minimal JSON representation, where
all whitespace is elided and JSON strings use the shortest encoding.
Relevant options include:
- [AllowDuplicateNames]
- [AllowInvalidUTF8]
- [EscapeForHTML]
- [EscapeForJS]
- [PreserveRawStrings]
- [CanonicalizeRawInts]
- [CanonicalizeRawFloats]
- [ReorderRawObjects]
- [SpaceAfterColon]
- [SpaceAfterComma]
- [Multiline]
- [WithIndent]
- [WithIndentPrefix]
All other options are ignored.
It is guaranteed to succeed if the value is valid according to the same options.
If the value is already formatted, then the buffer is not mutated. Indent reformats the whitespace in the raw JSON value so that each element
in a JSON object or array begins on a indented line according to the nesting.
It does not reformat JSON strings or numbers to use any other representation.
To maximize the set of JSON values that can be formatted,
this permits values with duplicate names and invalid UTF-8.
Indent is equivalent to calling [Value.Format] with the following options:
- [AllowDuplicateNames](true)
- [AllowInvalidUTF8](true)
- [PreserveRawStrings](true)
- [Multiline](true)
Any options specified by the caller are applied after the initial set
and may deliberately override prior options. IsValid reports whether the raw JSON value is syntactically valid
according to the specified options.
By default (if no options are specified), it validates according to RFC 7493.
It verifies whether the input is properly encoded as UTF-8,
that escape sequences within strings decode to valid Unicode codepoints, and
that all names in each object are unique.
It does not verify whether numbers are representable within the limits
of any common numeric type (e.g., float64, int64, or uint64).
Relevant options include:
- [AllowDuplicateNames]
- [AllowInvalidUTF8]
All other options are ignored. Kind returns the starting token kind.
For a valid value, this will never include '}' or ']'. MarshalJSON returns v as the JSON encoding of v.
It returns the stored value as the raw JSON output without any validation.
If v is nil, then this returns a JSON null. String returns the string formatting of v. UnmarshalJSON sets v as the JSON encoding of b.
It stores a copy of the provided raw JSON input without any validation.
Value : encoding/json/v2.Marshaler
*Value : encoding/json/v2.Unmarshaler
Value : expvar.Var
Value : fmt.Stringer
func (*Decoder).ReadValue() (Value, error)
func Value.Clone() Value
func (*Encoder).WriteValue(v Value) error
Package-Level Functions (total 23)
AllowDuplicateNames specifies that JSON objects may contain
duplicate member names. Disabling the duplicate name check may provide
performance benefits, but breaks compliance with RFC 7493, section 2.3.
The input or output will still be compliant with RFC 8259,
which leaves the handling of duplicate names as unspecified behavior.
This affects either encoding or decoding.
AllowInvalidUTF8 specifies that JSON strings may contain invalid UTF-8,
which will be mangled as the Unicode replacement character, U+FFFD.
This causes the encoder or decoder to break compliance with
RFC 7493, section 2.1, and RFC 8259, section 8.1.
This affects either encoding or decoding.
AppendFormat formats the JSON value in src and appends it to dst
according to the specified options.
See [Value.Format] for more details about the formatting behavior.
The dst and src may overlap.
If an error is reported, then the entirety of src is appended to dst.
Type Parameters:
Bytes: ~[]byte | ~string AppendQuote appends a double-quoted JSON string literal representing src
to dst and returns the extended buffer.
It uses the minimal string representation per RFC 8785, section 3.2.2.2.
Invalid UTF-8 bytes are replaced with the Unicode replacement character
and an error is returned at the end indicating the presence of invalid UTF-8.
The dst must not overlap with the src.
Type Parameters:
Bytes: ~[]byte | ~string AppendUnquote appends the decoded interpretation of src as a
double-quoted JSON string literal to dst and returns the extended buffer.
The input src must be a JSON string without any surrounding whitespace.
Invalid UTF-8 bytes are replaced with the Unicode replacement character
and an error is returned at the end indicating the presence of invalid UTF-8.
Any trailing bytes after the JSON string literal results in an error.
The dst must not overlap with the src.
Bool constructs a Token representing a JSON boolean.
CanonicalizeRawFloats specifies that when encoding a raw JSON
floating-point number (i.e., a number with a fraction or exponent) in a
[Token] or [Value], the number is canonicalized
according to RFC 8785, section 3.2.2.3. As a special case,
the number -0 is canonicalized as 0.
JSON numbers are treated as IEEE 754 double precision numbers.
It is safe to canonicalize a serialized single precision number and
parse it back as a single precision number and expect the same value.
If a number exceeds ±1.7976931348623157e+308, which is the maximum
finite number, then it saturated at that value and formatted as such.
This only affects encoding and is ignored when decoding.
CanonicalizeRawInts specifies that when encoding a raw JSON
integer number (i.e., a number without a fraction and exponent) in a
[Token] or [Value], the number is canonicalized
according to RFC 8785, section 3.2.2.3. As a special case,
the number -0 is canonicalized as 0.
JSON numbers are treated as IEEE 754 double precision numbers.
Any numbers with precision beyond what is representable by that form
will lose their precision when canonicalized. For example,
integer values beyond ±2⁵³ will lose their precision.
For example, 1234567890123456789 is formatted as 1234567890123456800.
This only affects encoding and is ignored when decoding.
EscapeForHTML specifies that '<', '>', and '&' characters within JSON strings
should be escaped as a hexadecimal Unicode codepoint (e.g., \u003c) so that
the output is safe to embed within HTML.
This only affects encoding and is ignored when decoding.
EscapeForJS specifies that U+2028 and U+2029 characters within JSON strings
should be escaped as a hexadecimal Unicode codepoint (e.g., \u2028) so that
the output is valid to embed within JavaScript. See RFC 8259, section 12.
This only affects encoding and is ignored when decoding.
Float constructs a Token representing a JSON number.
The values NaN, +Inf, and -Inf will be represented
as a JSON string with the values "NaN", "Infinity", and "-Infinity".
Int constructs a Token representing a JSON number from an int64.
Multiline specifies that the JSON output should expand to multiple lines,
where every JSON object member or JSON array element appears on
a new, indented line according to the nesting depth.
If [SpaceAfterColon] is not specified, then the default is true.
If [SpaceAfterComma] is not specified, then the default is false.
If [WithIndent] is not specified, then the default is "\t".
If set to false, then the output is a single-line,
where the only whitespace emitted is determined by the current
values of [SpaceAfterColon] and [SpaceAfterComma].
This only affects encoding and is ignored when decoding.
NewDecoder constructs a new streaming decoder reading from r.
If r is a [bytes.Buffer], then the decoder parses directly from the buffer
without first copying the contents to an intermediate buffer.
Additional writes to the buffer must not occur while the decoder is in use.
NewEncoder constructs a new streaming encoder writing to w
configured with the provided options.
It flushes the internal buffer when the buffer is sufficiently full or
when a top-level value has been written.
If w is a [bytes.Buffer], then the encoder appends directly into the buffer
without copying the contents from an intermediate buffer.
PreserveRawStrings specifies that when encoding a raw JSON string in a
[Token] or [Value], pre-escaped sequences
in a JSON string are preserved to the output.
However, raw strings still respect [EscapeForHTML] and [EscapeForJS]
such that the relevant characters are escaped.
If [AllowInvalidUTF8] is enabled, bytes of invalid UTF-8
are preserved to the output.
This only affects encoding and is ignored when decoding.
ReorderRawObjects specifies that when encoding a raw JSON object in a
[Value], the object members are reordered according to
RFC 8785, section 3.2.3.
This only affects encoding and is ignored when decoding.
SpaceAfterColon specifies that the JSON output should emit a space character
after each colon separator following a JSON object name.
If false, then no space character appears after the colon separator.
This only affects encoding and is ignored when decoding.
SpaceAfterComma specifies that the JSON output should emit a space character
after each comma separator following a JSON object value or array element.
If false, then no space character appears after the comma separator.
This only affects encoding and is ignored when decoding.
String constructs a Token representing a JSON string.
The provided string should contain valid UTF-8, otherwise invalid characters
may be mangled as the Unicode replacement character.
Uint constructs a Token representing a JSON number from a uint64.
WithIndent specifies that the encoder should emit multiline output
where each element in a JSON object or array begins on a new, indented line
beginning with the indent prefix (see [WithIndentPrefix])
followed by one or more copies of indent according to the nesting depth.
The indent must only be composed of space or tab characters.
If the intent to emit indented output without a preference for
the particular indent string, then use [Multiline] instead.
This only affects encoding and is ignored when decoding.
Use of this option implies [Multiline] being set to true.
WithIndentPrefix specifies that the encoder should emit multiline output
where each element in a JSON object or array begins on a new, indented line
beginning with the indent prefix followed by one or more copies of indent
(see [WithIndent]) according to the nesting depth.
The prefix must only be composed of space or tab characters.
This only affects encoding and is ignored when decoding.
Use of this option implies [Multiline] being set to true.
ErrDuplicateName indicates that a JSON token could not be
encoded or decoded because it results in a duplicate JSON object name.
This error is directly wrapped within a [SyntacticError] when produced.
The name of a duplicate JSON object member can be extracted as:
err := ...
var serr jsontext.SyntacticError
if errors.As(err, &serr) && serr.Err == jsontext.ErrDuplicateName {
ptr := serr.JSONPointer // JSON pointer to duplicate name
name := ptr.LastToken() // duplicate name itself
...
}
This error is only returned if [AllowDuplicateNames] is false.
ErrNonStringName indicates that a JSON token could not be
encoded or decoded because it is not a string,
as required for JSON object names according to RFC 8259, section 4.
This error is directly wrapped within a [SyntacticError] when produced.
The pages are generated with Goldsv0.7.7-preview. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.
