jason: github.com/antonholmquist/jason Index | Files

package jason

import "github.com/antonholmquist/jason"

Jason is designed to be convenient for reading arbitrary JSON while still honoring the strictness of the language. Inspired by other libraries and improved to work well for common use cases. It currently focuses on reading JSON data rather than creating it.

Examples

JSON is a commonly used data transfer format, so usually the data you want to read comes either as bytes or as an io.Reader.

Create an object from bytes:

v, err := jason.NewObjectFromBytes(b)

.. or from a net/http response body:

v, err := jason.NewObjectFromReader(res.body)

Read values

Reading values is done with Get<Type>(keys ...) or the generic Get(keys ...). If the key path is invalid or the type doesn't match, it will return an error and the default value.

name, err := v.GetString("name")
age, err := v.GetNumber("age")
verified, err := v.GetBoolean("verified")
education, err := v.GetObject("education")
friends, err := v.GetObjectArray("friends")

Loop through array

Getting an array is done by Get<Type>Array() or the generic GetValueArray(). It returns an error if the value at that keypath is null (or something else than the type).

friends, err := person.GetObjectArray("friends")
for _, friend := range friends {
	name, err := friend.GetString("name")
	age, err := friend.GetNumber("age")
}

Loop through keys of object

Looping through an object is done by first getting it with `GetObject()` and then range on the Map(). The GetObject() method returns an error if the value at that keypath is null (or something else than an object).

person, err := person.GetObject("person")
for key, value := range person.Map() {
  ...
}

Index

Package Files

jason.go

Variables

var (
    ErrNotNull        = errors.New("is not null")
    ErrNotArray       = errors.New("Not an array")
    ErrNotNumber      = errors.New("not a number")
    ErrNotBool        = errors.New("no bool")
    ErrNotObject      = errors.New("not an object")
    ErrNotObjectArray = errors.New("not an object array")
    ErrNotString      = errors.New("not a string")
)

Error values returned when validation functions fail

type KeyNotFoundError Uses

type KeyNotFoundError struct {
    Key string
}

func (KeyNotFoundError) Error Uses

func (k KeyNotFoundError) Error() string

type Object Uses

type Object struct {
    Value
    // contains filtered or unexported fields
}

Object represents an object JSON object. It inherets from Value but with an additional method to access a map representation of it's content. It's useful when iterating.

func NewObjectFromBytes Uses

func NewObjectFromBytes(b []byte) (*Object, error)

func NewObjectFromReader Uses

func NewObjectFromReader(reader io.Reader) (*Object, error)

func (*Object) GetBoolean Uses

func (v *Object) GetBoolean(keys ...string) (bool, error)

Gets the value at key path and attempts to typecast the value into a bool. Returns error if the value is not a json boolean. Example:

married, err := GetBoolean("person", "married")

func (*Object) GetBooleanArray Uses

func (v *Object) GetBooleanArray(keys ...string) ([]bool, error)

Gets the value at key path and attempts to typecast the value into an array of bools. Returns error if the value is not a json array or if any of the contained objects are not booleans.

func (*Object) GetFloat64 Uses

func (v *Object) GetFloat64(keys ...string) (float64, error)

Gets the value at key path and attempts to typecast the value into a float64. Returns error if the value is not a json number. Example:

n, err := GetNumber("address", "street_number")

func (*Object) GetFloat64Array Uses

func (v *Object) GetFloat64Array(keys ...string) ([]float64, error)

Gets the value at key path and attempts to typecast the value into an array of floats. Returns error if the value is not a json array or if any of the contained objects are not numbers.

func (*Object) GetInt64 Uses

func (v *Object) GetInt64(keys ...string) (int64, error)

Gets the value at key path and attempts to typecast the value into a float64. Returns error if the value is not a json number. Example:

n, err := GetNumber("address", "street_number")

func (*Object) GetInt64Array Uses

func (v *Object) GetInt64Array(keys ...string) ([]int64, error)

Gets the value at key path and attempts to typecast the value into an array of ints. Returns error if the value is not a json array or if any of the contained objects are not numbers.

func (*Object) GetInterface Uses

func (v *Object) GetInterface(keys ...string) (interface{}, error)

Gets the value at key path and attempts to typecast the value into a float64. Returns error if the value is not a json number. Example:

v, err := GetInterface("address", "anything")

func (*Object) GetNull Uses

func (v *Object) GetNull(keys ...string) error

Gets the value at key path and attempts to typecast the value into null. Returns error if the value is not json null. Example:

err := GetNull("address", "street")

func (*Object) GetNullArray Uses

func (v *Object) GetNullArray(keys ...string) (int64, error)

Gets the value at key path and attempts to typecast the value into an array of nulls. Returns length, or an error if the value is not a json array or if any of the contained objects are not nulls.

func (*Object) GetNumber Uses

func (v *Object) GetNumber(keys ...string) (json.Number, error)

Gets the value at key path and attempts to typecast the value into a number. Returns error if the value is not a json number. Example:

n, err := GetNumber("address", "street_number")

func (*Object) GetNumberArray Uses

func (v *Object) GetNumberArray(keys ...string) ([]json.Number, error)

Gets the value at key path and attempts to typecast the value into an array of numbers. Returns error if the value is not a json array or if any of the contained objects are not numbers. Example:

