README

jsonq

Build Status Godoc license

Simplify your golang json usage by extracting fields or items from arrays and objects with a simple, hierarchical query. API Documentation on godoc.org.

This package is meant to make working with complex feeds a bit more easy. If you have simple feeds you want to model with struct types, check out jflect, which will create struct definitions given a json document.

installing

go get github.com/jmoiron/jsonq

usage

Given some json data like:

{
	"foo": 1,
	"bar": 2,
	"test": "Hello, world!",
	"baz": 123.1,
	"array": [
		{"foo": 1},
		{"bar": 2},
		{"baz": 3}
	],
	"subobj": {
		"foo": 1,
		"subarray": [1,2,3],
		"subsubobj": {
			"bar": 2,
			"baz": 3,
			"array": ["hello", "world"]
		}
	},
	"bool": true
}

Decode it into a map[string]interface{}:

import (
	"strings"
	"encoding/json"
	"github.com/jmoiron/jsonq"
)

data := map[string]interface{}{}
dec := json.NewDecoder(strings.NewReader(jsonstring))
dec.Decode(&data)
jq := jsonq.NewQuery(data)

From here, you can query along different keys and indexes:

// data["foo"] -> 1
jq.Int("foo")

// data["subobj"]["subarray"][1] -> 2
jq.Int("subobj", "subarray", "1")

// data["subobj"]["subarray"]["array"][0] -> "hello"
jq.String("subobj", "subsubobj", "array", "0")

// data["subobj"] -> map[string]interface{}{"subobj": ...}
obj, err := jq.Object("subobj")

Missing keys, out of bounds indexes, and type failures will return errors. For simplicity, integer keys (ie, {"0": "zero"}) are inaccessible by jsonq as integer strings are assumed to be array indexes.

The Int and Float methods will attempt to parse numbers from string values to ease the use of many real world feeds which deliver numbers as strings.

Suggestions/comments please tweet @jmoiron

Expand ▾ Collapse ▴

Documentation

Overview

    Package jsonq simplify your json usage with a simple hierarchical query.

    Given some json data like:

    {
    	"foo": 1,
    	"bar": 2,
    	"test": "Hello, world!",
    	"baz": 123.1,
    	"array": [
    		{"foo": 1},
    		{"bar": 2},
    		{"baz": 3}
    	],
    	"subobj": {
    		"foo": 1,
    		"subarray": [1,2,3],
    		"subsubobj": {
    			"bar": 2,
    			"baz": 3,
    			"array": ["hello", "world"]
    		}
    	},
    	"bool": true
    }
    

    Decode it into a map[string]interrface{}:

    import (
    	"strings"
    	"encoding/json"
    	"github.com/jmoiron/jsonq"
    )
    
    data := map[string]interface{}{}
    dec := json.NewDecoder(strings.NewReader(jsonstring))
    dec.Decode(&data)
    jq := jsonq.NewQuery(data)
    

    From here, you can query along different keys and indexes:

    // data["foo"] -> 1
    jq.Int("foo")
    
    // data["subobj"]["subarray"][1] -> 2
    jq.Int("subobj", "subarray", "1")
    
    // data["subobj"]["subarray"]["array"][0] -> "hello"
    jq.String("subobj", "subsubobj", "array", "0")
    
    // data["subobj"] -> map[string]interface{}{"subobj": ...}
    obj, err := jq.Object("subobj")
    
    Notes:
    

    Missing keys, out of bounds indexes, and type failures will return errors. For simplicity, integer keys (ie, {"0": "zero"}) are inaccessible by `jsonq` as integer strings are assumed to be array indexes.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    Types

    type JsonQuery

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

      JsonQuery is an object that enables querying of a Go map with a simple positional query language.

      func NewQuery

      func NewQuery(data interface{}) *JsonQuery

        NewQuery creates a new JsonQuery obj from an interface{}.

        func (*JsonQuery) Array

        func (j *JsonQuery) Array(s ...string) ([]interface{}, error)

          Array extracts a []interface{} from the JsonQuery

          func (*JsonQuery) ArrayOfArrays

          func (j *JsonQuery) ArrayOfArrays(s ...string) ([][]interface{}, error)

            ArrayOfArrays extracts an array of []interface{} (arrays) from some json

            func (*JsonQuery) ArrayOfBools

            func (j *JsonQuery) ArrayOfBools(s ...string) ([]bool, error)

              ArrayOfBools extracts an array of bools from some json

              func (*JsonQuery) ArrayOfFloats

              func (j *JsonQuery) ArrayOfFloats(s ...string) ([]float64, error)

                ArrayOfFloats extracts an array of float64s from some json

                func (*JsonQuery) ArrayOfInts

                func (j *JsonQuery) ArrayOfInts(s ...string) ([]int, error)

                  ArrayOfInts extracts an array of ints from some json

                  func (*JsonQuery) ArrayOfObjects

                  func (j *JsonQuery) ArrayOfObjects(s ...string) ([]map[string]interface{}, error)

                    ArrayOfObjects extracts an array of map[string]interface{} (objects) from some json

                    func (*JsonQuery) ArrayOfStrings

                    func (j *JsonQuery) ArrayOfStrings(s ...string) ([]string, error)

                      ArrayOfStrings extracts an array of strings from some json

                      func (*JsonQuery) Bool

                      func (j *JsonQuery) Bool(s ...string) (bool, error)

                        Bool extracts a bool the JsonQuery

                        func (*JsonQuery) Float

                        func (j *JsonQuery) Float(s ...string) (float64, error)

                          Float extracts a float from the JsonQuery

                          func (*JsonQuery) Int

                          func (j *JsonQuery) Int(s ...string) (int, error)

                            Int extracts an int from the JsonQuery

                            func (*JsonQuery) Interface

                            func (j *JsonQuery) Interface(s ...string) (interface{}, error)

                              Interface extracts an interface{} from the JsonQuery

                              func (*JsonQuery) Matrix2D

                              func (j *JsonQuery) Matrix2D(s ...string) ([][]interface{}, error)

                                Matrix2D is an alias for ArrayOfArrays

                                func (*JsonQuery) Object

                                func (j *JsonQuery) Object(s ...string) (map[string]interface{}, error)

                                  Object extracts a json object from the JsonQuery

                                  func (*JsonQuery) String

                                  func (j *JsonQuery) String(s ...string) (string, error)

                                    String extracts a string from the JsonQuery

                                    Source Files