jsonq

README

jsonq

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/rocksolidlabs/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")

Also you can query using a path specification as show in the examples below:

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

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

Finally, As functions have been included so that if you are sure the call will succeed you can inline the values. If these calls encounter an error they will panic:

// data["subobj"]["subarray"][1] -> 2
fmt.Printf("%d\n", jq.AsInt("subobj", "subarray", "1"))
fmt.Printf("%d\n", jq.AsInt("subobj.subarray[1]"))

// data["subobj"]["subarray"]["array"][0] -> "hello"
fmt.Printf("%s\n", jq.AsString("subobj", "subsubobj", "array", "0"))
fmt.Printf("%s\n", jq.AsString("subobj.subsubobj.array[0]"))

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

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

Also you can query using a *path* specification as show in the examples below:

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

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

Finally, As functions have been included so that if you are *sure* the call will succeed you can inline the values. If these calls encounter an error they will panic:

```go
// data["subobj"]["subarray"][1] -> 2
fmt.Printf("%d\n", jq.AsInt("subobj", "subarray", "1"))
fmt.Printf("%d\n", jq.AsInt("subobj.subarray[1]"))

// data["subobj"]["subarray"]["array"][0] -> "hello"
fmt.Printf("%s\n", jq.AsString("subobj", "subsubobj", "array", "0"))
fmt.Printf("%s\n", jq.AsString("subobj.subsubobj.array[0]"))
```

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

• type JsonQuery
  • func NewQuery(data interface{}) *JsonQuery
  • func (j *JsonQuery) Array(s ...string) ([]interface{}, error)
  • func (j *JsonQuery) ArrayOfArrays(s ...string) ([][]interface{}, error)
  • func (j *JsonQuery) ArrayOfBools(s ...string) ([]bool, error)
  • func (j *JsonQuery) ArrayOfFloats(s ...string) ([]float64, error)
  • func (j *JsonQuery) ArrayOfInts(s ...string) ([]int, error)
  • func (j *JsonQuery) ArrayOfObjects(s ...string) ([]map[string]interface{}, error)
  • func (j *JsonQuery) ArrayOfStrings(s ...string) ([]string, error)
  • func (j *JsonQuery) AsArray(s ...string) []interface{}
  • func (j *JsonQuery) AsArrayOfArrays(s ...string) [][]interface{}
  • func (j *JsonQuery) AsArrayOfBools(s ...string) []bool
  • func (j *JsonQuery) AsArrayOfFloats(s ...string) []float64
  • func (j *JsonQuery) AsArrayOfInts(s ...string) []int
  • func (j *JsonQuery) AsArrayOfObjects(s ...string) []map[string]interface{}
  • func (j *JsonQuery) AsArrayOfStrings(s ...string) []string
  • func (j *JsonQuery) AsBool(s ...string) bool
  • func (j *JsonQuery) AsFloat(s ...string) float64
  • func (j *JsonQuery) AsInt(s ...string) int
  • func (j *JsonQuery) AsInterface(s ...string) interface{}
  • func (j *JsonQuery) AsMatrix2D(s ...string) [][]interface{}
  • func (j *JsonQuery) AsObject(s ...string) map[string]interface{}
  • func (j *JsonQuery) AsString(s ...string) string
  • func (j *JsonQuery) Bool(s ...string) (bool, error)
  • func (j *JsonQuery) Exists(s ...string) bool
  • func (j *JsonQuery) Float(s ...string) (float64, error)
  • func (j *JsonQuery) Get(s ...string) (interface{}, error)
  • func (j *JsonQuery) Int(s ...string) (int, error)
  • func (j *JsonQuery) Interface(s ...string) (interface{}, error)
  • func (j *JsonQuery) Matrix2D(s ...string) ([][]interface{}, error)
  • func (j *JsonQuery) Object(s ...string) (map[string]interface{}, error)
  • func (j *JsonQuery) String(s ...string) (string, error)

Types

type JsonQuery

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

JsonQuery is an object that enables querying of a Go interface 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) AsArray

func (j *JsonQuery) AsArray(s ...string) []interface{}

AsArray extracts a []interface{} from the JsonQuery, but panics on error so it can be used inline

func (*JsonQuery) AsArrayOfArrays

func (j *JsonQuery) AsArrayOfArrays(s ...string) [][]interface{}

AsArrayOfArrays extracts an array of []interface{} (arrays) from some json, but panics on error so it can be used inline

func (*JsonQuery) AsArrayOfBools

func (j *JsonQuery) AsArrayOfBools(s ...string) []bool

AsArrayOfBools extracts an array of bools from some json, but panics on error so it can be used inline

func (*JsonQuery) AsArrayOfFloats

func (j *JsonQuery) AsArrayOfFloats(s ...string) []float64

AsArrayOfFloats extracts an array of float64s from some json, but panics on error so it can be used inline

func (*JsonQuery) AsArrayOfInts

func (j *JsonQuery) AsArrayOfInts(s ...string) []int

AsArrayOfInts extracts an array of ints from some json, but panics on error so it can be used inline

func (*JsonQuery) AsArrayOfObjects

func (j *JsonQuery) AsArrayOfObjects(s ...string) []map[string]interface{}

AsArrayOfObjects extracts an array of map[string]interface{} (objects) from some json, but panics on error so it can be used inline

func (*JsonQuery) AsArrayOfStrings

func (j *JsonQuery) AsArrayOfStrings(s ...string) []string

AsArrayOfStrings extracts an array of strings from some json, but panics on error so it can be used inline

func (*JsonQuery) AsBool

func (j *JsonQuery) AsBool(s ...string) bool

AsBool extracts a bool the JsonQuery, but panics on error so it can be used inline

func (*JsonQuery) AsFloat

func (j *JsonQuery) AsFloat(s ...string) float64

AsFloat extracts a float from the JsonQuery, but panics on error so it can be used inline

func (*JsonQuery) AsInt

func (j *JsonQuery) AsInt(s ...string) int

AsInt extracts an int from the JsonQuery, but panics on error so it can be used inline

func (*JsonQuery) AsInterface

func (j *JsonQuery) AsInterface(s ...string) interface{}

AsInterface extracts an interface{} from the JsonQuery, but panics on error so it can be used inline

func (*JsonQuery) AsMatrix2D

func (j *JsonQuery) AsMatrix2D(s ...string) [][]interface{}

AsMatrix2D is an alias for ArrayOfArrays

func (*JsonQuery) AsObject

func (j *JsonQuery) AsObject(s ...string) map[string]interface{}

AsObject extracts a json object from the JsonQuery, but panics on error so it can be used inline

func (*JsonQuery) AsString

func (j *JsonQuery) AsString(s ...string) string

AsString extracts a string from the JsonQuery, but panics on error so it can be used inline

func (*JsonQuery) Bool

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

Bool extracts a bool the JsonQuery

func (*JsonQuery) Exists

func (j *JsonQuery) Exists(s ...string) bool

Exists return true if node can be accessed, else false

func (*JsonQuery) Float

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

Float extracts a float from the JsonQuery

func (*JsonQuery) Get

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

Get extracts a untyped field 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