mirror of
https://github.com/tomnomnom/gron
synced 2024-10-18 16:52:20 +00:00
230 lines
6.1 KiB
Markdown
230 lines
6.1 KiB
Markdown
# 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.
|
|
|
|
<pre>
|
|
▶ <b>gron</b> "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 = "mail@tomnomnom.com";
|
|
json[0].commit.author.name = "Tom Hudson";
|
|
</pre>
|
|
|
|
gron can work backwards too, enabling you to turn your filtered data back into JSON:
|
|
<pre>
|
|
▶ gron "https://api.github.com/repos/tomnomnom/gron/commits?per_page=1" | fgrep "commit.author" | <b>gron --ungron</b>
|
|
[
|
|
{
|
|
"commit": {
|
|
"author": {
|
|
"date": "2016-07-02T10:51:21Z",
|
|
"email": "mail@tomnomnom.com",
|
|
"name": "Tom Hudson"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
</pre>
|
|
|
|
> 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 get` (if you're using Go 1.7 or newer):
|
|
|
|
```
|
|
▶ go get -u github.com/tomnomnom/gron
|
|
```
|
|
|
|
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 = "mail@tomnomnom.com";
|
|
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 = "mail@tomnomnom.com";
|
|
---
|
|
> json.contact.email = "contact@tomnomnom.com";
|
|
```
|
|
|
|
The output of `gron` is valid JavaScript:
|
|
|
|
```
|
|
▶ gron testdata/two.json > tmp.js
|
|
▶ echo "console.log(json);" >> tmp.js
|
|
▶ nodejs tmp.js
|
|
{ contact: { email: 'mail@tomnomnom.com', twitter: '@TomNomNom' },
|
|
github: 'https://github.com/tomnomnom/',
|
|
likes: [ 'code', 'cheese', 'meat' ],
|
|
name: 'Tom' }
|
|
```
|
|
|
|
## ungronning
|
|
gron can also turn its output back into JSON:
|
|
```
|
|
▶ gron testdata/two.json | gron -u
|
|
{
|
|
"contact": {
|
|
"email": "mail@tomnomnom.com",
|
|
"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"
|
|
]
|
|
}
|
|
```
|
|
|
|
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)
|
|
-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
|
|
--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.
|