j

README

j

J is a JSON library for Go (golang) with a focus on consistency and extensibility.

The project's aim is to provide a set of small api-compatible libraries that provides a comprehensive experience for working with JSON document and streams, from syntax checking to schema validation and encoding.

Please note that the project is in it's infancy stage and being rapidly developed, so some APIs may change until a point where all the required components are worked out and in a stable state. This notice will be removed once the API is considered stable.

Why?

Credits

• The scanner design is heavily influenced by Rob Pike's Lexical Scanning in Go talk and borrows some implementation details from the Go's standard library text and json scanner implementations.

License

MIT, see LICENSE.md.

Documentation

Index

• Variables
• func Encode(value Value) ([]byte, error)
• func Match(a Value, b Value) bool
• func Valid(src []byte) error
• type Iterator
• type Member
  • func NewMember(tag string, name string, value Value) Member
• type ParseError
  • func (pe ParseError) Error() string
• type Position
• type String
• type SyntaxError
  • func (se SyntaxError) Error() string
• type Type
  • func (i Type) String() string
• type Value
  • func Decode(input []byte) (Value, error)
  • func NewArray(values []Value) Value
  • func NewBool(value bool) Value
  • func NewNull() Value
  • func NewNumber(raw []byte) Value
  • func NewNumberFloat64(v float64) Value
  • func NewNumberInt64(v int64) Value
  • func NewNumberUint64(v uint64) Value
  • func NewObject(members []Member) Value
  • func NewString(text string) Value

Variables

var (
	// ErrInvalidType means your Value is of InvalidType.
	ErrInvalidType = errors.New("Invalid Value")
	// ErrNotDocument means you have provided a non-array or non-object type where
	// a valid JSON Document type is expected.
	ErrNotDocument = errors.New("Not a JSON Document. Expected Array or Object Type")
)

Functions

func Encode

func Encode(value Value) ([]byte, error)

Encode creates a json document the provided j.Value

func Match

func Match(a Value, b Value) bool

Match deep compares the provided values.

func Valid

func Valid(src []byte) error

Valid check if the provide data is correct json document.

Types

type Iterator

type Iterator interface {
	// Next returns the next value if any or nil.
	// More indicates whatever there is any more
	// _possible_ values, so you must always check
	// to make sure the item is not nil.
	// Calling Next after the last item MUST return
	// `nil, false`.
	Next() (item Value, more bool)
	// Len returns -1 for indefinite streams or an advisory
	// number indicating the the number of values it holds.
	// The iterator _MAY_ return more or less items than what
	// is advised but _MUST_ always return a finite
	// number of items when Len returns 1 or more.
	// 0 indicates exactly 0 items.
	Len() int
}

Iterator is the common interface for JSON iterators.

type Member

type Member interface {
	// Tag is the struct member tag.
	Tag() string

	Name() *string
	Value() Value
}

Member is a JSON object Member.

func NewMember

func NewMember(tag string, name string, value Value) Member

NewMember creates a new mutable object

type ParseError

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

ParseError holds an error and offset, the error maybe a a SyntaxError

func (ParseError) Error

func (pe ParseError) Error() string

type Position

type Position struct {
	Line   int
	Column int
	Offset int
}

Position is a location in the json document, used for errors.

type String

type String *string

The String type is simply a string. It merely exists to keep the fmt package from calling it and resulting in panics.

type SyntaxError

type SyntaxError struct {
	Message  string
	Position Position
}

SyntaxError is JSON syntax error with a message and int's position.

func (SyntaxError) Error

func (se SyntaxError) Error() string

type Type

type Type uint

A Type describes the type of a value as per JSON spec.

const (
	InvalidType Type = iota
	ObjectType
	ArrayType
	BoolType
	NumberType
	StringType
	NullType
)

Type of Objects as per the JSON spec.

func (Type) String

func (i Type) String() string

type Value

type Value interface {
	Type() Type

	// Object applies to Object type.
	Member(string) Value
	Members() []Member

	// Array applies to Array type.
	Values() []Value

	// Bool applies to Bool type.
	Bool() bool

	// Number applies to Number type.
	Float64() (float64, error)
	Int64() (int64, error)
	Uint64() (uint64, error)
	Raw() []byte

	// String applies to string type.
	String() String
}

Value is the json value. The Methods should be only called on specified type documented. Null type accepts no methods.

func Decode

func Decode(input []byte) (Value, error)

Decode loads your input int a Value object.

func NewArray

func NewArray(values []Value) Value

NewArray creates a new mutable array value

func NewBool

func NewBool(value bool) Value

NewBool creates a new mutable object

func NewNull

func NewNull() Value

NewNull creates a new null

func NewNumber

func NewNumber(raw []byte) Value

NewNumber creates a number type from provided raw value. It is the callers responsiblity to make sure it is correctly encoded JSON numbers.

func NewNumberFloat64

func NewNumberFloat64(v float64) Value

NewNumberFloat64 creates a number from the provided value.

func NewNumberInt64

func NewNumberInt64(v int64) Value

NewNumberInt64 creates a number from the provided value.

func NewNumberUint64

func NewNumberUint64(v uint64) Value

NewNumberUint64 creates a number from the provided value.

func NewObject

func NewObject(members []Member) Value

NewObject creates a new mutable object

func NewString

func NewString(text string) Value

NewString creates a new mutable String