sjson

Documentation

Overview

Package sjson implements a portable strongly-typed json-like codec.

The serialization format is json-like in that the output is always valid JSON but it differs from JSON in a few ways. It is somewhat readable but it is not meant for manual editing. It is meant to be relatively easy to create serializers that work in any language without needing intermediate DSLs to specify the layout.

The source of truth of the types is assumed to be Golang and all type names referred to in code effectively uses golang conventions.

The serialization always includes top-level type information via:

{"typeName": <value>}

For example, a simple int32 would get serialized to:

{"int32": 42}

The <value> part matches JSON for integer and string types. Float32 and Float64 are serialized as strings using Golang's `g` format specifier.

Pointers are serialized to their underlying value (or `null` if they are nil):

{"*int32": null} or {"*int32": 42}

Slices are styled similar to JSON:

{"[]int32": null} or {"[]int32": [42]}

Maps do not use the JSON-notation since it does not adequately capture the type of the key for non-string keys. Instead, maps are represented as a sequence with keys and values alternating:

{"map[string]string": ["hello", "world", "goodbye", "cruel sky"]}
// map[string]string{"hello": "world", "goodbye": "cruel sky"}

Structs *could* use the JSON approach but since the type information is available, they instead simply encode the fields in sequence:

// type myStruct { Field1 string }
{"myStruct": ["hello"]}

Structs only look at exported fields, though they do include embedded fields.

Interfaces are encoded with the underlying type:

// type myStruct { Field1 Stringer }
{"myStruct": [{"string": "hello"}]}

Note that interfaces can occur in slices, map keys or values. In all cases, the associated type is encoded.

All named types should be registered via Codec.Register. This is needed for properly decoding types

Index

• Variables
• type Codec
  • func (c *Codec) Register(v interface{})
• type Decoder
  • func (d Decoder) Decode(value interface{}, r io.Reader) (err error)
• type Encoder
  • func (e Encoder) Encode(value interface{}, w io.Writer) error

Variables

var Std = &Codec{}

Std is a global encoder/decoder

Types

type Codec

type Codec struct {
	Encoder
	Decoder
}

Codec exposes both the encoder and decoder

func (*Codec) Register

func (c *Codec) Register(v interface{})

Register registers a value and its associated type

type Decoder

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

Decoder decodes any value

func (Decoder) Decode

func (d Decoder) Decode(value interface{}, r io.Reader) (err error)

Decode implements ops/nw/Codec Decode method

type Encoder

type Encoder struct {
}

Encoder encodes any value

func (Encoder) Encode

func (e Encoder) Encode(value interface{}, w io.Writer) error

Encode implements ops/nw/Codec Encode method