Skip to content
Goalchemy

std/encoding/jsonvalue

import "github.com/eugenioenko/goalchemy/std/encoding/jsonvalue"

Package jsonvalue parses, inspects, builds and encodes JSON documents of any shape as a tree of Values, without declaring Go types. Numbers keep their exact source text, so integers beyond 2^53 and long decimals round-trip unchanged. Object members keep their order, and duplicate member names are rejected. Parsing and encoding are bounded by Limits. Accessors never panic: a missing member, an out-of-range index or a value of another kind yields the zero result.

const MaxDepth = 128

MaxDepth is the largest nesting depth Limits may allow.

Encode

Section titled “Encode”
func Encode(v Value) ([]byte, error)

Encode returns the compact JSON encoding of v with DefaultLimits.

EncodeWithLimits

Section titled “EncodeWithLimits”
func EncodeWithLimits(v Value, l Limits) ([]byte, error)

EncodeWithLimits returns the compact JSON encoding of v. Strings are escaped exactly as encoding/json.Marshal escapes them, including <, > and & as <, > and &, U+2028 and U+2029, and invalid UTF-8 as �. Numbers are written from their source text.

type InvalidValueError

Section titled “type InvalidValueError”
type InvalidValueError struct {
  Msg string
}

InvalidValueError reports a Value that cannot be encoded: a number that is not valid JSON (including NaN and infinities), an object with duplicate member names, or an invalid Value.

InvalidValueError.Error

Section titled “InvalidValueError.Error”
func (e *InvalidValueError) Error() string

type Kind

Section titled “type Kind”
type Kind int

Kind identifies the JSON type of a Value.

const (
  KindInvalid Kind = iota
  KindNull
  KindBool
  KindNumber
  KindString
  KindArray
  KindObject
)

Kind.String

Section titled “Kind.String”
func (k Kind) String() string

type LimitError

Section titled “type LimitError”
type LimitError struct {
  Limit string
}

LimitError reports that parsing or encoding exceeded one of the Limits. Limit names it: “bytes”, “depth”, “nodes”, “string bytes” or “limits” when the Limits themselves are invalid.

LimitError.Error

Section titled “LimitError.Error”
func (e *LimitError) Error() string

type Limits

Section titled “type Limits”
type Limits struct {
  Bytes       int
  Depth       int
  Nodes       int
  StringBytes int
}

Limits bounds the work done by parsing and encoding. Depth counts nested arrays and objects, Nodes counts values, and StringBytes bounds each string after unescaping. Depth must not exceed MaxDepth.

DefaultLimits

Section titled “DefaultLimits”
func DefaultLimits() Limits

DefaultLimits returns the limits Parse and Encode use: 16 MiB of input or output, nesting depth 128, 1Mi values and 16 MiB per string.

type SyntaxError

Section titled “type SyntaxError”
type SyntaxError struct {
  Msg    string
  Offset int
}

SyntaxError describes invalid JSON input. Offset is the byte offset at which the error was detected.

SyntaxError.Error

Section titled “SyntaxError.Error”
func (e *SyntaxError) Error() string

type Value

Section titled “type Value”
type Value struct {
}

Value is one JSON value. The zero Value is invalid: it is what lookups of missing members and out-of-range indexes return.

Array

Section titled “Array”
func Array(elems ...Value) Value

Array returns a JSON array of elems.

Bool

Section titled “Bool”
func Bool(b bool) Value

Bool returns a JSON boolean.

Float

Section titled “Float”
func Float(f float64) Value

Float returns a JSON number formatted as encoding/json formats a float64: the shortest representation that round-trips, in exponent form below 1e-6 and from 1e21. NaN and infinities produce a Value that Encode rejects.

Int

Section titled “Int”
func Int(n int64) Value

Int returns a JSON number holding n exactly.

Null

Section titled “Null”
func Null() Value

Null returns the JSON null value.

Number

Section titled “Number”
func Number(text string) Value

Number returns a JSON number with the given source text, such as “12345678901234567890” or “1.50e+3”. Encode rejects text that is not a valid JSON number.

Object

Section titled “Object”
func Object(keyvals ...any) Value

Object returns a JSON object from alternating string keys and Value values, in order. It panics if the arguments do not alternate that way.

Parse

Section titled “Parse”
func Parse(data []byte) (Value, error)

Parse parses one JSON document with DefaultLimits.

ParseWithLimits

Section titled “ParseWithLimits”
func ParseWithLimits(data []byte, l Limits) (Value, error)

