jsontext

package
v0.0.0-...-af2d506 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 18, 2024 License: BSD-3-Clause Imports: 13 Imported by: 16

Documentation

Overview

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.

Example (StringReplace)

This example demonstrates the use of the Encoder and Decoder to parse and modify JSON without unmarshaling it into a concrete Go type. 

package main

import (
	"bytes"
	"fmt"
	"io"
	"log"
	"strings"

	"github.com/go-json-experiment/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())

}

Output:

Replaced "Golang" with "Go" in:
	/title
	/text
	/otherArticles/0
	/otherArticles/2

Result: {
	"title": "Go version 1 is released",
	"author": "Andrew Gerrand",
	"date": "2012-03-28",
	"text": "Today marks a major milestone in the development of the Go programming language.",
	"otherArticles": [
		"Twelve Years of Go",
		"The Laws of Reflection",
		"Learn Go from your browser"
	]
}

Index

Examples

Constants

This section is empty.

Variables

View Source 
var Internal exporter

Internal is for internal use only. This is exempt from the Go compatibility agreement.

Functions

func AppendQuote 

func AppendQuote[Bytes ~[]byte | ~string](dst []byte, src Bytes) ([]byte, error)

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.

func AppendUnquote 

func AppendUnquote[Bytes ~[]byte | ~string](dst []byte, src Bytes) ([]byte, error)

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.

Types

type Decoder 

type Decoder struct {
	// contains filtered or unexported fields
}

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.

func NewDecoder 

func NewDecoder(r io.Reader, opts ...Options) *Decoder

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.

func (*Decoder) InputOffset 

func (d *Decoder) InputOffset() int64

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.

func (*Decoder) PeekKind 

func (d *Decoder) PeekKind() Kind

PeekKind retrieves the next token kind, but does not advance the read offset. It returns 0 if there are no more tokens.

func (*Decoder) ReadToken 

func (d *Decoder) ReadToken() (Token, error)

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.

func (*Decoder) ReadValue 

func (d *Decoder) ReadValue() (Value, error)

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.

func (*Decoder) Reset 

func (d *Decoder) Reset(r io.Reader, opts ...Options)

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.UnmarshalerV2.UnmarshalJSONV2 method or the encoding/json/v2.UnmarshalFuncV2 function.

func (*Decoder) SkipValue 

func (d *Decoder) SkipValue() error

SkipValue is semantically equivalent to calling Decoder.ReadValue and discarding the result except that memory is not wasted trying to hold the entire result.

func (*Decoder) StackDepth 

func (d *Decoder) StackDepth() int

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 ObjectStart or ArrayStart token is encountered and decremented whenever an ObjectEnd or ArrayEnd token is encountered. The depth is zero-indexed, where zero represents the top-level JSON value.

func (*Decoder) StackIndex 

func (d *Decoder) StackIndex(i int) (Kind, int64)

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.

func (*Decoder) StackPointer 

func (d *Decoder) StackPointer() Pointer

StackPointer returns a JSON Pointer (RFC 6901) to the most recently read value. Object names are only present if AllowDuplicateNames is false, otherwise object members are represented using their index within the object.

func (*Decoder) UnreadBuffer 

func (d *Decoder) UnreadBuffer() []byte

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.

type Encoder 

type Encoder struct {
	// contains filtered or unexported fields
}

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(ObjectStart)        // {
e.WriteToken(String("name"))     // "name"
e.WriteToken(String("value"))    // "value"
e.WriteValue(Value(`"array"`))   // "array"
e.WriteToken(ArrayStart)         // [
e.WriteToken(Null)               // null
e.WriteToken(False)              // false
e.WriteValue(Value("true"))      // true
e.WriteToken(Float(3.14159))     // 3.14159
e.WriteToken(ArrayEnd)           // ]
e.WriteValue(Value(`"object"`))  // "object"
e.WriteValue(Value(`{"k":"v"}`)) // {"k":"v"}
e.WriteToken(ObjectEnd)          // }

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.

func NewEncoder 

func NewEncoder(w io.Writer, opts ...Options) *Encoder

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.

func (*Encoder) OutputOffset 

func (e *Encoder) OutputOffset() int64

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.

func (*Encoder) Reset 

func (e *Encoder) Reset(w io.Writer, opts ...Options)

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.MarshalerV2.MarshalJSONV2 method or the encoding/json/v2.MarshalFuncV2 function.

func (*Encoder) StackDepth 

func (e *Encoder) StackDepth() int

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 ObjectStart or ArrayStart token is encountered and decremented whenever an ObjectEnd or ArrayEnd token is encountered. The depth is zero-indexed, where zero represents the top-level JSON value.

func (*Encoder) StackIndex 

func (e *Encoder) StackIndex(i int) (Kind, int64)

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.

func (*Encoder) StackPointer 

func (e *Encoder) StackPointer() Pointer

StackPointer returns a JSON Pointer (RFC 6901) to the most recently written value. Object names are only present if AllowDuplicateNames is false, otherwise object members are represented using their index within the object.

func (*Encoder) UnusedBuffer 

func (e *Encoder) UnusedBuffer() []byte

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.

func (*Encoder) WriteToken 

func (e *Encoder) WriteToken(t Token) error

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.

func (*Encoder) WriteValue 

func (e *Encoder) WriteValue(v Value) error

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.

type Kind 

type Kind byte

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.

func (Kind) String 

func (k Kind) String() string

String prints the kind in a humanly readable fashion.

type Options 

type Options = jsonopts.Options

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.

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.

func AllowDuplicateNames 

