jscandec

README

Experimental JSON decoder based on jscan

⚠️ Don't use in production! ⚠️

This is an experimental JSON Unmarshaler/Decoder implementation for Go based on jscan. This decoder will be moved to jscan v3 once it's ready for production.

The jscan decoder is expected to be a backward compatible drop-in replacement for encoding/json.

Roadmap:

• Primitive types
• Struct types
  • Type struct{}
  • Recursive struct types
• Slices
• Arrays
• Type any
• Type map
  • string keys
  • encoding.TextUnmarshaler keys
  • Integer keys
• JSON struct tags
  • Case-insensitive key matching (backward-compatibility feature of encoding/json)
  • Option DisallowUnknownFields
  • Option DisableFieldNameUnescaping
  • Option DisableCaseInsensitiveMatching
  • Option DisallowDuplicateNames
  • Struct tag option string
• Pointers
• Type Unmarshaler interface { UnmarshalJSON([]byte) error }
• Type TextUnmarshaler interface { UnmarshalText(text []byte) error }
• encoding/json compatible drop-in replacement package jscandec/std
  • encoding/json compatible error messages

Documentation

Index

• Variables
• func Unmarshal[S []byte | string, T any](s S, t *T) error
• type DecodeOptions
• type Decoder
  • func NewDecoder[S []byte | string, T any](tokenizer *jscan.Tokenizer[S], options *InitOptions) (*Decoder[S, T], error)
  • func (d *Decoder[S, T]) Decode(s S, t *T, options *DecodeOptions) (errIndex int, err error)
• type ExpectType
  • func (t ExpectType) String() string
• type InitOptions
• type Number
  • func (n Number) Float64() (float64, error)
  • func (n Number) Int64() (int64, error)
  • func (n Number) String() string

Variables

var (
	ErrStringTagOptionOnUnsupportedType = errors.New(
		"invalid use of the `string` tag option on unsupported type",
	)
	ErrNilDest         = errors.New("decoding to nil pointer")
	ErrUnexpectedValue = errors.New("unexpected value")
	ErrUnknownField    = errors.New("unknown field")
	ErrIntegerOverflow = errors.New("integer overflow")
)

var DefaultInitOptions = &InitOptions{
	DisallowStringTagOptOnUnsupportedTypes: false,
}

DefaultInitOptions are to be used by default. DO NOT MUTATE.

var DefaultOptions = &DecodeOptions{
	DisallowUnknownFields: false,
}

DefaultOptions are to be used by default. DO NOT MUTATE.

Functions

func Unmarshal

func Unmarshal[S []byte | string, T any](s S, t *T) error

Unmarshal dynamically allocates new decoder and tokenizer instances and unmarshals the JSON contents of s into t. Unmarshal is primarily a drop-in replacement for the standard encoding/json.Unmarshal and behaves identically except for error messages. To significantly improve performance by avoiding dynamic decoder and tokenizer allocation and reflection at runtime create a reusable decoder instance using NewDecoder.

Types

type DecodeOptions

type DecodeOptions struct {
	// DisallowUnknownFields will make Decode return ErrUnknownField
	// when encountering an unknown struct field.
	DisallowUnknownFields bool

	// DisableFieldNameUnescaping disables unescaping of struct field names
	// before matching which is enabled by default as a backward-compatibility feature
	// of encoding/json.
	//
	// For example, the following JSON input:
	//
	//   `{ "\u0069\u0064": "value" }`
	//
	// will match field ID in the following type:
	//
	//   struct { ID string `json:"id"` }
	//
	// because "\u0069\u0064" is first unescaped to "id" before matching.
	// DisableFieldNameUnescaping=true disables this behavior and will treat
	// property "\u0069\u0064" as an unknown field instead.
	DisableFieldNameUnescaping bool

	// DisableCaseInsensitiveMatching will disable case-insensitive struct field
	// matching that's enabled by default as a backward-compatibility feature
	// of encoding/json.
	//
	// For example, the following JSON input:
	//
	//   `{ "A": 42 }`
	//
	// will match field A in the following type:
	//
	//   struct { A int `json:"a"` }
	//
	// DisableCaseInsensitiveMatching=true disables this behavior and will treat
	// property "A" as an unknown field instead.
	DisableCaseInsensitiveMatching bool
}