ParseWithLimits parses one JSON document. Surrounding whitespace is allowed; any other trailing input is an error. Invalid UTF-8 and unpaired surrogate escapes in strings become U+FFFD, as in encoding/json.

String

Section titled “String”
func String(s string) Value

String returns a JSON string. Invalid UTF-8 is encoded as U+FFFD.

Uint

Section titled “Uint”
func Uint(n uint64) Value

Uint returns a JSON number holding n exactly.

Value.Append

Section titled “Value.Append”
func (v Value) Append(elems ...Value) Value

Append returns a copy of the array v with elems added at the end. If v is not an array, Append returns a new array holding only elems.

Value.AsBool

Section titled “Value.AsBool”
func (v Value) AsBool() (bool, bool)

AsBool returns the value of a JSON boolean.

Value.AsFloat64

Section titled “Value.AsFloat64”
func (v Value) AsFloat64() (float64, bool)

AsFloat64 returns the float64 nearest to a JSON number. Numbers beyond the float64 range are rejected.

Value.AsInt64

Section titled “Value.AsInt64”
func (v Value) AsInt64() (int64, bool)

AsInt64 returns a JSON number written as an integer that fits in int64. Numbers with a fraction or exponent, such as 1.0 or 1e3, are rejected.

Value.AsString

Section titled “Value.AsString”
func (v Value) AsString() (string, bool)

AsString returns the content of a JSON string.

Value.AsUint64

Section titled “Value.AsUint64”
func (v Value) AsUint64() (uint64, bool)

AsUint64 returns a JSON number written as a nonnegative integer that fits in uint64.

Value.Bool

Section titled “Value.Bool”
func (v Value) Bool() bool

Bool returns the value of a JSON boolean, or false.

Value.Exists

Section titled “Value.Exists”
func (v Value) Exists() bool

Exists reports whether v is a value rather than the result of a failed lookup.

Value.Float64

Section titled “Value.Float64”
func (v Value) Float64() float64

Float64 returns the result of AsFloat64, or 0.

Value.Get

Section titled “Value.Get”
func (v Value) Get(key string) Value

Get returns the member key of the object v, or the zero Value.

Value.Has

Section titled “Value.Has”
func (v Value) Has(key string) bool

Has reports whether the object v has a member key.

Value.Index

Section titled “Value.Index”
func (v Value) Index(i int) Value

Index returns element i of the array v, or the zero Value.

Value.Int64

Section titled “Value.Int64”
func (v Value) Int64() int64

Int64 returns the result of AsInt64, or 0.

Value.IsNull

Section titled “Value.IsNull”
func (v Value) IsNull() bool

IsNull reports whether v is JSON null.

Value.Keys

Section titled “Value.Keys”
func (v Value) Keys() []string

Keys returns the member names of the object v in order.

Value.Kind

Section titled “Value.Kind”
func (v Value) Kind() Kind

Kind returns the JSON type of v.

Value.Len

Section titled “Value.Len”
func (v Value) Len() int

Len returns the number of elements of an array or members of an object, and 0 for other kinds.

Value.Lookup

Section titled “Value.Lookup”
func (v Value) Lookup(key string) (Value, bool)

Lookup returns the member key of the object v.

Value.MarshalJSON

Section titled “Value.MarshalJSON”
func (v Value) MarshalJSON() ([]byte, error)

MarshalJSON returns Encode(v), so a Value encodes as itself when it is passed to, or is a field of a value passed to, json.Marshal.

Value.Number

Section titled “Value.Number”
func (v Value) Number() string

Number returns the source text of a JSON number, or “”.

Value.Set

Section titled “Value.Set”
func (v Value) Set(key string, x Value) Value

Set returns a copy of the object v with member key set to x, replacing an existing member in place or appending a new one. If v is not an object, Set returns a new object holding only that member.

Value.String

Section titled “Value.String”
func (v Value) String() string

String returns the content of a JSON string, the compact encoding of any other value, and “” for the zero Value or a Value that cannot be encoded. Use AsString to require a string.

Value.Uint64

Section titled “Value.Uint64”
func (v Value) Uint64() uint64

Uint64 returns the result of AsUint64, or 0.

Value.UnmarshalJSON

Section titled “Value.UnmarshalJSON”
func (v *Value) UnmarshalJSON(data []byte) error

UnmarshalJSON sets *v to Parse(data), so a Value can be the target of, or a field of the target of, json.Unmarshal.