Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

https://github.com/tomnomnom/gron

Make JSON greppable!
https://github.com/tomnomnom/gron

Last synced: 7 days ago
JSON representation

Make JSON greppable!

Awesome Lists containing this project

README 

        
# gron

[![Build Status](https://travis-ci.org/tomnomnom/gron.svg?branch=master)](https://travis-ci.org/tomnomnom/gron)



Make JSON greppable!



gron transforms JSON into discrete assignments to make it easier to `grep` for what you want and see the absolute 'path' to it.

It eases the exploration of APIs that return large blobs of JSON but have terrible documentation.




▶ gron "https://api.github.com/repos/tomnomnom/gron/commits?per_page=1" | fgrep "commit.author"

json[0].commit.author = {};

json[0].commit.author.date = "2016-07-02T10:51:21Z";

json[0].commit.author.email = "[email protected]";

json[0].commit.author.name = "Tom Hudson";




gron can work backwards too, enabling you to turn your filtered data back into JSON:


▶ gron "https://api.github.com/repos/tomnomnom/gron/commits?per_page=1" | fgrep "commit.author" | gron --ungron

[

  {

    "commit": {

      "author": {

        "date": "2016-07-02T10:51:21Z",

        "email": "[email protected]",

        "name": "Tom Hudson"

      }

    }

  }

]




> Disclaimer: the GitHub API has fantastic documentation, but it makes for a good example.



## Installation



gron has no runtime dependencies. You can just [download a binary for Linux, Mac, Windows or FreeBSD and run it](https://github.com/tomnomnom/gron/releases).

Put the binary in your `$PATH` (e.g. in `/usr/local/bin`) to make it easy to use:

```

▶ tar xzf gron-linux-amd64-0.1.5.tgz

▶ sudo mv gron /usr/local/bin/

```



If you're a Mac user you can also [install gron via brew](http://braumeister.org/formula/gron):

```

▶ brew install gron

```



Or if you're a Go user you can use `go install`:



```

▶ go install github.com/tomnomnom/gron@latest

```



It's recommended that you alias `ungron` or `norg` (or both!) to `gron --ungron`. Put something like this in your shell profile (e.g. in `~/.bashrc`):

```

alias norg="gron --ungron"

alias ungron="gron --ungron"

```

Or you could create a shell script in your $PATH named `ungron` or `norg` to affect all users:

```

gron --ungron "$@"

```



## Usage



Get JSON from a file:



```

▶ gron testdata/two.json 

json = {};

json.contact = {};

json.contact.email = "[email protected]";

json.contact.twitter = "@TomNomNom";

json.github = "https://github.com/tomnomnom/";

json.likes = [];

json.likes[0] = "code";

json.likes[1] = "cheese";

json.likes[2] = "meat";

json.name = "Tom";

```



From a URL:



```

▶ gron http://headers.jsontest.com/

json = {};

json.Host = "headers.jsontest.com";

json["User-Agent"] = "gron/0.1";

json["X-Cloud-Trace-Context"] = "6917a823919477919dbc1523584ba25d/11970839830843610056";

```



Or from `stdin`:



```

▶ curl -s http://headers.jsontest.com/ | gron

json = {};

json.Accept = "*/*";

json.Host = "headers.jsontest.com";

json["User-Agent"] = "curl/7.43.0";

json["X-Cloud-Trace-Context"] = "c70f7bf26661c67d0b9f2cde6f295319/13941186890243645147";

```



Grep for something and easily see the path to it:



```

▶ gron testdata/two.json | grep twitter

json.contact.twitter = "@TomNomNom";

```



gron makes diffing JSON easy too:



```

▶ diff <(gron two.json) <(gron two-b.json)

3c3

< json.contact.email = "[email protected]";

---

> json.contact.email = "[email protected]";

```



The output of `gron` is valid JavaScript:



```

▶ gron testdata/two.json > tmp.js

▶ echo "console.log(json);" >> tmp.js

▶ nodejs tmp.js

{ contact: { email: '[email protected]', twitter: '@TomNomNom' },

  github: 'https://github.com/tomnomnom/',

  likes: [ 'code', 'cheese', 'meat' ],

  name: 'Tom' }

```



It's also possible to obtain the `gron` output as JSON stream via

the `--json` switch:



```

▶ curl -s http://headers.jsontest.com/ | gron --json

[[],{}]

[["Accept"],"*/*"]

[["Host"],"headers.jsontest.com"]

[["User-Agent"],"curl/7.43.0"]

[["X-Cloud-Trace-Context"],"c70f7bf26661c67d0b9f2cde6f295319/13941186890243645147"]

```



## ungronning

gron can also turn its output back into JSON:

```

▶ gron testdata/two.json | gron -u

{

  "contact": {

    "email": "[email protected]",

    "twitter": "@TomNomNom"

  },

  "github": "https://github.com/tomnomnom/",

  "likes": [

    "code",

    "cheese",

    "meat"

  ],

  "name": "Tom"

}

```



This means you use can use gron with `grep` and other tools to modify JSON:

```

▶ gron testdata/two.json | grep likes | gron --ungron

{

  "likes": [

    "code",

    "cheese",

    "meat"

  ]

}

```



or



```

▶ gron --json testdata/two.json | grep likes | gron  --json --ungron

{

  "likes": [

    "code",

    "cheese",

    "meat"

  ]

}

```



To preserve array keys, arrays are padded with `null` when values are missing:

```

▶ gron testdata/two.json | grep likes | grep -v cheese

json.likes = [];

json.likes[0] = "code";

json.likes[2] = "meat";

▶ gron testdata/two.json | grep likes | grep -v cheese | gron --ungron

{

  "likes": [

    "code",

    null,

    "meat"

  ]

}

```



If you get creative you can do [some pretty neat tricks with gron](ADVANCED.mkd), and

then ungron the output back into JSON.



## Get Help



```

▶ gron --help

Transform JSON (from a file, URL, or stdin) into discrete assignments to make it greppable



Usage:

  gron [OPTIONS] [FILE|URL|-]



Options:

  -u, --ungron     Reverse the operation (turn assignments back into JSON)

  -v, --values     Print just the values of provided assignments

  -c, --colorize   Colorize output (default on tty)

  -m, --monochrome Monochrome (don't colorize output)

  -s, --stream     Treat each line of input as a separate JSON object

  -k, --insecure   Disable certificate validation

  -j, --json       Represent gron data as JSON stream

      --no-sort    Don't sort output (faster)

      --version    Print version information



Exit Codes:

  0	OK

  1	Failed to open file

  2	Failed to read input

  3	Failed to form statements

  4	Failed to fetch URL

  5	Failed to parse statements

  6	Failed to encode JSON



Examples:

  gron /tmp/apiresponse.json

  gron http://jsonplaceholder.typicode.com/users/1 

  curl -s http://jsonplaceholder.typicode.com/users/1 | gron

  gron http://jsonplaceholder.typicode.com/users/1 | grep company | gron --ungron

```



## FAQ

### Wasn't this written in PHP before?

Yes it was! The original version is [preserved here for posterity](https://github.com/tomnomnom/gron/blob/master/original-gron.php).



### Why the change to Go?

Mostly to remove PHP as a dependency. There's a lot of people who work with JSON who don't have PHP installed.



### Why shouldn't I just use jq?

[jq](https://stedolan.github.io/jq/) is *awesome*, and a lot more powerful than gron, but with that power comes

complexity. gron aims to make it easier to use the tools you already know, like `grep` and `sed`.



gron's primary purpose is to make it easy to find the path to a value in a deeply nested JSON blob

when you don't already know the structure; much of jq's power is unlocked only once you know that structure.