jason

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 3, 2015 License: MIT Imports: 4 Imported by: 226

README

logo

Jason is an easy-to-use JSON library for Go.

Build Status Godoc license

About

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. API Documentation can be found on godoc.org.

Install

go get github.com/antonholmquist/jason

Import

import (
  "github.com/antonholmquist/jason"
)

Data types

The following golang values are used to represent JSON data types. It is consistent with how encoding/json uses primitive types.

  • bool, for JSON booleans
  • json.Number/float64/int64, for JSON numbers
  • string, for JSON strings
  • []*Value, for JSON arrays
  • map[string]*Value, for JSON objects
  • nil for JSON null

Examples

Create from bytes

Create object from bytes. Returns an error if the bytes are not valid JSON.

v, err := jason.NewObjectFromBytes(b)

If the root object is not an array, use this method instead. It can then be cased to the expected type with one of the As-Methods.

v, err := jason.NewValueFromBytes(b)
Create from a reader (like a http response)

Create value from a io.reader. Returns an error if the string couldn't be parsed.

v, err := jason.NewObjectFromReader(res.Body)
Read values

Reading values is easy. If the key path is invalid or type doesn't match, it will return an error and the default value.

name, err := v.GetString("name")
age, err := v.GetInt64("age")
verified, err := v.GetBoolean("verified")
education, err := v.GetObject("education")
friends, err := v.GetObjectArray("friends")
interests, err := v.GetStringArray("interests")
Read nested values

Reading nested values is easy. If the path is invalid or type doesn't match, it will return the default value and an error.

name, err := v.GetString("person", "name")
age, err := v.GetInt64("person", "age")
verified, err := v.GetBoolean("person", "verified")
education, err := v.GetObject("person", "education")
friends, err := v.GetObjectArray("person", "friends")
Loop through array

Looping through an array is done with GetValueArray() or GetObjectArray(). It returns an error if the value at that keypath is null (or something else than an array).

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

Looping through an object is easy. GetObject() 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() {
  ...
}

Sample App

Example project:

package main

import (
  "github.com/antonholmquist/jason"
  "log"
)

func main() {

  exampleJSON := `{
    "name": "Walter White",
    "age": 51,
    "children": [
      "junior",
      "holly"
    ],
    "other": {
      "occupation": "chemist",
      "years": 23
    }
  }`

  v, _ := jason.NewObjectFromBytes([]byte(exampleJSON))

  name, _ := v.GetString("name")
  age, _ := v.GetNumber("age")
  occupation, _ := v.GetString("other", "occupation")
  years, _ := v.GetNumber("other", "years")

  log.Println("age:", age)
  log.Println("name:", name)
  log.Println("occupation:", occupation)
  log.Println("years:", years)

  children, _ := v.GetStringArray("children")
  for i, child := range children {
    log.Printf("child %d: %s", i, child)
  }

  others, _ := v.GetObject("other")

  for _, value := range others.Map() {

    s, sErr := value.String()
    n, nErr := value.Number()

    if sErr == nil {
      log.Println("string value: ", s)
    } else if nErr == nil {
      log.Println("number value: ", n)
    }
  }
}

Documentation

Documentation can be found a godoc:

https://godoc.org/github.com/antonholmquist/jason

Test

To run the project tests:

go test

Compatibility

Go 1.1 and up.

Where does the name come from?

I remebered it from an email one of our projects managers sent a couple of years ago.

"Don't worry. We can handle both XML and Jason"

Author

Anton Holmquist, http://twitter.com/antonholmquist

Documentation

Overview

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Object 

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 

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

func NewObjectFromReader 

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

func (*Object) GetBoolean 

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 

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 

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 

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 

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 

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) GetNull 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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 

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

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

func (*Object) String 

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 

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 

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

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

func NewValueFromReader 

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 

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 

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 

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 

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) Marshal 

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

Marshal into bytes.

func (*Value) Null 

func (v *Value) Null() error

Returns an error if the value is not actually null

func (*Value) Number 

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 

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) String 

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()

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.