manbeardo / jason

Easy-to-use JSON Library for Go

Jason - JSON Library for Go

Jason is an easy-to-use JSON library for Go. It's designed to be convenient for reading arbitrary JSON and to be forgiving to inconsistent content. 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.

Note: The API will be subject to change during 2014 if there are very good reasons to do so. On January 1st 2015 it will be frozen.

Data types

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

• bool, for JSON booleans
• float64, for JSON numbers
• string, for JSON strings
• []*Jason, for JSON arrays
• map[string]*Jason, for JSON objects
• nil for JSON null

Install

go get github.com/antonholmquist/jason

Import

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

Examples

Create from string

Create a instance from a string. Returns an error if the string couldn't be parsed.

root, err := jason.NewFromString(s)

Create from a reader (like a http response)

Create a instance from a net/http response. Returns an error if the string couldn't be parsed.

root, err := jason.NewFromReader(res.Body)

Read values

Reading values is easy. If the key is invalid, it will return the default value.

root.Get("name").String()
root.Get("age").Number()
root.Get("verified").Boolean()
root.Get("education").Object()
root.Get("friends").Array()

Read nested values

Reading nested values is easy. If the path is invalid, it will return the default value, for instance the empty string.

root.Get("person", "name").String()
root.Get("person", "age").Number()
root.Get("person", "verified").Boolean()
root.Get("person", "education").Object()
root.Get("person", "friends").Array()

Check if values exists

To check if a value exist, use Exists() or Has(). The two examples below are identical and have different use cases.

root.Get("person", "name").Exists()

or the shorter form:

root.Has("person", "name")

Validate values

To check if a value at the keypath really is what you think it is, use the Is()-methods.

root.Get("name").IsString()
root.Get("age").IsNumber()
root.Get("verified").IsBoolean()
root.Get("education").IsObject()
root.Get("friends").IsArray()
root.Get("friends").IsNull()

Loop through array

Looping through an array is easy and will never return an exeption. Array() returns an empty slice if the value at that keypath is null (or something else than an array).

for _, friend := range person.Get("friends").Array() {
  name := friend.Get("name").String()
  age := friend.Get("age").Number()
}

Loop through object

Looping through an object is easy and will never return an exeption. Object() returns an empty map if the value at that keypath is null (or something else than an object).

for key, value := range person.Get("person").Object() {
  ...
}

Sample App

Example project demonstrating how to parse a string.

package main

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

func main() {

  exampleJSON := `{
    "name": "Walter White",

    "age": 51,
    "children": [
      "junior",
      "holly"
    ],
    "other": {
      "occupation": "chemist",
      "years": 23
    }
  }`

  j, _ := jason.NewFromString(exampleJSON)

  log.Println("name:", j.Get("name").String())
  log.Println("age:", j.Get("age").Number())

  log.Println("occupation:", j.Get("other", "occupation").String())
  log.Println("years:", j.Get("other", "years").Number())

  for i, child := range j.Get("children").Array() {
    log.Printf("child %d: %s", i, child.String())
  }

  for key, value := range j.Get("other").Object() {
    log.Println("key: ", key)

    if value.IsString() {
      log.Println("string value: ", value.String())
    } else if value.IsNumber() {
      log.Println("number value: ", value.Number())
    }
  }

}

Documentation

Documentation can be found a godoc:

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

Test

To run the project tests:

go test