Command line tool and API for parsing JSON documents
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
lib
spec
.gitignore
.travis.yml
CHANGELOG.markdown
COPYING
Gemfile
README.markdown
Rakefile
jgrep.gemspec

README.markdown

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)