Browse files

update docs for json 2.0

  • Loading branch information...
1 parent 878f02a commit e7acc1bda8270b99bf23a3a860a7fa5cf0833a02 @trentm committed Oct 5, 2011
Showing with 288 additions and 114 deletions.
  1. +163 −26 README.md
  2. +0 −17 TODO.md
  3. +1 −0 bin/json2
  4. +51 −27 json.1.ronn
  5. +2 −5 lib/jsontool.js
  6. +69 −38 man/man1/json.1
  7. +2 −1 package.json
View
189 README.md
@@ -6,7 +6,7 @@ is a single-file node.js script.
1. Get [node](http://nodejs.org) and [npm](http://npmjs.org).
-2. `npm install jsontool`.
+2. `npm install -g jsontool`.
**OR manually**:
@@ -24,28 +24,33 @@ is a single-file node.js script.
Usage: <something generating JSON on stdout> | json [options] [lookups...]
- Pipe in your JSON for nicer output. Or supply one or more `lookups`
+ Pipe in your JSON for nicer output or supply one or more `lookups`
to extract a subset of the JSON. HTTP header blocks (as from `curl -i`)
are skipped by default.
- By default, the output is JSON-y: JSON, except for a simple string return
- value, which is printed without quotes. Use '-j' or '-i' to override.
-
Options:
-h, --help print this help info and exit
--version print version of this command and exit
-q, --quiet don't warn if input isn't valid JSON
- -H drop any HTTP header block
- -i output using node's `sys.inspect`
- -j output using `JSON.stringfy`, i.e. strict JSON
- -x, --experimental
- enable experimental features: '*' in lookup
+
+ -H drop any HTTP header block (as from `curl -i ...`)
+ -a, --array process input as an array of separate inputs
+ and output in tabular form
+ -d DELIM delimiter string for tabular output (default is ' ')
+
+ -o, --output MODE Specify an output mode. One of
+ jsony (default): JSON with string quotes elided
+ json: JSON output, 2-space indent
+ json-N: JSON output, N-space indent, e.g. 'json-4'
+ inspect: node.js `util.inspect` output
+ -i shortcut for `-o inspect`
+ -j shortcut for `-o json`
Examples:
curl -s http://search.twitter.com/search.json?q=node.js | json
curl -s http://search.twitter.com/search.json?q=node.js | json results
- See <https://github.com/trentm/json> for more.
+ See <https://github.com/trentm/json#readme> for more complete docs.
@@ -54,20 +59,20 @@ is a single-file node.js script.
Since v1.3.1 you can using "jsontool" as a node.js module:
var jsontool = require('jsontool');
-
+
However, so far the module API isn't that useful. This will improve in
subsequent releases. For now the cli is the primary focus.
-# Examples
+# Learn By Example
-Using the Github API to look at [node](https://github/joyent/node):
+Let's use the Github API to look at [node](https://github/joyent/node):
$ curl -s http://github.com/api/v2/json/repos/show/joyent/node
{"repository":{"has_wiki":true,"forks":597,"language":"C++","pushed_at":"2011/03/18 15:19:24 -0700","homepage":"http://nodejs.org/","open_issues":271,"fork":false,"has_issues":true,"url":"https://github.com/joyent/node","created_at":"2009/05/27 09:29:46 -0700","size":20984,"private":false,"has_downloads":false,"name":"node","owner":"joyent","organization":"joyent","watchers":5584,"description":"evented I/O for v8 javascript"}}
-Nice output by default:
+**Nice output by default**:
$ curl -s http://github.com/api/v2/json/repos/show/joyent/node | json
{
@@ -93,12 +98,12 @@ Nice output by default:
}
}
-Say you just want to extract one value:
+Say you just want to **extract one value**:
$ curl -s https://github.com/api/v2/json/repos/show/joyent/node | json repository.open_issues
- 271
+ 391
-If you use `curl -i` to get HTTP headers (because perhaps they contain relevant information), `json` will skip those automatically:
+If you use `curl -i` to get HTTP headers (because perhaps they contain relevant information), **`json` will skip the HTTP headers automatically**:
$ curl -is https://github.com/api/v2/json/repos/show/joyent/node | json repository
HTTP/1.1 200 OK
@@ -134,18 +139,155 @@ If you use `curl -i` to get HTTP headers (because perhaps they contain relevant
"open_issues": 229
}
-Or, say you are stuck with the headers in your pipeline, `json -H` will drop them:
+Or, say you are stuck with the headers in your pipeline, **`json -H` will drop HTTP headers**:
$ curl -is https://github.com/api/v2/json/repos/show/joyent/node | json -H repository.watchers
4753
-Here is an example that shows indexing a list. (The given "lookup" argument is basically
-JavaScript code appended, with '.' if necessary, to the JSON data and eval'd.)
+Here is **an example that shows indexing a list**. (The given "lookup"
+argument is basically JavaScript code appended, with '.' if necessary, to the
+JSON data and eval'd.)
$ curl -s http://github.com/api/v2/json/repos/search/nodejs | json 'repositories[2].description'
Connect is a middleware layer for Node.js
+# Array processing with `-a`
+
+`json` includes `-a` (aka `--array`) option for **processing each element of
+an input JSON array independently** and **using tabular output**. Let'sContinuing
+our example above, let's first get a list of repositories for a "nodejs"
+search on github:
+
+ $ curl -s http://github.com/api/v2/json/repos/search/nodejs | json repositories
+ [
+ {
+ "type": "repo",
+ "followers": 3922,
+ "watchers": 3922,
+ "has_issues": true,
+ "description": "Sinatra inspired web development framework for node.js -- insanely fast, flexible, and sexy",
+ "url": "https://github.com/visionmedia/express",
+ "has_downloads": true,
+ "created_at": "2009/06/26 11:56:01 -0700",
+ "pushed": "2011/09/28 10:27:26 -0700",
+ "forks": 345,
+ ...
+
+We can then print a table with just some fields as follows:
+
+ $ curl -s http://github.com/api/v2/json/repos/search/nodejs \
+ | json repositories | json -a forks url
+ 345 https://github.com/visionmedia/express
+ 136 https://github.com/unconed/TermKit
+ 292 https://github.com/LearnBoost/socket.io
+
+Ultimately this can be useful for then using other command-line tools. For
+example, we could get the list of top-five most forks "nodejs" github
+repos:
+
+ $ curl -s http://github.com/api/v2/json/repos/search/nodejs \
+ | json repositories | json -a forks url | sort -n | tail -5
+ 136 https://github.com/christkv/node-mongodb-native
+ 136 https://github.com/unconed/TermKit
+ 182 https://github.com/senchalabs/connect
+ 292 https://github.com/LearnBoost/socket.io
+ 345 https://github.com/visionmedia/express
+
+Or get a breakdown by ISO language code of the recent tweets mentioning "nodejs":
+
+ $ curl -s http://search.twitter.com/search.json?q=nodejs\&rpp=100 \
+ | json results | json -a iso_language_code | sort | uniq -c | sort
+ 1 es
+ 1 no
+ 1 th
+ 4 ru
+ 12 ja
+ 23 pt
+ 58 en
+
+The **`-d` option can be used to specify a delimiter**:
+
+ $ curl -s http://github.com/api/v2/json/repos/search/nodejs \
+ | json repositories | json -a forks url -d,
+
+ $ curl -s http://github.com/api/v2/json/repos/search/nodejs \
+ | json repositories | json -a forks watchers url -d,
+ 345,3922,https://github.com/visionmedia/express
+ 136,3128,https://github.com/unconed/TermKit
+ 292,2777,https://github.com/LearnBoost/socket.io
+ 104,1640,https://github.com/mishoo/UglifyJS
+ ...
+
+
+# Output flavours
+
+You can use the '-o MODE' option (or '--output MODE') to control the output
+flavour. By default the output is "jsony" (JSON, except that a simple string
+is printed *without the quotes*):
+
+ $ echo '[{"name": "Trent"},{"name": "Mark"}]' | json
+ [
+ {
+ "name": "Trent"
+ },
+ {
+ "name": "Mark"
+ }
+ ]
+
+ $ echo '[{"name": "Trent"},{"name": "Mark"}]' | json '[0].name'
+ Trent
+
+ $ echo '[{"name": "Trent"},{"name": "Mark"}]' | json '[0].name' -o jsony
+ Trent
+
+Or for strict JSON output:
+
+ $ echo '[{"name": "Trent"},{"name": "Mark"}]' | json -o json
+ [
+ {
+ "name": "Trent"
+ },
+ {
+ "name": "Mark"
+ }
+ ]
+
+ $ echo '[{"name": "Trent"},{"name": "Mark"}]' | json '[0].name' -o json
+ "Trent"
+
+By default this uses a 2-space indent. That can be changed with a "-N" suffix:
+
+ $ echo '[{"name": "Trent"},{"name": "Mark"}]' | json -o json-4
+ [
+ {
+ "name": "Trent"
+ },
+ {
+ "name": "Mark"
+ }
+ ]
+
+ $ echo '[{"name": "Trent"},{"name": "Mark"}]' | json -o json-0
+ [{"name":"Trent"},{"name":"Mark"}]
+
+You can get colored (non-JSON) output using node.js's [`util.inspect`](http://nodejs.org/docs/latest/api/all.html#util.inspect):
+
+ $ echo '[{"name": "Trent"},{"name": "Mark"}]' | json -o inspect
+ [ { name: 'Trent' },
+ { name: 'Mark' } ]
+
+Or a hacked up "compact" output mode which prints the elements of an array on their own line:
+
+ $ echo '[{"name": "Trent"},{"name": "Mark"}]' | json -o compact
+ [
+ {"name":"Trent"},
+ {"name":"Mark"}
+ ]
+
+
+
# Test suite
make test
@@ -162,11 +304,6 @@ If you are stuck with an older node and don't want the utf8 failure in your face
-# TODO
-
-- consider a '*' syntax for running the subsequent lookup on all items in a list
-
-
# Alternatives you might prefer
- json:select: <http://jsonselect.org/>
View
17 TODO.md
@@ -8,13 +8,6 @@
# top
-- -o|--output TYPE
- 'jsony' (default) is JSON except: (a) a bare string is output without
- quotes; (b) a
- 'json' (aka 'json-2')
- 'json-2'
- ...
- 'compact' # one object per line, better name?
- npm/lib/utils/minimatch.js: fnmatch/glob implementation.
Use that for more generic "*.foo" or "*.{foo,bar}" matching. Says Isaac: "it'd be cool :)".
https://github.com/isaacs/npm/blob/master/lib/utils/minimatch.js
@@ -74,16 +67,6 @@
]
-- finish '*' handling: support input of multiple json docs (see changelog entry for '*')
-
- $ echo '[{"one": "un"}, {"two": "deux"}]' | json -x '*'
- {
- "one": "un"
- }
- {
- "two": "deux"
- }
-
- The JSON syntax error sucks because it doesn't show where in the document the syntax error is. Sometimes it is hard to find.
json: error: doesn't look like JSON: SyntaxError: Unexpected token { (buffer="{...
View
1 bin/json2
View
78 json.1.ronn
@@ -3,57 +3,80 @@
## SYNOPSIS
-`<something generating JSON on stdout> | json [options] [lookup]`
+`<something generating JSON on stdout> | json [OPTIONS] [LOOKUPS]`
## DESCRIPTION
-Pipe in your JSON for nicer (pretty-printed) output. Or supply a `lookup` to
-extract a subset of the JSON. HTTP header blocks are skipped by default (as from
-`curl -i`) by default.
+Pipe in your JSON for nicer (pretty-printed) output or supply one or more
+lookups` to extract a subset of the JSON. HTTP header blocks are skipped by
+default (as from `curl -i`) by default.
-See a full changelog here <https://github.com/trentm/json/blob/master/CHANGES.md>
+See more complete documentation in the readme and changelog:
+- README: <https://github.com/trentm/json#readme>
+- Change log: <https://github.com/trentm/json/blob/master/CHANGES.md>
-## OPTIONS
-
-By default `json` outputs results in a "flat" format that is intended to be
-of most use to the UNIX command-line. Currently the only difference between
-flat and JSON output is that a simple string result is printed *without* JSON's
-double-quotes. Other output formats:
-
-- `-i`:
- output using node's `sys.inspect`
-- `-j`:
- output using `JSON.stringfy`, i.e. strict JSON
+## OPTIONS
-If your JSON output is a REST API response, it migth include the headers
+If your JSON output is a REST API response, it might include the headers
(e.g. when calling with `curl -i`). By default `json` will pass those headers
through (without choking on them). However if you want then stripped you
can use:
-- `-H`:
- drop a leading HTTP header block, if any
+`-H`
+ drop any HTTP header block (as from `curl -i ...`)
+
+
+By default `json` outputs results in a "flat" format that is intended to be
+of most use to the UNIX command-line. Currently the only difference between
+flat and JSON output is that a simple string result is printed *without* JSON's
+double-quotes. Other output formats are supported:
+
+`-o, --output MODE`
+ Specify an output mode. One of:
+
+ jsony (default): JSON with string quotes elided
+ json: JSON output, 2-space indent
+ json-N: JSON output, N-space indent, e.g. 'json-4'
+ inspect: node.js `util.inspect` output
+
+`-i`
+ shortcut for `-o inspect`
+
+`-j`
+ shortcut for `-o json`
+
+
+You can process elements of an input array separately and generate tabular
+output:
+
+`-a, --array`
+ Process input as an array of separate inputs and output in tabular form.
+
+`-d DELIM`
+ Delimiter string for tabular output (default is ' ').
+
Miscellaneous options:
-- `-h, --help`:
+`-h, --help`
print this help info and exit
-- `--version`:
+
+`--version`
print version of this command and exit
-- `-q, --quiet`:
+
+`-q, --quiet`
don't warn if input isn't valid JSON
-- `-x, --experimental`:
- Enable experimental features. Currently this enables '\*' in the lookup for JSON arrays.
## EXAMPLES
A REST API:
$ curl -s http://github.com/api/v2/json/repos/show/joyent/node
- {"repository":{"has_wiki":true,"forks":597,"language":"C++","pushed_at":"2011/03/18 15:19:24 -0700","homepage":"http://nodejs.org/","open_issues":271,"fork":false,"has_issues":true,"url":"https://github.com/joyent/node","created_at":"2009/05/27 09:29:46 -0700","size":20984,"private":false,"has_downloads":false,"name":"node","owner":"joyent","organization":"joyent","watchers":5584,"description":"evented I/O for v8 javascript"}}
+ {"repository":{"has_wiki":true,"forks":597,"language":"C++",...}
Nice output by default:
@@ -83,10 +106,11 @@ Nice output by default:
Say you just want to extract one value:
- $ curl -s https://github.com/api/v2/json/repos/show/joyent/node | json repository.open_issues
+ $ curl -s https://github.com/api/v2/json/repos/show/joyent/node \
+ | json repository.open_issues
271
-More examples at <https://github.com/trentm/json#readme>
+More examples at <https://github.com/trentm/json#readme>.
## BUGS
View
7 lib/jsontool.js
@@ -62,13 +62,10 @@ function isArray(ar) {
function printHelp() {
sys.puts("Usage: <something generating JSON on stdout> | json [options] [lookups...]");
sys.puts("");
- sys.puts("Pipe in your JSON for nicer output. Or supply one or more `lookups`");
+ sys.puts("Pipe in your JSON for nicer output or supply one or more `lookups`");
sys.puts("to extract a subset of the JSON. HTTP header blocks (as from `curl -i`)");
sys.puts("are skipped by default.");
sys.puts("");
- sys.puts("By default, the output is JSON-y: JSON, except for a simple string return");
- sys.puts("value, which is printed without quotes. Use '-j' or '-i' to override.");
- sys.puts("");
sys.puts("Options:");
sys.puts(" -h, --help print this help info and exit");
sys.puts(" --version print version of this command and exit");
@@ -91,7 +88,7 @@ function printHelp() {
sys.puts(" curl -s http://search.twitter.com/search.json?q=node.js | json");
sys.puts(" curl -s http://search.twitter.com/search.json?q=node.js | json results");
sys.puts("");
- sys.puts("See <https://github.com/trentm/json> for more.");
+ sys.puts("See <https://github.com/trentm/json> for more complete docs.");
}
View
107 man/man1/json.1
@@ -1,69 +1,96 @@
.\" Generated with Ronnjs/v0.1
.\" http://github.com/kapouer/ronnjs/
.
-.TH "JSON" "1" "May 2011" "" ""
+.TH "JSON" "1" "October 2011" "" ""
.
.SH "NAME"
\fBjson\fR \-\- JSON love for your command line
.
.SH "SYNOPSIS"
-\fB<something generating JSON on stdout> | json [options] [lookup]\fR
+\fB<something generating JSON on stdout> | json [OPTIONS] [LOOKUPS]\fR
.
.SH "DESCRIPTION"
-Pipe in your JSON for nicer (pretty\-printed) output\. Or supply a \fBlookup\fR to
-extract a subset of the JSON\. HTTP header blocks are skipped by default (as from \fBcurl \-i\fR) by default\.
+Pipe in your JSON for nicer (pretty\-printed) output or supply one or more
+lookups\fB to extract a subset of the JSON\. HTTP header blocks are skipped by
+default (as from \fRcurl \-i`) by default\.
.
.P
-See a full changelog here \fIhttps://github\.com/trentm/json/blob/master/CHANGES\.md\fR
-.
-.SH "OPTIONS"
-By default \fBjson\fR outputs results in a "flat" format that is intended to be
-of most use to the UNIX command\-line\. Currently the only difference between
-flat and JSON output is that a simple string result is printed \fIwithout\fR JSON\'s
-double\-quotes\. Other output formats:
+See more complete documentation in the readme and changelog:
.
.IP "\(bu" 4
-\fB\-i\fR:
-output using node\'s \fBsys\.inspect\fR
+README: \fIhttps://github\.com/trentm/json#readme\fR
.
.IP "\(bu" 4
-\fB\-j\fR:
-output using \fBJSON\.stringfy\fR, i\.e\. strict JSON
+Change log: \fIhttps://github\.com/trentm/json/blob/master/CHANGES\.md\fR
.
.IP "" 0
.
-.P
-If your JSON output is a REST API response, it migth include the headers
+.SH "OPTIONS"
+If your JSON output is a REST API response, it might include the headers
(e\.g\. when calling with \fBcurl \-i\fR)\. By default \fBjson\fR will pass those headers
through (without choking on them)\. However if you want then stripped you
can use:
.
-.IP "\(bu" 4
-\fB\-H\fR:
-drop a leading HTTP header block, if any
+.P
+\fB\-H\fR
+ drop any HTTP header block (as from \fBcurl \-i \.\.\.\fR)
+.
+.P
+By default \fBjson\fR outputs results in a "flat" format that is intended to be
+of most use to the UNIX command\-line\. Currently the only difference between
+flat and JSON output is that a simple string result is printed \fIwithout\fR JSON\'s
+double\-quotes\. Other output formats are supported:
+.
+.P
+\fB\-o, \-\-output MODE\fR
+ Specify an output mode\. One of:
+.
+.IP "" 4
+.
+.nf
+ jsony (default): JSON with string quotes elided
+ json: JSON output, 2\-space indent
+ json\-N: JSON output, N\-space indent, e\.g\. \'json\-4\'
+ inspect: node\.js `util\.inspect` output
+.
+.fi
.
.IP "" 0
.
.P
-Miscellaneous options:
+\fB\-i\fR
+ shortcut for \fB\-o inspect\fR
.
-.IP "\(bu" 4
-\fB\-h, \-\-help\fR:
-print this help info and exit
+.P
+\fB\-j\fR
+ shortcut for \fB\-o json\fR
.
-.IP "\(bu" 4
-\fB\-\-version\fR:
-print version of this command and exit
+.P
+You can process elements of an input array separately and generate tabular
+output:
.
-.IP "\(bu" 4
-\fB\-q, \-\-quiet\fR:
-don\'t warn if input isn\'t valid JSON
+.P
+\fB\-a, \-\-array\fR
+ Process input as an array of separate inputs and output in tabular form\.
.
-.IP "\(bu" 4
-\fB\-x, \-\-experimental\fR:
-Enable experimental features\. Currently this enables \'*\' in the lookup for JSON arrays\.
+.P
+\fB\-d DELIM\fR
+ Delimiter string for tabular output (default is \' \')\.
.
-.IP "" 0
+.P
+Miscellaneous options:
+.
+.P
+\fB\-h, \-\-help\fR
+ print this help info and exit
+.
+.P
+\fB\-\-version\fR
+ print version of this command and exit
+.
+.P
+\fB\-q, \-\-quiet\fR
+ don\'t warn if input isn\'t valid JSON
.
.SH "EXAMPLES"
A REST API:
@@ -72,7 +99,7 @@ A REST API:
.
.nf
$ curl \-s http://github\.com/api/v2/json/repos/show/joyent/node
-{"repository":{"has_wiki":true,"forks":597,"language":"C++","pushed_at":"2011/03/18 15:19:24 \-0700","homepage":"http://nodejs\.org/","open_issues":271,"fork":false,"has_issues":true,"url":"https://github\.com/joyent/node","created_at":"2009/05/27 09:29:46 \-0700","size":20984,"private":false,"has_downloads":false,"name":"node","owner":"joyent","organization":"joyent","watchers":5584,"description":"evented I/O for v8 javascript"}}
+{"repository":{"has_wiki":true,"forks":597,"language":"C++",\.\.\.}
.
.fi
.
@@ -118,26 +145,30 @@ Say you just want to extract one value:
.IP "" 4
.
.nf
-$ curl \-s https://github\.com/api/v2/json/repos/show/joyent/node | json repository\.open_issues
+$ curl \-s https://github\.com/api/v2/json/repos/show/joyent/node \\
+ | json repository\.open_issues
271
.
.fi
.
.IP "" 0
.
.P
-More examples at \fIhttps://github\.com/trentm/json#readme\fR
+More examples at \fIhttps://github\.com/trentm/json#readme\fR\|\.
.
.SH "BUGS"
\fBjson\fR is written in JavaScript and requires node\.js (\fBnode\fR)\. Report bugs
-to \fIhttps://github\.com/trentm/json\fR\|\.
+to \fIhttps://github\.com/trentm/json/issues\fR\|\.
.
.SH "COPYRIGHT"
json is Copyright (c) 2011 Trent Mick
.
.SH "SEE ALSO"
.
.IP "\(bu" 4
+json:select: \fIhttp://jsonselect\.org/\fR
+.
+.IP "\(bu" 4
jsonpipe: \fIhttps://github\.com/dvxhouse/jsonpipe\fR
.
.IP "\(bu" 4
View
3 package.json
@@ -1,7 +1,7 @@
{
"name": "jsontool",
"description": "a 'json' command for massaging JSON on your Unix command line",
- "version": "1.4.2",
+ "version": "2.0.0",
"repository": {
"type": "git",
"url": "git://github.com/trentm/json.git"
@@ -11,6 +11,7 @@
],
"bin": {
"json": "./lib/jsontool.js"
+ "json2": "./lib/jsontool.js"
},
"main": "./lib/jsontool.js",
"man": "./man/man1/json.1",

0 comments on commit e7acc1b

Please sign in to comment.