diff options
author | Nicolas Williams <nico@cryptonector.com> | 2017-02-14 23:37:35 -0600 |
---|---|---|
committer | Nicolas Williams <nico@cryptonector.com> | 2017-02-15 11:48:39 -0600 |
commit | 9b2179089b6f0bf78a870c0bfe2d96f1f127dd6c (patch) | |
tree | 7d2f27380a00f77349f80316bf46762ff1e05248 /docs | |
parent | 1c806b74eaeaa63802725b8329a68d83f73b551e (diff) |
Improve manual
Diffstat (limited to 'docs')
-rw-r--r-- | docs/content/3.manual/manual.yml | 169 |
1 files changed, 90 insertions, 79 deletions
diff --git a/docs/content/3.manual/manual.yml b/docs/content/3.manual/manual.yml index adeeb7cf..26a8d418 100644 --- a/docs/content/3.manual/manual.yml +++ b/docs/content/3.manual/manual.yml @@ -255,12 +255,12 @@ sections: - title: Basic filters entries: - - title: "`.`" + - title: "Identity: `.`" body: | - The absolute simplest (and least interesting) filter - is `.`. This is a filter that takes its input and - produces it unchanged as output. + The absolute simplest filter is `.` . This is a filter that + takes its input and produces it unchanged as output. That is, + this is the identity operator. Since jq by default pretty-prints all output, this trivial program can be a useful way of formatting JSON output from, @@ -271,17 +271,24 @@ sections: input: '"Hello, world!"' output: ['"Hello, world!"'] - - title: "`.foo`, `.foo.bar`" + - title: "Object Identifier-Index: `.foo`, `.foo.bar`" body: | The simplest *useful* filter is `.foo`. When given a JSON object (aka dictionary or hash) as input, it produces the value at the key "foo", or null if there's none present. + A filter of the form `.foo.bar` is equivalent to `.foo|.bar`. + + This syntax only works for simple, identifier-like keys, that + is, keys that are all made of alphanumeric characters and + underscore, and which do not start with a digit. + If the key contains special characters, you need to surround - it with double quotes like this: `."foo$"`. + it with double quotes like this: `."foo$"`, or else `.["foo$"]`. - A filter of the form `.foo.bar` is equivalent to `.foo|.bar`. + For example `.["foo::bar"]` and `.["foo.bar"]` work while + `.foo::bar` does not, and `.foo.bar` means `.["foo"].["bar"]`. examples: - program: '.foo' @@ -294,7 +301,7 @@ sections: input: '{"foo": 42}' output: [42] - - title: "`.foo?`" + - title: "Optional Object Identifier-Index: `.foo?`" body: | Just like `.foo`, but does not output even an error when `.` @@ -314,37 +321,22 @@ sections: input: '[1,2]' output: ['[]'] - - title: "`.[<string>]`, `.[2]`, `.[10:15]`" + - title: "Generic Object Index: `.[<string>]`" body: | You can also look up fields of an object using syntax like - `.["foo"]` (.foo above is a shorthand version of this). This - one works for arrays as well, if the key is an - integer. Arrays are zero-based (like javascript), so `.[2]` - returns the third element of the array. + `.["foo"]` (.foo above is a shorthand version of this, but + only for identifier-like strings). - The `.[10:15]` syntax can be used to return a subarray of an - array or substring of a string. The array returned by - `.[10:15]` will be of length 5, containing the elements from - index 10 (inclusive) to index 15 (exclusive). Either index may - be negative (in which case it counts backwards from the end of - the array), or omitted (in which case it refers to the start - or end of the array). + - title: "Array Index: `.[2]`" + body: | - The `.[2]` syntax can be used to return the element at the - given index. Negative indices are allowed, with -1 referring - to the last element, -2 referring to the next to last element, - and so on. + When the index value is an integer, `.[<value>]` can index + arrays. Arrays are zero-based, so `.[2]` returns the third + element. - The `.foo` syntax only works for simply keys i.e. keys that - are all alphanumeric characters. `.[<string>]` works with - keys that contain special characters such as colons and dots. - For example `.["foo::bar"]` and `.["foo.bar"]` work while - `.foo::bar` and `.foo.bar` would not. - - The `?` "operator" can also be used with the slice operator, - as in `.[10:15]?`, which outputs values where the inputs are - slice-able. + Negative indices are allowed, with -1 referring to the last + element, -2 referring to the next to last element, and so on. examples: - program: '.[0]' @@ -355,6 +347,22 @@ sections: input: '[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]' output: ['null'] + - program: '.[-2]' + input: '[1,2,3]' + output: ['2'] + + - title: "Array/String Slice: `.[10:15]`" + body: | + + The `.[10:15]` syntax can be used to return a subarray of an + array or substring of a string. The array returned by + `.[10:15]` will be of length 5, containing the elements from + index 10 (inclusive) to index 15 (exclusive). Either index may + be negative (in which case it counts backwards from the end of + the array), or omitted (in which case it refers to the start + or end of the array). + + examples: - program: '.[2:4]' input: '["a","b","c","d","e"]' output: ['["c", "d"]'] @@ -371,11 +379,7 @@ sections: input: '["a","b","c","d","e"]' output: ['["d", "e"]'] - - program: '.[-2]' - input: '[1,2,3]' - output: ['2'] - - - title: "`.[]`" + - title: "Array/Object Value Iterator: `.[]`" body: | If you use the `.[index]` syntax, but omit the index @@ -408,15 +412,16 @@ sections: Like `.[]`, but no errors will be output if . is not an array or object. - - title: "`,`" + - title: "Comma: `,`" body: | If two filters are separated by a comma, then the - input will be fed into both and there will be multiple - outputs: first, all of the outputs produced by the left - expression, and then all of the outputs produced by the - right. For instance, filter `.foo, .bar`, produces - both the "foo" fields and "bar" fields as separate outputs. + same input will be fed into both and the two filters' output + value streams will be concatenated in order: first, all of the + outputs produced by the left expression, and then all of the + outputs produced by the right. For instance, filter `.foo, + .bar`, produces both the "foo" fields and "bar" fields as + separate outputs. examples: - program: '.foo, .bar' @@ -431,7 +436,7 @@ sections: input: '["a","b","c","d","e"]' output: ['"e"', '"c"'] - - title: "`|`" + - title: "Pipe: `|`" body: | The | operator combines two filters by feeding the output(s) of @@ -481,7 +486,7 @@ sections: instead. entries: - - title: Array construction - `[]` + - title: "Array construction: `[]`" body: | As in JSON, `[]` is used to construct arrays, as in @@ -506,30 +511,33 @@ sections: - program: "[.user, .projects[]]" input: '{"user":"stedolan", "projects": ["jq", "wikiflow"]}' output: ['["stedolan", "jq", "wikiflow"]'] - - title: Objects - `{}` + - title: "Object Construction: `{}`" body: | Like JSON, `{}` is for constructing objects (aka dictionaries or hashes), as in: `{"a": 42, "b": 17}`. - If the keys are "sensible" (all alphabetic characters), then - the quotes can be left off. The value can be any expression - (although you may need to wrap it in parentheses if it's a - complicated one), which gets applied to the {} expression's - input (remember, all filters have an input and an - output). + If the keys are "identifier-like", then the quotes can be left + off, as in `{a:42, b:17}. Keys generated by expressions need + to be parenthesized, e.g., `{("a"+"b"):59}`. + + The value can be any expression (although you may need to + wrap it in parentheses if it's a complicated one), which gets + applied to the {} expression's input (remember, all filters + have an input and an output). {foo: .bar} will produce the JSON object `{"foo": 42}` if given the JSON - object `{"bar":42, "baz":43}`. You can use this to select - particular fields of an object: if the input is an object - with "user", "title", "id", and "content" fields and you - just want "user" and "title", you can write + object `{"bar":42, "baz":43}` as its input. You can use this + to select particular fields of an object: if the input is an + object with "user", "title", "id", and "content" fields and + you just want "user" and "title", you can write {user: .user, title: .title} - Because that's so common, there's a shortcut syntax: `{user, title}`. + Because that is so common, there's a shortcut syntax for it: + `{user, title}`. If one of the expressions produces multiple results, multiple dictionaries will be produced. If the input's @@ -564,6 +572,24 @@ sections: input: '{"user":"stedolan","titles":["JQ Primer", "More JQ"]}' output: ['{"stedolan": ["JQ Primer", "More JQ"]}'] + - title: "Recursive Descent: `..`" + body: | + + Recursively descends `.`, producing every value. This is the + same as the zero-argument `recurse` builtin (see below). This + is intended to resemble the XPath `//` operator. Note that + `..a` does not work; use `..|.a` instead. In the example + below we use `..|.a?` to find all the values of object keys + "a" in any object found "below" `.`. + + This is particularly useful in conjunction with `path(EXP)` + (also see below) and the `?` operator. + + examples: + - program: '..|.a?' + input: '[[{"a":1}]]' + output: ['1'] + - title: Builtin operators and functions body: | @@ -574,7 +600,7 @@ sections: no result. entries: - - title: Addition - `+` + - title: "Addition: `+`" body: | The operator `+` takes two filters, applies them both @@ -613,7 +639,7 @@ sections: input: 'null' output: ['{"a": 42, "b": 2, "c": 3}'] - - title: Subtraction - `-` + - title: "Subtraction: `-`" body: | As well as normal arithmetic subtraction on numbers, the `-` @@ -628,7 +654,7 @@ sections: input: '["xml", "yaml", "json"]' output: ['["json"]'] - - title: Multiplication, division, modulo - `*`, `/`, and `%` + - title: "Multiplication, division, modulo: `*`, `/`, and `%`" body: | These infix operators behave as expected when given two numbers. @@ -1627,21 +1653,6 @@ sections: output: - '[{"a":{"b":2}}]' - - - title: "`..`" - body: | - - Short-hand for `recurse` without arguments. This is intended - to resemble the XPath `//` operator. Note that `..a` does not - work; use `..|a` instead. In the example below we use - `..|.a?` to find all the values of object keys "a" in any - object found "below" `.`. - - examples: - - program: '..|.a?' - input: '[[{"a":1}]]' - output: ['1'] - - title: "`env`" body: | @@ -2033,7 +2044,7 @@ sections: input: 'null' output: ['[false, true]'] - - title: Alternative operator - `//` + - title: "Alternative operator: `//`" body: | A filter of the form `a // b` produces the same @@ -2110,7 +2121,7 @@ sections: because no label `$out` is visible. - - title: "`?` operator" + - title: "Error Suppresion / Optional Operator: `?`" body: | The `?` operator, used as `EXP?`, is shorthand for `try EXP`. @@ -2333,7 +2344,7 @@ sections: Finally, there is a module/library system. entries: - - title: Variables + - title: "Variable / Symbolic Binding Operator: `... as $identifier | ...`" body: | In jq, all filters have an input and an output, so manual |