From 4723a173f58b600091bddba4abaecbb35985af75 Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Tue, 11 Aug 2015 22:02:53 -0700 Subject: [PATCH] Update wording and json bodies in tutorial --- docs/content/1.tutorial/default.yml | 289 ++++++++++++++-------------- 1 file changed, 147 insertions(+), 142 deletions(-) diff --git a/docs/content/1.tutorial/default.yml b/docs/content/1.tutorial/default.yml index 43097f3..5a2dcb8 100644 --- a/docs/content/1.tutorial/default.yml +++ b/docs/content/1.tutorial/default.yml @@ -2,8 +2,8 @@ headline: Tutorial body: - text: | - GitHub has a JSON API, so let's play with that. This URL gets - us the last 5 commits from the jq repo: + GitHub has a JSON API, so let's play with that. This URL gets us the last + 5 commits from the jq repo. - command: "curl 'https://api.github.com/repos/stedolan/jq/commits?per_page=5'" result: | @@ -34,174 +34,180 @@ body: "comments_url": "https://api.github.com/repos/stedolan/jq/commits/d25341478381063d1c76e81b3a52e0592a7c997f/comments", "author": { "login": "stedolan", - ... + ... - text: | - Github returns a ton of info here, and it's relatively hard to - read as it is. To syntax highlight it and order the attributes we pipe - it through jq, telling jq to just spit the input back at us using - the expression `.`: + + GitHub returns nicely formatted JSON. For servers that don't, it can be + helpful to pipe the response through jq to pretty-print it. The simplest + jq program is the expression `.`, which takes the input and produces it + unchanged as output. - command: "curl 'https://api.github.com/repos/stedolan/jq/commits?per_page=5' | jq '.'" result: | [ { - "parents": [ - { - "html_url": "https://github.com/stedolan/jq/commit/54b9c9bdb225af5d886466d72f47eafc51acb4f7", - "url": "https://api.github.com/repos/stedolan/jq/commits/54b9c9bdb225af5d886466d72f47eafc51acb4f7", - "sha": "54b9c9bdb225af5d886466d72f47eafc51acb4f7" + "sha": "d25341478381063d1c76e81b3a52e0592a7c997f", + "commit": { + "author": { + "name": "Stephen Dolan", + "email": "mu@netsoc.tcd.ie", + "date": "2013-06-22T16:30:59Z" }, - { - "html_url": "https://github.com/stedolan/jq/commit/8b1b503609c161fea4b003a7179b3fbb2dd4345a", - "url": "https://api.github.com/repos/stedolan/jq/commits/8b1b503609c161fea4b003a7179b3fbb2dd4345a", - "sha": "8b1b503609c161fea4b003a7179b3fbb2dd4345a" - } - ], - "committer": { - "type": "User", - "received_events_url": "https://api.github.com/users/stedolan/received_events", - "events_url": "https://api.github.com/users/stedolan/events{/privacy}", - "repos_url": "https://api.github.com/users/stedolan/repos", - "organizations_url": "https://api.github.com/users/stedolan/orgs", + "committer": { + "name": "Stephen Dolan", + "email": "mu@netsoc.tcd.ie", + "date": "2013-06-22T16:30:59Z" + }, + "message": "Merge pull request #162 from stedolan/utf8-fixes\n\nUtf8 fixes. Closes #161", + "tree": { + "sha": "6ab697a8dfb5a96e124666bf6d6213822599fb40", + "url": "https://api.github.com/repos/stedolan/jq/git/trees/6ab697a8dfb5a96e124666bf6d6213822599fb40" + }, + "url": "https://api.github.com/repos/stedolan/jq/git/commits/d25341478381063d1c76e81b3a52e0592a7c997f", + "comment_count": 0 + }, + "url": "https://api.github.com/repos/stedolan/jq/commits/d25341478381063d1c76e81b3a52e0592a7c997f", + "html_url": "https://github.com/stedolan/jq/commit/d25341478381063d1c76e81b3a52e0592a7c997f", + "comments_url": "https://api.github.com/repos/stedolan/jq/commits/d25341478381063d1c76e81b3a52e0592a7c997f/comments", + "author": { + "login": "stedolan", ... - text: | - There's still far too much info for our purposes, so we can try - just grab the first commit: - + We can use jq to extract just the first commit. - command: "curl 'https://api.github.com/repos/stedolan/jq/commits?per_page=5' | jq '.[0]'" result: | { - "parents": [ - { - "html_url": "https://github.com/stedolan/jq/commit/54b9c9bdb225af5d886466d72f47eafc51acb4f7", - "url": "https://api.github.com/repos/stedolan/jq/commits/54b9c9bdb225af5d886466d72f47eafc51acb4f7", - "sha": "54b9c9bdb225af5d886466d72f47eafc51acb4f7" + "sha": "d25341478381063d1c76e81b3a52e0592a7c997f", + "commit": { + "author": { + "name": "Stephen Dolan", + "email": "mu@netsoc.tcd.ie", + "date": "2013-06-22T16:30:59Z" }, - { - "html_url": "https://github.com/stedolan/jq/commit/8b1b503609c161fea4b003a7179b3fbb2dd4345a", - "url": "https://api.github.com/repos/stedolan/jq/commits/8b1b503609c161fea4b003a7179b3fbb2dd4345a", - "sha": "8b1b503609c161fea4b003a7179b3fbb2dd4345a" - } - ], - "committer": { - "type": "User", - "received_events_url": "https://api.github.com/users/stedolan/received_events", - "events_url": "https://api.github.com/users/stedolan/events{/privacy}", - "repos_url": "https://api.github.com/users/stedolan/repos", - "organizations_url": "https://api.github.com/users/stedolan/orgs", - "subscriptions_url": "https://api.github.com/users/stedolan/subscriptions", - "starred_url": "https://api.github.com/users/stedolan/starred{/owner}{/repo}", - "gists_url": "https://api.github.com/users/stedolan/gists{/gist_id}", + "committer": { + "name": "Stephen Dolan", + "email": "mu@netsoc.tcd.ie", + "date": "2013-06-22T16:30:59Z" + }, + "message": "Merge pull request #162 from stedolan/utf8-fixes\n\nUtf8 fixes. Closes #161", + "tree": { + "sha": "6ab697a8dfb5a96e124666bf6d6213822599fb40", + "url": "https://api.github.com/repos/stedolan/jq/git/trees/6ab697a8dfb5a96e124666bf6d6213822599fb40" + }, + "url": "https://api.github.com/repos/stedolan/jq/git/commits/d25341478381063d1c76e81b3a52e0592a7c997f", + "comment_count": 0 + }, + "url": "https://api.github.com/repos/stedolan/jq/commits/d25341478381063d1c76e81b3a52e0592a7c997f", + "html_url": "https://github.com/stedolan/jq/commit/d25341478381063d1c76e81b3a52e0592a7c997f", + "comments_url": "https://api.github.com/repos/stedolan/jq/commits/d25341478381063d1c76e81b3a52e0592a7c997f/comments", + "author": { "login": "stedolan", "id": 79765, - "avatar_url": "https://1.gravatar.com/avatar/31de909d8e55dd07ed782d92ece59842?d=https%3A%2F%2Fidenticons.github.com%2Ffc5b6765b1c9cfaecea48ae71df4d279.png", - "gravatar_id": "31de909d8e55dd07ed782d92ece59842", + "avatar_url": "https://avatars.githubusercontent.com/u/79765?v=3", + "gravatar_id": "", "url": "https://api.github.com/users/stedolan", "html_url": "https://github.com/stedolan", "followers_url": "https://api.github.com/users/stedolan/followers", - "following_url": "https://api.github.com/users/stedolan/following{/other_user}" - }, - "author": { - "type": "User", - "received_events_url": "https://api.github.com/users/stedolan/received_events", - "events_url": "https://api.github.com/users/stedolan/events{/privacy}", - "repos_url": "https://api.github.com/users/stedolan/repos", - "organizations_url": "https://api.github.com/users/stedolan/orgs", - "subscriptions_url": "https://api.github.com/users/stedolan/subscriptions", - "starred_url": "https://api.github.com/users/stedolan/starred{/owner}{/repo}", + "following_url": "https://api.github.com/users/stedolan/following{/other_user}", "gists_url": "https://api.github.com/users/stedolan/gists{/gist_id}", + "starred_url": "https://api.github.com/users/stedolan/starred{/owner}{/repo}", + "subscriptions_url": "https://api.github.com/users/stedolan/subscriptions", + "organizations_url": "https://api.github.com/users/stedolan/orgs", + "repos_url": "https://api.github.com/users/stedolan/repos", + "events_url": "https://api.github.com/users/stedolan/events{/privacy}", + "received_events_url": "https://api.github.com/users/stedolan/received_events", + "type": "User", + "site_admin": false + }, + "committer": { "login": "stedolan", "id": 79765, - "avatar_url": "https://1.gravatar.com/avatar/31de909d8e55dd07ed782d92ece59842?d=https%3A%2F%2Fidenticons.github.com%2Ffc5b6765b1c9cfaecea48ae71df4d279.png", - "gravatar_id": "31de909d8e55dd07ed782d92ece59842", + "avatar_url": "https://avatars.githubusercontent.com/u/79765?v=3", + "gravatar_id": "", "url": "https://api.github.com/users/stedolan", "html_url": "https://github.com/stedolan", "followers_url": "https://api.github.com/users/stedolan/followers", - "following_url": "https://api.github.com/users/stedolan/following{/other_user}" + "following_url": "https://api.github.com/users/stedolan/following{/other_user}", + "gists_url": "https://api.github.com/users/stedolan/gists{/gist_id}", + "starred_url": "https://api.github.com/users/stedolan/starred{/owner}{/repo}", + "subscriptions_url": "https://api.github.com/users/stedolan/subscriptions", + "organizations_url": "https://api.github.com/users/stedolan/orgs", + "repos_url": "https://api.github.com/users/stedolan/repos", + "events_url": "https://api.github.com/users/stedolan/events{/privacy}", + "received_events_url": "https://api.github.com/users/stedolan/received_events", + "type": "User", + "site_admin": false }, - "comments_url": "https://api.github.com/repos/stedolan/jq/commits/d25341478381063d1c76e81b3a52e0592a7c997f/comments", - "html_url": "https://github.com/stedolan/jq/commit/d25341478381063d1c76e81b3a52e0592a7c997f", - "url": "https://api.github.com/repos/stedolan/jq/commits/d25341478381063d1c76e81b3a52e0592a7c997f", - "commit": { - "comment_count": 0, - "url": "https://api.github.com/repos/stedolan/jq/git/commits/d25341478381063d1c76e81b3a52e0592a7c997f", - "tree": { - "url": "https://api.github.com/repos/stedolan/jq/git/trees/6ab697a8dfb5a96e124666bf6d6213822599fb40", - "sha": "6ab697a8dfb5a96e124666bf6d6213822599fb40" - }, - "message": "Merge pull request #162 from stedolan/utf8-fixes\n\nUtf8 fixes. Closes #161", - "committer": { - "date": "2013-06-22T16:30:59Z", - "email": "mu@netsoc.tcd.ie", - "name": "Stephen Dolan" + "parents": [ + { + "sha": "54b9c9bdb225af5d886466d72f47eafc51acb4f7", + "url": "https://api.github.com/repos/stedolan/jq/commits/54b9c9bdb225af5d886466d72f47eafc51acb4f7", + "html_url": "https://github.com/stedolan/jq/commit/54b9c9bdb225af5d886466d72f47eafc51acb4f7" }, - "author": { - "date": "2013-06-22T16:30:59Z", - "email": "mu@netsoc.tcd.ie", - "name": "Stephen Dolan" + { + "sha": "8b1b503609c161fea4b003a7179b3fbb2dd4345a", + "url": "https://api.github.com/repos/stedolan/jq/commits/8b1b503609c161fea4b003a7179b3fbb2dd4345a", + "html_url": "https://github.com/stedolan/jq/commit/8b1b503609c161fea4b003a7179b3fbb2dd4345a" } - }, - "sha": "d25341478381063d1c76e81b3a52e0592a7c997f" + ] } - text: | - For the rest of the examples, I'll leave out the `curl` command - it's not going to change. - - There's still a lot of info we don't care about there, so we'll - restrict it down to the most interesting fields. + For the rest of the examples, I'll leave out the `curl` command - it's not + going to change. + There's a lot of info we don't care about there, so we'll restrict it down + to the most interesting fields. - command: "jq '.[0] | {message: .commit.message, name: .commit.committer.name}'" result: | { - "name": "Stephen Dolan", - "message": "Merge pull request #162 from stedolan/utf8-fixes\n\nUtf8 fixes. Closes #161" + "message": "Merge pull request #162 from stedolan/utf8-fixes\n\nUtf8 fixes. Closes #161", + "name": "Stephen Dolan" } - text: | - The `|` operator in jq feeds the output of one filter - (`.[0]` which gets the first element of the array in the response) - into the input of another (`{...}` which - builds an object out of those fields). You can access nested attributes, - such as `.commit.message`: - - Now let's get the rest of the commits: + The `|` operator in jq feeds the output of one filter (`.[0]` which gets + the first element of the array in the response) into the input of another + (`{...}` which builds an object out of those fields). You can access + nested attributes, such as `.commit.message`. + Now let's get the rest of the commits. - command: "jq '.[] | {message: .commit.message, name: .commit.committer.name}'" result: | { - "name": "Stephen Dolan", - "message": "Merge pull request #162 from stedolan/utf8-fixes\n\nUtf8 fixes. Closes #161" + "message": "Merge pull request #162 from stedolan/utf8-fixes\n\nUtf8 fixes. Closes #161", + "name": "Stephen Dolan" } { - "name": "Stephen Dolan", - "message": "Reject all overlong UTF8 sequences." + "message": "Reject all overlong UTF8 sequences.", + "name": "Stephen Dolan" } { - "name": "Stephen Dolan", - "message": "Fix various UTF8 parsing bugs.\n\nIn particular, parse bad UTF8 by replacing the broken bits with U+FFFD\nand resychronise correctly after broken sequences." + "message": "Fix various UTF8 parsing bugs.\n\nIn particular, parse bad UTF8 by replacing the broken bits with U+FFFD\nand resychronise correctly after broken sequences.", + "name": "Stephen Dolan" } { - "name": "Stephen Dolan", - "message": "Fix example in manual for `floor`. See #155." + "message": "Fix example in manual for `floor`. See #155.", + "name": "Stephen Dolan" } { - "name": "Nicolas Williams", - "message": "Document floor" + "message": "Document floor", + "name": "Nicolas Williams" } - text: | - `.[]` returns each element of the array returned in the response, - one at a time, which are all fed into `{message: .commit.message, name: .commit.committer.name}`. - + `.[]` returns each element of the array returned in the response, one at a + time, which are all fed into + `{message: .commit.message, name: .commit.committer.name}`. Data in jq is represented as streams of JSON values - every jq expression runs for each value in its input stream, and can @@ -219,26 +225,27 @@ body: result: | [ { - "name": "Stephen Dolan", - "message": "Merge pull request #162 from stedolan/utf8-fixes\n\nUtf8 fixes. Closes #161" + "message": "Merge pull request #163 from stedolan/utf8-fixes\n\nUtf8 fixes. Closes #161", + "name": "Stephen Dolan" }, { - "name": "Stephen Dolan", - "message": "Reject all overlong UTF8 sequences." + "message": "Reject all overlong UTF8 sequences.", + "name": "Stephen Dolan" }, { - "name": "Stephen Dolan", - "message": "Fix various UTF8 parsing bugs.\n\nIn particular, parse bad UTF8 by replacing the broken bits with U+FFFD\nand resychronise correctly after broken sequences." + "message": "Fix various UTF8 parsing bugs.\n\nIn particular, parse bad UTF8 by replacing the broken bits with U+FFFD\nand resychronise correctly after broken sequences.", + "name": "Stephen Dolan" }, { - "name": "Stephen Dolan", - "message": "Fix example in manual for `floor`. See #155." + "message": "Fix example in manual for `floor`. See #155.", + "name": "Stephen Dolan" }, { - "name": "Nicolas Williams", - "message": "Document floor" + "message": "Document floor", + "name": "Nicolas Williams" } ] + - text: | - - - @@ -249,14 +256,14 @@ body: "parents": [ { - "html_url": "https://github.com/stedolan/jq/commit/54b9c9bdb225af5d886466d72f47eafc51acb4f7", + "sha": "54b9c9bdb225af5d886466d72f47eafc51acb4f7", "url": "https://api.github.com/repos/stedolan/jq/commits/54b9c9bdb225af5d886466d72f47eafc51acb4f7", - "sha": "54b9c9bdb225af5d886466d72f47eafc51acb4f7" + "html_url": "https://github.com/stedolan/jq/commit/54b9c9bdb225af5d886466d72f47eafc51acb4f7" }, { - "html_url": "https://github.com/stedolan/jq/commit/8b1b503609c161fea4b003a7179b3fbb2dd4345a", + "sha": "8b1b503609c161fea4b003a7179b3fbb2dd4345a", "url": "https://api.github.com/repos/stedolan/jq/commits/8b1b503609c161fea4b003a7179b3fbb2dd4345a", - "sha": "8b1b503609c161fea4b003a7179b3fbb2dd4345a" + "html_url": "https://github.com/stedolan/jq/commit/8b1b503609c161fea4b003a7179b3fbb2dd4345a" } ] @@ -264,59 +271,57 @@ body: commits and make a simple list of strings to go along with the "message" and "author" fields we already have. - - - command: "jq '[.[] | {message: .commit.message, name: .commit.committer.name, parents: [.parents[].html_url]}]'" result: | [ { + "message": "Merge pull request #162 from stedolan/utf8-fixes\n\nUtf8 fixes. Closes #161", + "name": "Stephen Dolan", "parents": [ "https://github.com/stedolan/jq/commit/54b9c9bdb225af5d886466d72f47eafc51acb4f7", "https://github.com/stedolan/jq/commit/8b1b503609c161fea4b003a7179b3fbb2dd4345a" - ], - "name": "Stephen Dolan", - "message": "Merge pull request #162 from stedolan/utf8-fixes\n\nUtf8 fixes. Closes #161" + ] }, { + "message": "Reject all overlong UTF8 sequences.", + "name": "Stephen Dolan", "parents": [ "https://github.com/stedolan/jq/commit/ff48bd6ec538b01d1057be8e93b94eef6914e9ef" - ], - "name": "Stephen Dolan", - "message": "Reject all overlong UTF8 sequences." + ] }, { + "message": "Fix various UTF8 parsing bugs.\n\nIn particular, parse bad UTF8 by replacing the broken bits with U+FFFD\nand resychronise correctly after broken sequences.", + "name": "Stephen Dolan", "parents": [ "https://github.com/stedolan/jq/commit/54b9c9bdb225af5d886466d72f47eafc51acb4f7" - ], - "name": "Stephen Dolan", - "message": "Fix various UTF8 parsing bugs.\n\nIn particular, parse bad UTF8 by replacing the broken bits with U+FFFD\nand resychronise correctly after broken sequences." + ] }, { + "message": "Fix example in manual for `floor`. See #155.", + "name": "Stephen Dolan", "parents": [ "https://github.com/stedolan/jq/commit/3dcdc582ea993afea3f5503a78a77675967ecdfa" - ], - "name": "Stephen Dolan", - "message": "Fix example in manual for `floor`. See #155." + ] }, { + "message": "Document floor", + "name": "Nicolas Williams", "parents": [ "https://github.com/stedolan/jq/commit/7c4171d414f647ab08bcd20c76a4d8ed68d9c602" - ], - "name": "Nicolas Williams", - "message": "Document floor" + ] } ] - text: | Here we're making an object as before, but this time the `parents` - field is being set to `[.parents[].html_url]}]`, which collects + field is being set to `[.parents[].html_url]`, which collects all of the parent commit URLs defined in the parents object. - text: | - - - - Here endeth the tutorial! There's lots more to play with, go + Here endeth the tutorial! There's lots more to play with. Go read [the manual](../manual/) if you're interested, and [download jq](../download/) if you haven't already. -- 2.50.1