Skip to content

nytlabs/gojee

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

21 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

jee

jee (json expression evaluator) transforms JSON through logical and mathematical expressions. jee can be used from the command line or as a Go package. It is inspired by the fantastic (and much more fully featured) jq.

jee was created out of the need for a simple JSON query language in streamtools. jee is designed for stream processing and provides a reusable token tree.

####get the library

go get github.com/nytlabs/gojee

####make and install the binary

cd $gopath/src/github.com/nytlabs/gojee/jee
go install

usage (binary)

querying JSON

get the entire input object:

> echo '{"a": 3}' | jee '.'
{
    "a": 3
}

get a value for a specific key:

> echo '{"a": 3, "b": 4}' | jee '.a'
3

get a value from an array:

> echo '{"a": [4,5,6]}' | jee '.a[0]'
4

get all values from an array:

> echo '{"a": [4,5,6]}' | jee '.a[]'
[
    4,
    5,
    6
]

query all objects inside array 'a' for key 'id':

> echo '{"a": [{"id":"foo"},{"id":"bar"},{"id":"baz"}]}' | jee '.a[].id'
[
    "foo",
    "bar",
    "baz"
]
arithmetic

+ - * /

> echo '{"a": 10}' | jee '(.a * 100)/-10 * 5'
-500
comparison

> >= < <= !=

> echo '{"a": 10}' | jee '(.a * 100)/-10 * 5 == -500'
true
> echo '{"a": 10}' | jee '(.a * 100)/-10 * 5 > 0'
false
logical

|| &&

> echo '{"a": false}' | jee '!(.a && true) || false  == true'
true
functions
types

$num(x {bool, float64, string, nil})
Converts x to a float64. If x is a bool, 1 is returned for true and 0 for false. If x is nil, 0 is returned.

$str(x {bool, float64, string, nil, object, []*))
Converts x to a string. If x is a bool, "true" is returned for true and "false" for false. "null" is returned for nil. If x is an object or an array, it is marshaled into a JSON string.

$bool(x {bool, string})
Converts x to a bool. See strconv.ParseBool

$~bool(x {bool, float64, string, nil, object, []*})
Truthy conversion of x to a bool. Falsey values:null,NaN,0,false, and arrays with a length of 0.

math

$sqrt(x float64)
Returns square root of x.

$pow(x float64, y float64)
Returns x^y.

$floor(x float64)
Returns nearest downward integer for x.

$abs(x float64)
Returns absolute value of x.

arrays

$len(a []interface{})
Returns the length of array a.

$has( a {[]bool, []float64, []string, []nil}, val {bool, float64, string, nil} )
Checks to see if array a contains val. Returns bool. val cannot be an object.

$sum(a []float64)
Returns the sum of array a.

$min(a []float64)
Returns the minumum of array a.

$max(a []float64)
Returns the maximum of array a.

objects

$keys(o object)
Returns an array of keys in object o.

$exists(o object, key string)
Checks to see if key exists in map o. Returns bool. $exists() does a map lookup and is faster than $has($keys(o), "foo")


date and time

$now()
Returns current system time in float64 (epoch milliseconds).

$parseTime(layout string, t string)
Accepts a time layout in golang time format. t is parsed and returned as epoch milliseconds in float64.

$fmtTime(layout string, t float64)
Accepts a time layout in golang time format. t is expected in epoch milliseconds. Returns a formatted string.

strings

$contains(s string, substr string)
see strings.Contains

$regex(pattern string, s string)
see regexp.MatchString. Much slower than $contains()

see jee_test.go for examples.

package usage

#####Lexer(string) []*Token, error converts a jee query string into a slice of tokens

#####Parser([]*Tokens) *TokenTree, error builds a parse tree out token slice from Lexer()

#####Eval(*TokenTree, {}interface) {}interface, error evaluates a variable of type interface{} with a *TokenTree generated from Parser(). Only types given by json.Unmarshal are supported.

quirks

  • Types are strictly enforced. false || "foo" will produce a type error.
  • null and 0 are not falsey
  • Using a JSON key as an array index or an escaped key in bracket notation will not currently be evaluated. ie: .a[.b]
  • All numbers in a jee query must start with a digit. numbers <1 should start with a 0. use 0.1 instead of .1
  • Bracket notation is available for keys that need escaping .["foo"]["bar"]]
  • Queries for JSON keys or indices that do not exist return null (to test if a key exists, use $exists)
  • jee does not support variables, conditional expressions, or assignment
  • jee may be very quirky in general.

changes

  • .0.1.1 addition of $bool, $~bool, $num, $str, $now, $fmtTime, $parseTime. Fix for non-alphanumeric characters in JSON keys.
  • .0.1.0 initial release

Releases

No releases published

Packages

No packages published

Languages