unjson

Documentation

Overview

Package unjson uses reflection to marshal/unmarshal JSON from `njson.Node` input

It is combatible with the default `encoding/json` package but the API is different so it's *not* a 'drop-in' replacement.

## Decoding

Values are decoded from JSON by `Decoder` instances. `Decoder` iterates over an `njson.Node` instance to decode a value instead of reading directly from an `io.Reader` as in `encoding/json`. This decouples decoding and parsing of a JSON document. A parsed JSON document can be thus decoded multiple times to produce different values or using different decoding options.

To decode streams of JSON values from an `io.Reader` use `LineDecoder`.

To decode a value from JSON you need to create a `Decoder` for it's type. A package-wide decoder registry using the default `json` tag is used to decode values with the `Unmarshal` method.

## Encoding

Values are encoded to JSON by `Encoder` instances. `Encoder` instances provide an API that appends to a byte slice instead of writing to an `io.Writer` as in `encoding/json`. To encode streams of JSON values to an `io.Writer` use `LineEncoder`.

Index

• func AppendJSON(out []byte, x interface{}) ([]byte, error)
• func Marshal(x interface{}) ([]byte, error)
• func Unmarshal(data []byte, x interface{}) error
• func UnmarshalFromNode(n njson.Node, x interface{}) error
• func UnmarshalFromString(s string, x interface{}) (err error)
• type Cache
  • func (c *Cache) Decoder(typ reflect.Type) (dec Decoder, err error)
  • func (c *Cache) Encoder(typ reflect.Type) (enc Encoder, err error)
• type Decoder
  • func NewTypeDecoder(typ reflect.Type, tag string) (Decoder, error)
• type Encoder
  • func NewTypeEncoder(typ reflect.Type, options Options) (Encoder, error)
• type LineDecoder
  • func NewLineDecoder(r io.Reader) *LineDecoder
  • func (d *LineDecoder) Decode(x interface{}) (err error)
• type LineEncoder
  • func NewLineEncoder(w io.Writer) *LineEncoder
  • func (e *LineEncoder) Encode(x interface{}) (err error)
• type Omiter
• type Options
  • func DefaultOptions() Options

Functions

func AppendJSON

func AppendJSON(out []byte, x interface{}) ([]byte, error)

AppendJSON appends the JSON encoding of a value to a buffer

It uses a package-wide cache of `Encoder` instances using the default options. In order to use custom options for an `Encoder` and avoid lock congestion on the registry, create a local `Encoder` instance with `NewTypeEncoder`

func Marshal

func Marshal(x interface{}) ([]byte, error)

Marshal is a drop-in replacement for json.Marshal.

It delegates to `AppendJSON`, allocating a new buffer. To avoid allocations use `AppendJSON` and provide a buffer yourself.

func Unmarshal

func Unmarshal(data []byte, x interface{}) error

Unmarshal is a drop-in replacement for json.Unmarshal.

It delegates to `UnmarshalFromJSON` by allocating a new string. To avoid allocations use `UnmarshalFromString` or `UnmarshalFromNode`

func UnmarshalFromNode

func UnmarshalFromNode(n njson.Node, x interface{}) error

UnmarshalFromNode unmarshals from an njson.Node

It uses a package-wide cache of `Decoder` instances using the default options. In order to use custom options for a `Decoder` and avoid lock congestion on the registry, create a local `Decoder` instance with `NewTypeDecoder`

func UnmarshalFromString

func UnmarshalFromString(s string, x interface{}) (err error)

UnmarshalFromString unmarshals from a JSON string

It borrows a blank `njson.Document` from `njson.Blank` to parse the JSON string and a `Decoder` with the default options from package-wide cache of `Dec`Decoder` instances.

Types

type Cache

type Cache struct {
	Options
	// contains filtered or unexported fields
}

Cache is an Encoder/Decoder cache for specific options

func (*Cache) Decoder

func (c *Cache) Decoder(typ reflect.Type) (dec Decoder, err error)

Decoder returns a Decoder for the type using the tag key from cache.Options

func (*Cache) Encoder

func (c *Cache) Encoder(typ reflect.Type) (enc Encoder, err error)

Encoder returns an Encoder for the type using cache.Options

type Decoder

type Decoder interface {
	Decode(x interface{}, n njson.Node) error
	// contains filtered or unexported methods
}

Decoder is a type specific decoder

func NewTypeDecoder

func NewTypeDecoder(typ reflect.Type, tag string) (Decoder, error)

NewTypeDecoder creates a new decoder for a type.

type Encoder

type Encoder interface {
	Encode(out []byte, x interface{}) ([]byte, error)
	// contains filtered or unexported methods
}

Encoder encodes a `reflect.Value` to JSON

Each encoder can handle only a specific `reflect.Type`. To create a new `Encoder` for a type use `NewTypeEncoder`.

func NewTypeEncoder

func NewTypeEncoder(typ reflect.Type, options Options) (Encoder, error)

NewTypeEncoder creates a new Encoder for `typ` using `options`

Encoding can be customized through `options` argument and by using struct tag options. The default tag is `json` and can be customized by `options.Tag`. The following struct tag options are supported:

• `omitempty` to omit empty values. If the value provides an `Omit() bool` method it is used to determine if a value is to be omitted. Otherwise the default rules from `json/encoding` are used. The name of the method can be customized by the `options.OmitMethod`. To omit empty values by default use `options.OmitEmpty`.
• `8bit` mark a string value as `8bit` to avoid costly JSON unescaping
• `html` mark a string value as HTML text that should be escaped

type LineDecoder

type LineDecoder struct {
	Decoder // Use a specific type decoder
	// contains filtered or unexported fields
}

LineDecoder decodes from a newline delimited JSON stream. (http://ndjson.org/)

func NewLineDecoder

func NewLineDecoder(r io.Reader) *LineDecoder

NewLineDecoder creates a new LineDecoder

func (*LineDecoder) Decode

func (d *LineDecoder) Decode(x interface{}) (err error)

Decode decodes the next JSON line in the stream to x

type LineEncoder

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

LineEncoder encodes to a newline delimited JSON stream. (http://ndjson.org/)

func NewLineEncoder

func NewLineEncoder(w io.Writer) *LineEncoder

NewLineEncoder creates a new LineEncoder

func (*LineEncoder) Encode

func (e *LineEncoder) Encode(x interface{}) (err error)

Encode encodes a value to a new JSON line on the stream.

type Omiter

type Omiter interface {
	Omit() bool
}

Omiter implements custom omitempty logic

type Options

type Options struct {
	Tag        string // Tag name to use for hints
	OmitEmpty  bool   // Force omitempty on all fields
	OmitMethod string // Method name for checking if a value is empty defaults to 'Omit'
	AllowNaN   bool   // Allow NaN values for numbers
	AllowInf   bool   // Allow ±Inf values for numbers
}

Options holds options for an Encoder/Decoder

func DefaultOptions

func DefaultOptions() Options

DefaultOptions returns the default options for an Encoder/Decoder