func AllowDuplicateNames(v bool) Options

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.

func AllowInvalidUTF8 

func AllowInvalidUTF8(v bool) Options

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.

func EscapeForHTML 

func EscapeForHTML(v bool) Options

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.

Example

Directly embedding JSON within HTML requires special handling for safety. Escape certain runes to prevent JSON directly treated as HTML from being able to perform <script> injection.

This example shows how to obtain equivalent behavior provided by the v1 encoding/json package that is no longer directly supported by this package. Newly written code that intermix JSON and HTML should instead be using the github.com/google/safehtml module for safety purposes. 

package main

import (
	"fmt"
	"log"

	"github.com/go-json-experiment/json"
	"github.com/go-json-experiment/json/jsontext"
)

func main() {
	page := struct {
		Title string
		Body  string
	}{
		Title: "Example Embedded Javascript",
		Body:  `<script> console.log("Hello, world!"); </script>`,
	}

	b, err := json.Marshal(&page,
		// Escape certain runes within a JSON string so that
		// JSON will be safe to directly embed inside HTML.
		jsontext.EscapeForHTML(true),
		jsontext.EscapeForJS(true),
		jsontext.Multiline(true)) // expand for readability
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(string(b))

}

Output:

{
	"Title": "Example Embedded Javascript",
	"Body": "\u003cscript\u003e console.log(\"Hello, world!\"); \u003c/script\u003e"
}

func EscapeForJS 

func EscapeForJS(v bool) Options

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.

func Multiline 

func Multiline(v bool) Options

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.

func SpaceAfterColon 

func SpaceAfterColon(v bool) Options

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.

func SpaceAfterComma 

func SpaceAfterComma(v bool) Options

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.

func WithIndent 

func WithIndent(indent string) Options

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.

func WithIndentPrefix 

func WithIndentPrefix(prefix string) Options

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.

type Pointer 

type Pointer string

Pointer is a JSON Pointer (RFC 6901) that references a particular JSON value relative to the root of the top-level JSON value.

type SyntacticError 

type SyntacticError struct {

	// ByteOffset indicates that an error occurred after this byte offset.
	ByteOffset int64
	// contains filtered or unexported fields
}

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.

func (*SyntacticError) Error 

func (e *SyntacticError) Error() string

type Token 

type Token struct {
	// contains filtered or unexported fields
}

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. 

var (
	Null  Token = rawToken("null")
	False Token = rawToken("false")
	True  Token = rawToken("true")

	ObjectStart Token = rawToken("{")
	ObjectEnd   Token = rawToken("}")
	ArrayStart  Token = rawToken("[")
	ArrayEnd    Token = rawToken("]")
)

func Bool 

func Bool(b bool) Token

Bool constructs a Token representing a JSON boolean.

func Float 

func Float(n float64) Token

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".

func Int 

func Int(n int64) Token

Int constructs a Token representing a JSON number from an int64.

func String 

func String(s string) Token

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.

func Uint 

func Uint(n uint64) Token

Uint constructs a Token representing a JSON number from a uint64.

func (Token) Bool 

func (t Token) Bool() bool

Bool returns the value for a JSON boolean. It panics if the token kind is not a JSON boolean.

func (Token) Clone 

func (t Token) Clone() Token

Clone makes a copy of the Token such that its value remains valid even after a subsequent [Decoder.Read] call.

func (Token) Float 

func (t Token) Float() float64

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.

func (Token) Int 

func (t Token) Int() int64

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.

func (Token) Kind 

func (t Token) Kind() Kind

Kind returns the token kind.

func (Token) String 

func (t Token) String() string

String returns the unescaped string value for a JSON string. For other JSON kinds, this returns the raw JSON representation.

func (Token) Uint 

func (t Token) Uint() uint64

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.

type Value 

type Value []byte

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.

func (*Value) Canonicalize 

func (v *Value) Canonicalize() error

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.

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.

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. It is recommended that int64 and uint64 data types be represented as a JSON string.

It is guaranteed to succeed if the input is valid. If the value is already canonicalized, then the buffer is not mutated.

func (Value) Clone 

func (v Value) Clone() Value

Clone returns a copy of v.

func (*Value) Compact 

func (v *Value) Compact() error

Compact removes all whitespace from the raw JSON value.

It does not reformat JSON strings to use any other representation. It is guaranteed to succeed if the input is valid. If the value is already compacted, then the buffer is not mutated.

func (*Value) Indent 

func (v *Value) Indent(prefix, indent string) error

Indent reformats the whitespace in the raw JSON value so that each element in a JSON object or array begins on a new, indented line beginning with prefix followed by one or more copies of indent according to the nesting. The value does not begin with the prefix nor any indention, to make it easier to embed inside other formatted JSON data.

It does not reformat JSON strings to use any other representation. It is guaranteed to succeed if the input is valid. If the value is already indented properly, then the buffer is not mutated.

The prefix and indent strings must be composed of only spaces and/or tabs.

func (Value) IsValid 

func (v Value) IsValid() bool

IsValid reports whether the raw JSON value is syntactically valid 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).

func (Value) Kind 

func (v Value) Kind() Kind

Kind returns the starting token kind. For a valid value, this will never include '}' or ']'.

func (Value) MarshalJSON 

func (v Value) MarshalJSON() ([]byte, error)

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.

func (Value) String 

func (v Value) String() string

String returns the string formatting of v.

func (*Value) UnmarshalJSON 

func (v *Value) UnmarshalJSON(b []byte) error

UnmarshalJSON sets v as the JSON encoding of b. It stores a copy of the provided raw JSON input without any validation.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.