JGrep is a command line tool and API for parsing JSON documents based on logical expressions.
###Installation:###
jgrep is available as a gem:
gem install jgrep
###JGrep binary usage:###
jgrep [expression] -i foo.json
or
cat "foo.json" | jgrep [expression]
###Flags:###
-s "[Document fields]" : Greps the JSON and only returns the value of the field(s) specified
-c : Returns the JSON in its non-pretty flat form
-f : Flatten the results as much as possible
-v : Verbose output that will list a document if it fails to parse
-i [FILENAME] : Target JSON file to use as input
--start FIELD : Starts the grep at a specific key in the document
-q : Quiet; don't write to stdout. Exit with zero status if match found.
###Expressions###
JGrep uses the following logical symbols to define expressions.
'and' :
- [statement] and [statement]
Evaluates to true if both statements are true
'or' :
- [statement] and [statement]
Evaluates true if either statement is true
'not' :
- ! [statement]
- not [statement]
Inverts the value of statement
'+'
- +[value]
Returns true if value is present in the json document
'-'
- -[value]
Returns true if value is not present in the json doument
'(' and ')'
- (expression1) and expression2
Performs the operations inside the perentheses first.
###Statements:###
A statement is defined as some value in a json document compared to another value. Available comparison operators are '=', '<', '>', '<=', '>='
Examples:
foo.bar=1
foo.bar>0
foo.bar<=1.3
###Complex expressions:###
Given a json document, {"foo":1, "bar":null}, the following are examples of valid expressions
Examples:
+foo
... returns true
-bar
... returns false
+foo and !(foo=2)
... returns true
!(foo>=2 and bar=null) or !(bar=null)
... returns true
###CLI missing an expression###
If JGrep is executed without a set expression, it will return an unmodified JSON document. The -s flag can still be applied to the result.
###In document comparison:###
If a document contains an array, the '[' and ']' operators can be used to define a comparison where statements are checked for truth on a per element basis which will then be combined.
Example:
[foo.bar1=1 and foo.bar2=2]
on
[
{
"foo": [
{
"bar1":1
},
{
"bar2":2
}
]
},
{
"foo": [
{
"bar1":0
},
{
"bar2":0
}
]
}
]
will return
[
{
"foo": [
{
"bar1": 1
},
{
"bar2": 2
}
]
}
]
Note: In document comparison cannot be nested.
###The -s flag###
The s flag simplifies the output returned by JGrep. Given a JSON document
[{"a":1, "b":2, "c":3}, {"a":3, "b":2, "c":1}]
a JGrep invocation like
cat my.json | jgrep "a=1" -s b
will output
1
The s flag can also be used with multiple field, which will return JSON as output which only contain the specified fields. Note: Separate fields by a space and enclose all fields in quotes (see example below)
Given:
[{"a":1, "b":2, "c":3}, {"a":3, "b":2, "c":1}]
a JGrep invocation like
cat my.json | jgrep "a>0" -s "a c"
will output
[
{
"a" : 1,
"c" : 3
},
{
"a" : 3,
"c" : 1
}
]
###The --start flag###
Some documents do not comply to our expected format, they might have an array embedded deep in a field. The --start flag lets you pick a starting point for the grep.
An example document can be seen here:
{"results": [
{"name":"Jack", "surname":"Smith"},
{"name":"Jill", "surname":"Jones"}
]
}
This document does not comply to our standard but does contain data that can be searched - the results field. We can use the --start flat to tell jgrep to start looking for data in that field:
$ cat my.json | jgrep --start results name=Jack -s surname Smith
###JGrep Gem usage:###
require 'jgrep'
json = File.read("yourfile.json")
expression = "foo=1 or bar=1"
JGrep::jgrep(json, expression)
sflags = "foo"
JGrep::jgrep(json, expression, sflags)