Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ploubser/JSON-Grep

Command line tool and API for parsing JSON documents
https://github.com/ploubser/JSON-Grep

Last synced: about 2 months ago
JSON representation

Command line tool and API for parsing JSON documents

Lists

README 

        
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] or [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)