lzjson is a JSON decoding library aims to make you lazy.
Golang default JSON library requires to provide certain data structure (e.g. struct) to decode data to. It is hard to write type-inspecific code to examine JSON data structure. It is also hard to determine the abcence or prescence of data field.
This library provide flexible interface for writing generic JSON parsing code.
Key features:
-
zero knowledge parsing: can read and examine JSON structure without pre-defining the data structure before hand.
-
lazy parsing: allow you to parse only a specific node into golang data structure.
-
compatibility: totally compatible with the default json library
Decode is straight forward with any io.Reader implementation (e.g. http.Request.Body, http.Response.Body, strings.Reader).
For example, in a http.HandlerFunc:
import (
"net/http"
"github.com/go-restit/lzjson"
)
func handler(w http.ResponseWriter, r *http.Request) {
json := lzjson.Decode(r.Body)
...
...
}Or as a client:
func main() {
resp, _ := http.Get("https://foobarapi.com/things")
json := lzjson.Decode(resp.Body)
...
...
}You may retrieve the JSON value of any node.
// get "foo" in the json
foo := json.Get("foo")
// get the 10th item in foo
// (like ordinary array, 0 is the first)
item10 := foo.GetN(9)body := strings.NewReader(`
{
"string": "hello world",
"number": 3.14,
"bool": true,
"array": [1, 2, 3, 5],
"object": {"foo": "bar"}
}
`)
json := lzjson.Decode(body)
fmt.Printf("%s", json.Get("string").Type()) // output "TypeString"
fmt.Printf("%s", json.Get("number").Type()) // output "TypeNumber"
fmt.Printf("%s", json.Get("bool").Type()) // output "TypeBool"
fmt.Printf("%s", json.Get("array").Type()) // output "TypeArray"
fmt.Printf("%s", json.Get("object").Type()) // output "TypeObject"For basic value types (string, int, bool), you may evaluate them directly.
code := json.Get("code").Int()
message := json.Get("message").String()You may decode only a child-node in a JSON structure.
type Item struct {
Name string `json:"name"`
Weight int `json:"weight"`
}
var item Item
item10 := foo.GetN(9)
item10.Unmarshal(&item)
log.Printf("item: name=%s, weight=%d", item.Name, item.Weight)You may chain Get and GetN to get somthing deep within.
helloIn10thBar := lzjson.Decode(r.Body).Get("foo").GetN(9).Get("hello")Looping is straight forward with Len and GetKeys.
var item Item
for i := 0; i<foo.Len(); i++ {
foo.Get(i).Unmarshal(&item)
log.Printf("i=%d, value=%#v", i, item)
}
for _, key := range json.GetKeys() {
log.Printf("key=%#v, value=%#v", key, json.Get(key).String())
}With chaining, it is important where exactly did any parse error happen.
body := strings.NewReader(`
{
"hello": [
{
"name": "world 1"
},
{
"name": "world 2"
},
{
"name": "world 3"
},
],
}
`)
json := lzjson.Decode(body)
inner := json.Get("hello").GetN(2).Get("foo").Get("bar").GetN(0)
if err := inner.ParseError(); err != nil {
fmt.Println(err.Error()) // output: "hello[2].foo: undefined"
}Put everything above together, we can do something like this:
package main
import (
"log"
"net/http"
"github.com/go-restit/lzjson"
)
type Thing struct {
ID string `json:"id"`
Name string `json:"name"`
Found time.Time `json:"found"`
FromEarth bool `json:"from_earth"`
}
/**
* assume the API endpoints returns data:
* {
* "code": 200,
* "data": [
* ...
* ]
* }
*
* or error:
* {
* "code": 500,
* "message": "some error message"
* }
*
*/
func main() {
resp, err := http.Get("https://foobarapi.com/things")
if err != nil {
panic(err)
}
// decode the json as usual, if no error
json := lzjson.Decode(resp.Body)
if code := json.Get("code").Int(); code != 200 {
message := json.Get("message").String()
log.Fatalf("error %d: ", code, message)
}
// get the things array
things := json.Get("data")
// loop through the array
for i := 0; i<things.Len(); i++ {
thing := things.GetN(i)
if err := thing.ParseError(); err != nil {
log.Fatal(err.Error())
}
// if the thing is not from earth, unmarshal
// as a struct then read the details
if !thing.Get("from_earth").Bool() {
var theThing Thing
thing.Unmarshal(&theThing)
log.Printf("Alien found! %#v", theThing)
}
}
}For more details, please read the documentation
Your are welcome to contribute to this library.
To report bug, please use the issue tracker.
To fix an existing bug or implement a new feature, please:
- Check the issue tracker and pull requests for existing discussion.
- If not, please open a new issue for discussion.
- Write tests.
- Open a pull request referencing the issue.
- Have fun :-)
This software is licenced with the [MIT Licence] licence. You can obtain a copy of the licence in this repository.