jq

README

jq

A high performance Golang implementation of the incredibly useful jq command line tool.

Rather than marshalling json elements into go instances, jq opts to manipulate the json elements as raw []byte. This is especially useful for apps that need to handle dynamic json data.

Using jq consists of creation an Op and then calling Apply on the Op to transform one []byte into the desired []byte. Ops may be chained together to form a transformation chain similar to how the command line jq works.

Installation

go get github.com/savaki/jq

Example

package main

import (
	"fmt"

	"github.com/savaki/jq"
)

func main() {
	op, _ := jq.Parse(".hello")           // create an Op
	data := []byte(`{"hello":"world"}`)   // sample input
	value, _ := op.Apply(data)            // value == '"world"'
	fmt.Println(string(value))
}

Syntax

The initial goal is to support all the selectors the original jq command line supports.

syntax	meaning
.	unchanged input
.foo	value at key
.foo.bar	value at nested key
.[0]	value at specified element of array
.[0:1]	array of specified elements of array, inclusive
.foo.[0]	nested value

Examples

Data

{
  "string": "a",
  "number": 1.23,
  "simple": ["a", "b", "c"],
  "mixed": [
    "a",
    1,
    {"hello":"world"}
  ],
  "object": {
    "first": "joe",
    "array": [1,2,3]
  }
}

syntax	value
.string	"a"
.number	1.23
.simple	["a", "b", "c"]
.simple.[0]	"a"
.simple.[0:1]	["a","b"]
.mixed.[1]	1
.object.first	"joe"
.object.array.[2]	3

Performance

BenchmarkAny-8         	20000000	        80.8 ns/op	       0 B/op	       0 allocs/op
BenchmarkArray-8       	20000000	       108 ns/op	       0 B/op	       0 allocs/op
BenchmarkFindIndex-8   	10000000	       125 ns/op	       0 B/op	       0 allocs/op
BenchmarkFindKey-8     	10000000	       125 ns/op	       0 B/op	       0 allocs/op
BenchmarkFindRange-8   	10000000	       186 ns/op	      16 B/op	       1 allocs/op
BenchmarkNumber-8      	50000000	        28.9 ns/op	       0 B/op	       0 allocs/op
BenchmarkObject-8      	20000000	        98.5 ns/op	       0 B/op	       0 allocs/op
BenchmarkString-8      	30000000	        40.4 ns/op	       0 B/op	       0 allocs/op

Documentation

Overview

Package jp offers a highly performant json selector in the style of the jq command line

Usage of this package involves the concept of an Op. An Op is a transformation that converts a []byte into a []byte. To get started, use the Parse function to obtain an Op.

op, err := jq.Parse(".key")

This will create an Op that will accept a JSON object in []byte format and return the value associated with "key." For example:

in := []byte(`{"key":"value"}`)
data, _ := op.Apply(in))
fmt.Println(string(data))

Will print the string "value". The goal is to support all the select operations supported by jq's command line namesake.

Index

• func FindIndices(key string) [][]string
• type Op
  • func Must(op Op, err error) Op
  • func Parse(selector string) (Op, error)
• type OpFunc
  • func Chain(filters ...Op) OpFunc
  • func Dot(key string) OpFunc
  • func From(from int) OpFunc
  • func Index(index int) OpFunc
  • func Range(from, to int) OpFunc
  • func To(to int) OpFunc
  • func (fn OpFunc) Apply(in []byte) ([]byte, error)

Functions

func FindIndices

func FindIndices(key string) [][]string

Types

type Op

type Op interface {
	Apply([]byte) ([]byte, error)
}

Op defines a single transformation to be applied to a []byte

func Must

func Must(op Op, err error) Op

Must is a convenience method similar to template.Must

func Parse

func Parse(selector string) (Op, error)

Parse takes a string representation of a selector and returns the corresponding Op definition

type OpFunc

type OpFunc func([]byte) ([]byte, error)

OpFunc provides a convenient func type wrapper on Op

func Chain

func Chain(filters ...Op) OpFunc

Chain executes a series of operations in the order provided

func Dot

func Dot(key string) OpFunc

Dot extract the specific key from the map provided; to extract a nested value, use the Dot Op in conjunction with the Chain Op

func From

func From(from int) OpFunc

From extracts all elements from the array provided from the given index onward, inclusive

func Index

func Index(index int) OpFunc

Index extracts a specific element from the array provided

func Range

func Range(from, to int) OpFunc

Range extracts a selection of elements from the array provided, inclusive

func To

func To(to int) OpFunc

To extracts all elements from the array provided up to the given index, inclusive

func (OpFunc) Apply

func (fn OpFunc) Apply(in []byte) ([]byte, error)

Apply executes the transformation defined by OpFunc