friendAges, err := GetNumberArray("person", "friend_ages")
for i, friendAge := range friendAges {
	... // friendAge will be of type float64 here
}

func (*Object) GetObject Uses

func (v *Object) GetObject(keys ...string) (*Object, error)

Gets the value at key path and attempts to typecast the value into an object. Returns error if the value is not a json object. Example:

object, err := GetObject("person", "address")

func (*Object) GetObjectArray Uses

func (v *Object) GetObjectArray(keys ...string) ([]*Object, error)

Gets the value at key path and attempts to typecast the value into an array of objects. Returns error if the value is not a json array or if any of the contained objects are not objects. Example:

friends, err := GetObjectArray("person", "friends")
for i, friend := range friends {
	... // friend will be of type Object here
}

func (*Object) GetString Uses

func (v *Object) GetString(keys ...string) (string, error)

Gets the value at key path and attempts to typecast the value into a string. Returns error if the value is not a json string. Example:

string, err := GetString("address", "street")

func (*Object) GetStringArray Uses

func (v *Object) GetStringArray(keys ...string) ([]string, error)

Gets the value at key path and attempts to typecast the value into an array of string. Returns error if the value is not a json array or if any of the contained objects are not strings. Gets the value at key path and attempts to typecast the value into an array of objects. Returns error if the value is not a json array or if any of the contained objects are not objects. Example:

friendNames, err := GetStringArray("person", "friend_names")
for i, friendName := range friendNames {
	... // friendName will be of type string here
}

func (*Object) GetValue Uses

func (v *Object) GetValue(keys ...string) (*Value, error)

Gets the value at key path. Returns error if the value does not exist. Consider using the more specific Get<Type>(..) methods instead. Example:

value, err := GetValue("address", "street")

func (*Object) GetValueArray Uses

func (v *Object) GetValueArray(keys ...string) ([]*Value, error)

Gets the value at key path and attempts to typecast the value into an array. Returns error if the value is not a json array. Consider using the more specific Get<Type>Array() since it may reduce later type casts. Example:

friends, err := GetValueArray("person", "friends")
for i, friend := range friends {
	... // friend will be of type Value here
}

func (*Object) Map Uses

func (v *Object) Map() map[string]*Value

Returns the golang map. Needed when iterating through the values of the object.

func (*Object) MarshalJSON Uses

func (v *Object) MarshalJSON() ([]byte, error)

Marshal into bytes.

func (*Object) String Uses

func (v *Object) String() string

Returns the value a json formatted string. Note: The method named String() is used by golang's log method for logging. Example:

type Value Uses

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

Value represents an arbitrary JSON value. It may contain a bool, number, string, object, array or null.

func NewValueFromBytes Uses

func NewValueFromBytes(b []byte) (*Value, error)

Creates a new value from bytes. Returns an error if the bytes are not valid json.

func NewValueFromReader Uses

func NewValueFromReader(reader io.Reader) (*Value, error)

Creates a new value from an io.reader. Returns an error if the reader does not contain valid json. Useful for parsing the body of a net/http response. Example: NewFromReader(res.Body)

func (*Value) Array Uses

func (v *Value) Array() ([]*Value, error)

Attempts to typecast the current value into an array. Returns error if the current value is not a json array. Example:

friendsArray, err := friendsValue.Array()

func (*Value) Boolean Uses

func (v *Value) Boolean() (bool, error)

Attempts to typecast the current value into a bool. Returns error if the current value is not a json boolean. Example:

marriedBool, err := marriedValue.Boolean()

func (*Value) Float64 Uses

func (v *Value) Float64() (float64, error)

Attempts to typecast the current value into a float64. Returns error if the current value is not a json number. Example:

percentage, err := v.Float64()

func (*Value) Int64 Uses

func (v *Value) Int64() (int64, error)

Attempts to typecast the current value into a int64. Returns error if the current value is not a json number. Example:

id, err := v.Int64()

func (*Value) Interface Uses

func (v *Value) Interface() interface{}

Get the interyling data as interface

func (*Value) Marshal Uses

func (v *Value) Marshal() ([]byte, error)

Marshal into bytes.

func (*Value) MarshalJSON Uses

func (v *Value) MarshalJSON() ([]byte, error)

Marshal into bytes

func (*Value) Null Uses

func (v *Value) Null() error

Returns an error if the value is not actually null

func (*Value) Number Uses

func (v *Value) Number() (json.Number, error)

Attempts to typecast the current value into a number. Returns error if the current value is not a json number. Example:

ageNumber, err := ageValue.Number()

func (*Value) Object Uses

func (v *Value) Object() (*Object, error)

Attempts to typecast the current value into an object. Returns error if the current value is not a json object. Example:

friendObject, err := friendValue.Object()

func (*Value) ObjectArray Uses

func (v *Value) ObjectArray() ([]*Object, error)

Attempts to typecast the current value into an object arrau. Returns error if the current value is not an array of json objects Example:

friendObjects, err := friendValues.ObjectArray()

func (*Value) String Uses

func (v *Value) String() (string, error)

Attempts to typecast the current value into a string. Returns error if the current value is not a json string Example:

nameObject, err := nameValue.String()

Package jason imports 5 packages (graph) and is imported by 60 packages. Updated 2018-06-05. Refresh now. Tools for package owners.