DecodeOptions are options for the method *Decoder[S, T].Decode.

type Decoder

type Decoder[S []byte | string, T any] struct {
	// contains filtered or unexported fields
}

Decoder is a reusable decoder instance.

func NewDecoder

func NewDecoder[S []byte | string, T any](
	tokenizer *jscan.Tokenizer[S],
	options *InitOptions,
) (*Decoder[S, T], error)

NewDecoder creates a new reusable decoder instance. In case there are multiple decoder instances for different types of T, tokenizer is recommended to be shared across them, yet the decoders must not be used concurrently!

func (*Decoder[S, T]) Decode

func (d *Decoder[S, T]) Decode(
	s S, t *T, options *DecodeOptions,
) (errIndex int, err error)

Decode unmarshals the JSON contents of s into t. When S is string the decoder will not copy string values and will instead refer to the source string instead since Go strings are guaranteed to be immutable. When S is []byte all strings are copied.

Tip: To improve performance reducing dynamic memory allocations define options as a variable and pass the pointer. Don't initialize it like this:

d.Decode(input, &v, &jscandec.DecodeOptions{DisallowUnknownFields: true})

allocate the options to a variable and pass the variable instead:

d.Decode(input, &v, predefinedOptions)

type ExpectType

type ExpectType int8

const (

	// ExpectTypeNumber is the type `jscandec.Number`
	ExpectTypeNumber ExpectType

	// ExpectTypeJSONUnmarshaler is any type that implements
	// the encoding/json.Unmarshaler interface
	ExpectTypeJSONUnmarshaler

	// ExpectTypeTextUnmarshaler is any type that implements
	// the encoding.TextUnmarshaler interface
	ExpectTypeTextUnmarshaler

	// ExpectTypePtr is any pointer type
	ExpectTypePtr

	// ExpectTypePtrRecur is any recursive pointer type (used for recursive struct fields)
	ExpectTypePtrRecur

	// ExpectTypeAny is type `any`
	ExpectTypeAny

	// ExpectTypeMap is any map type
	ExpectTypeMap

	// ExpectTypeMapStringString is `map[string]string`
	ExpectTypeMapStringString

	// ExpectTypeMapRecur is any recursive map type (used for recursive struct fields)
	ExpectTypeMapRecur

	// ExpectTypeArray is any array type except zero-length array
	ExpectTypeArray

	// ExpectTypeArrayLen0 is any zero-length array type (like [0]int)
	ExpectTypeArrayLen0

	// ExpectTypeSlice is any slice type
	ExpectTypeSlice

	// ExpectTypeSliceRecur is a recursive slice type (used for recursive struct fields)
	ExpectTypeSliceRecur

	// ExpectTypeSliceEmptyStruct is type `[]struct{}`
	ExpectTypeSliceEmptyStruct

	// ExpectTypeSliceBool is type `[]bool`
	ExpectTypeSliceBool

	// ExpectTypeSliceString is type `[]string`
	ExpectTypeSliceString

	// ExpectTypeSliceInt is type `[]int`
	ExpectTypeSliceInt

	// ExpectTypeSliceInt8 is type `[]int8`
	ExpectTypeSliceInt8

	// ExpectTypeSliceInt16 is type `[]int16`
	ExpectTypeSliceInt16

	// ExpectTypeSliceInt32 is type `[]int32`
	ExpectTypeSliceInt32

	// ExpectTypeSliceInt64 is type `[]int64`
	ExpectTypeSliceInt64

	// ExpectTypeSliceUint is type `[]uint`
	ExpectTypeSliceUint

	// ExpectTypeSliceUint8 is type `[]uint8`
	ExpectTypeSliceUint8

	// ExpectTypeSliceUint16 is type `[]uint16`
	ExpectTypeSliceUint16

	// ExpectTypeSliceUint32 is type `[]uint32`
	ExpectTypeSliceUint32

	// ExpectTypeSliceUint64 is type `[]uint64`
	ExpectTypeSliceUint64

	// ExpectTypeSliceFloat32 is type `[]float32`
	ExpectTypeSliceFloat32

	// ExpectTypeSliceFloat64 is type `[]float64`
	ExpectTypeSliceFloat64

	// ExpectTypeStruct is any struct type except `struct{}`
	ExpectTypeStruct

	// ExpectTypeStruct is any recursive struct type
	ExpectTypeStructRecur

	// ExpectTypeEmptyStruct is type `struct{}`
	ExpectTypeEmptyStruct

	// ExpectTypeBool is type `bool`
	ExpectTypeBool

	// ExpectTypeStr is type `string`
	ExpectTypeStr

	// ExpectTypeFloat32 is type `float32`
	ExpectTypeFloat32

	// ExpectTypeFloat64 is type `float64`
	ExpectTypeFloat64

	// ExpectTypeInt is type `int`
	ExpectTypeInt

	// ExpectTypeInt8 is type `int8`
	ExpectTypeInt8

	// ExpectTypeInt16 is type `int16`
	ExpectTypeInt16

	// ExpectTypeInt32 is type `int32`
	ExpectTypeInt32

	// ExpectTypeInt64 is type `int64`
	ExpectTypeInt64

	// ExpectTypeUint is type `uint`
	ExpectTypeUint

	// ExpectTypeUint8 is type `uint8`
	ExpectTypeUint8

	// ExpectTypeUint16 is type `uint16`
	ExpectTypeUint16

	// ExpectTypeUint32 is type `uint32`
	ExpectTypeUint32

	// ExpectTypeUint64 is type `uint64`
	ExpectTypeUint64

	// ExpectTypeBoolString is type `bool` with `json:",string"` tag
	ExpectTypeBoolString

	// ExpectTypeStrString is type `string` with `json:",string"` tag
	ExpectTypeStrString

	// ExpectTypeFloat32String is type `float32` with `json:",string"` tag
	ExpectTypeFloat32String

	// ExpectTypeFloat64String is type `float32` with `json:",string"` tag
	ExpectTypeFloat64String

	// ExpectTypeIntString is type `int` with `json:",string"` tag
	ExpectTypeIntString

	// ExpectTypeInt8String is type `int8` with `json:",string"` tag
	ExpectTypeInt8String

	// ExpectTypeInt16String is type `int16` with `json:",string"` tag
	ExpectTypeInt16String

	// ExpectTypeInt32String is type `int32` with `json:",string"` tag
	ExpectTypeInt32String

	// ExpectTypeInt64String is type `int64` with `json:",string"` tag
	ExpectTypeInt64String

	// ExpectTypeUintString is type `uint` with `json:",string"` tag
	ExpectTypeUintString

	// ExpectTypeUint8String is type `uint8` with `json:",string"` tag
	ExpectTypeUint8String

	// ExpectTypeUint16String is type `uint16` with `json:",string"` tag
	ExpectTypeUint16String

	// ExpectTypeUint32String is type `uint32` with `json:",string"` tag
	ExpectTypeUint32String

	// ExpectTypeUint64String is type `uint64` with `json:",string"` tag
	ExpectTypeUint64String
)

func (ExpectType) String

func (t ExpectType) String() string

type InitOptions

type InitOptions struct {
	// DisallowStringTagOptOnUnsupportedTypes will make NewDecoder return
	// ErrStringTagOptionOnUnsupportedType if a `json:",string"` struct tag option is
	// used on an unsupported type.
	DisallowStringTagOptOnUnsupportedTypes bool
}

InitOptions are options for the constructor function NewDecoder[S, T].

type Number

type Number string

Number represents a JSON number literal.

func (Number) Float64

func (n Number) Float64() (float64, error)

Float64 returns the number as a float64.

func (Number) Int64

func (n Number) Int64() (int64, error)

Int64 returns the number as an int64.

func (Number) String

func (n Number) String() string

String returns the literal text of the number.