jgrep

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, --simple [FIELDS]   : Greps the JSON and only returns the value of the field(s) specified
-c, --compat            : Returns the JSON in its non-pretty flat form
-n, --stream            : Specify continuous input
-f, --flatten           : Flatten the results as much as possible
-i, --input [FILENAME]  : Target JSON file to use as input
-q, --quiet             : Quiet; don't write to stdout.  Exit with zero status if match found.
-v, --verbose           : Verbose output that will list a document if it fails to parse
    --start FIELD       : Starts the grep at a specific key in the document
    --slice [RANGE]     : A range of the form 'n' or 'n..m', indicating which documents to extract from the final output

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

The --slice flag

Allows the user to provide an int or range to slice an array of results with, in particular so a single element can be extracted, e.g.

$ echo '[{"foo": {"bar": "baz"}}, {"foo": {"bar":"baz"}}]' |
    jgrep "foo.bar=baz" --slice 0
{
  "foo": {
    "bar": "baz"
  }
}

The --stream flag

With the --stream or -n flag, jgrep will process multiple JSON inputs (newline separated) until standard input is closed. Each JSON input will be processed as usual, but the output immediately printed.

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)