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
- type Decoder
- type Encoder
- type LineDecoder
- type LineEncoder
- type Omiter
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AppendJSON ¶ added in v0.0.10
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶ added in v0.0.11
type Cache struct { Options // contains filtered or unexported fields }
Cache is an Encoder/Decoder cache for specific options
type Decoder ¶
type Decoder interface { Decode(x interface{}, n njson.Node) error // contains filtered or unexported methods }
Decoder is a type specific decoder
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 ¶ added in v0.0.11
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 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