diff options
Diffstat (limited to 'docs/content/manual/v1.5/manual.yml')
| -rw-r--r-- | docs/content/manual/v1.5/manual.yml | 110 |
1 files changed, 52 insertions, 58 deletions
diff --git a/docs/content/manual/v1.5/manual.yml b/docs/content/manual/v1.5/manual.yml index 2ef584af..64bee206 100644 --- a/docs/content/manual/v1.5/manual.yml +++ b/docs/content/manual/v1.5/manual.yml @@ -107,7 +107,7 @@ sections: output and an ASCII LF (line feed) is printed after every output. Input JSON texts that fail to parse are ignored (but warned about), discarding all subsequent input until the next - RS. This more also parses the output of jq without the `--seq` + RS. This mode also parses the output of jq without the `--seq` option. * `--stream`: @@ -115,7 +115,7 @@ sections: Parse the input in streaming fashion, outputting arrays of path and leaf values (scalars and empty arrays or empty objects). For example, `"a"` becomes `[[],"a"]`, and `[[],"a",["b"]]` - becomes `[[0],[]]`, `[[1],"a"]`, and `[[1,0],"b"]`. + becomes `[[0],[]]`, `[[1],"a"]`, and `[[2,0],"b"]`. This is useful for processing very large inputs. Use this in conjunction with filtering and the `reduce` and `foreach` syntax @@ -168,7 +168,7 @@ sections: ASCII output with every non-ASCII character replaced with the equivalent escape sequence. - * `--unbuffered` + * `--unbuffered`: Flush the output after each JSON object is printed (useful if you're piping a slow data source into jq and piping jq's @@ -202,7 +202,7 @@ sections: * `-e` / `--exit-status`: - Sets the exit status of jq to 0 if the last output values was + Sets the exit status of jq to 0 if the last output value was neither `false` nor `null`, 1 if the last output value was either `false` or `null`, or 4 if no valid result was ever produced. Normally jq exits with 2 if there was any usage @@ -314,11 +314,11 @@ sections: input: '[1,2]' output: ['[]'] - - title: "`.[<string>]`, `.[2]`, `.[10:15]`" + - title: "`.[<string>]`, `.[<number>]`, `.[<number>:<number>]`" body: | You can also look up fields of an object using syntax like - `.["foo"]` (.foo above is a shorthand version of this). This + `.["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. @@ -462,7 +462,7 @@ sections: instead. entries: - - title: Array construction - `[]` + - title: "Array construction: `[]`" body: | As in JSON, `[]` is used to construct arrays, as in @@ -487,7 +487,7 @@ sections: - program: "[.user, .projects[]]" input: '{"user":"stedolan", "projects": ["jq", "wikiflow"]}' output: ['["stedolan", "jq", "wikiflow"]'] - - title: Objects - `{}` + - title: "Objects: `{}`" body: | Like JSON, `{}` is for constructing objects (aka @@ -548,14 +548,14 @@ sections: - title: Builtin operators and functions body: | - Some jq operator (for instance, `+`) do different things + Some jq operators (for instance, `+`) do different things depending on the type of their arguments (arrays, numbers, etc.). However, jq never does implicit type conversions. If you try to add a string to an object you'll get an error message and no result. entries: - - title: Addition - `+` + - title: "Addition: `+`" body: | The operator `+` takes two filters, applies them both @@ -594,7 +594,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 `-` @@ -609,7 +609,7 @@ sections: input: '["xml", "yaml", "json"]' output: ['["json"]'] - - title: Multiplication, division, modulo - `*`, `/`, and `%` + - title: "Multiplication, division, modulo: `*`, `/`, `%`" body: | These infix operators behave as expected when given two numbers. @@ -770,7 +770,7 @@ sections: input: '["foo", "bar", "baz"]' output: ['["foo"]'] - - title: "`to_entries`, `from_entries`, `with_entries`" + - title: "`to_entries`, `from_entries`, `with_entries(f)`" body: | These functions convert between an object and an array of @@ -779,10 +779,10 @@ sections: includes `{"key": k, "value": v}`. `from_entries` does the opposite conversion, and - `with_entries(foo)` is a shorthand for `to_entries | - map(foo) | from_entries`, useful for doing some operation to - all keys and values of an object. `from_entries` accepts key, Key, - Name, value and Value as keys. + `with_entries(f)` is a shorthand for `to_entries | map(f) | + from_entries`, useful for doing some operation to all keys + and values of an object. `from_entries` accepts `"key"`, + `"Key"`, `"Name"`, `"value"`, and `"Value"` as keys. examples: - program: 'to_entries' @@ -799,8 +799,8 @@ sections: - title: "`select(boolean_expression)`" body: | - The function `select(foo)` produces its input unchanged if - `foo` returns true for that input, and produces no output + The function `select(f)` produces its input unchanged if + `f` returns true for that input, and produces no output otherwise. It's useful for filtering lists: `[1,2,3] | map(select(. >= 2))` @@ -862,18 +862,18 @@ sections: input: 'null' output: ['"{\"file\":\"<top-level>\",\"line\":1}"'] - - title: "`map(x)`, `map_values(x)`" + - title: "`map(f)`, `map_values(f)`" body: | - For any filter `x`, `map(x)` will run that filter for each + For any filter `f`, `map(f)` will run that filter for each element of the input array, and return the outputs in a new array. `map(.+1)` will increment each element of an array of numbers. - Similarly, `map_values(x)` will run that filter for each element, + Similarly, `map_values(f)` will run that filter for each element, but it will return an object when an object is passed. - `map(x)` is equivalent to `[.[] | x]`. In fact, this is how - it's defined. Similarly, `map_values(x)` is defined as `.[] |= x`. + `map(f)` is equivalent to `[.[] | f]`. In fact, this is how + it's defined. Similarly, `map_values(f)` is defined as `.[] |= f`. examples: - program: 'map(.+1)' @@ -1005,12 +1005,12 @@ sections: input: '[{"foo": "bar"}, [{"foo": "baz"}]]' output: ['[{"foo": "bar"}, {"foo": "baz"}]'] - - title: "`range(upto)`, `range(from;upto)` `range(from;upto;by)`" + - title: "`range(upto)`, `range(from; upto)` `range(from; upto; by)`" body: | - The `range` function produces a range of numbers. `range(4;10)` + The `range` function produces a range of numbers. `range(4; 10)` produces 6 numbers, from 4 (inclusive) to 10 (exclusive). The numbers - are produced as separate outputs. Use `[range(4;10)]` to get a range as + are produced as separate outputs. Use `[range(4; 10)]` to get a range as an array. The one argument form generates numbers from 0 to the given @@ -1023,22 +1023,22 @@ sections: with an increment of `by`. examples: - - program: 'range(2;4)' + - program: 'range(2; 4)' input: 'null' output: ['2', '3'] - - program: '[range(2;4)]' + - program: '[range(2; 4)]' input: 'null' output: ['[2,3]'] - program: '[range(4)]' input: 'null' output: ['[0,1,2,3]'] - - program: '[range(0;10;3)]' + - program: '[range(0; 10; 3)]' input: 'null' output: ['[0,3,6,9]'] - - program: '[range(0;10;-1)]' + - program: '[range(0; 10; -1)]' input: 'null' output: ['[]'] - - program: '[range(0;-5;-1)]' + - program: '[range(0; -5; -1)]' input: 'null' output: ['[0,-1,-2,-3,-4]'] @@ -1122,7 +1122,7 @@ sections: input: 'null' output: ['"number"', '"number"'] - - title: "`sort, sort_by(path_expression)`" + - title: "`sort`, `sort_by(path_expression)`" body: | The `sort` functions sorts its input, which must be an @@ -1144,8 +1144,8 @@ sections: `sort` may be used to sort by a particular field of an object, or by applying any jq filter. - `sort_by(foo)` compares two elements by comparing the result of - `foo` on each element. + `sort_by(f)` compares two elements by comparing the result of + `f` on each element. examples: - program: 'sort' @@ -1560,13 +1560,13 @@ sections: - title: "`bsearch(x)`" body: | - bsearch(x) conducts a binary search for x in the input + `bsearch(x)` conducts a binary search for x in the input array. If the input is sorted and contains x, then - bsearch(x) will return its index in the array; otherwise, if + `bsearch(x)` will return its index in the array; otherwise, if the array is sorted, it will return (-1 - ix) where ix is an insertion point such that the array would still be sorted after the insertion of x at ix. If the array is not sorted, - bsearch(x) will return an integer that is probably of no + `bsearch(x)` will return an integer that is probably of no interest. examples: @@ -1580,7 +1580,7 @@ sections: input: '[1,2,3]' output: ['[1,2,3,4]'] - - title: "String interpolation - `\\(foo)`" + - title: "String interpolation: `\\(exp)`" body: | Inside a string, you can put an expression inside parens @@ -1685,10 +1685,6 @@ sections: input: '"This works if x < y"' output: ['"This works if x < y"'] -# - program: '@html "<span>Anonymous said: \(.)</span>"' -# input: '"<script>alert(\"lol hax\");</script>"' -# output: ["<span>Anonymous said: <script>alert("lol hax");</script></span>"] - - program: '@sh "echo \(.)"' input: "\"O'Hara's Ale\"" output: ["\"echo 'O'\\\\''Hara'\\\\''s Ale'\""] @@ -1779,7 +1775,7 @@ sections: input: '[1, 1.0, "1", "banana"]' output: ['true', 'true', 'false', 'false'] - - title: if-then-else + - title: if-then-else-end body: | `if A then B else C end` will act the same as `B` if `A` @@ -1812,7 +1808,7 @@ sections: input: 2 output: ['"many"'] - - title: "`>, >=, <=, <`" + - title: "`>`, `>=`, `<=`, `<`" body: | The comparison operators `>`, `>=`, `<=`, `<` return whether @@ -1827,12 +1823,13 @@ sections: input: 2 output: ['true'] - - title: and/or/not + - title: "`and`, `or`, `not`" body: | - jq supports the normal Boolean operators and/or/not. They have the - same standard of truth as if expressions - false and null are - considered "false values", and anything else is a "true value". + jq supports the normal Boolean operators `and`, `or`, `not`. + They have the same standard of truth as if expressions - + `false` and `null` are considered "false values", and + anything else is a "true value". If an operand of one of these operators produces multiple results, the operator itself will produce a result for each input. @@ -1842,12 +1839,12 @@ sections: rather than with special syntax, as in `.foo and .bar | not`. - These three only produce the values "true" and "false", and + These three only produce the values `true` and `false`, and so are only useful for genuine Boolean operations, rather than the common Perl/Python/Ruby idiom of "value_that_may_be_null or default". If you want to use this form of "or", picking between two values rather than - evaluating a condition, see the "//" operator below. + evaluating a condition, see the `//` operator below. examples: - program: '42 and "a string"' @@ -1856,9 +1853,6 @@ sections: - program: '(true, false) or false' input: 'null' output: ['true', 'false'] -# - program: '(true, false) and (true, false)' -# input: 'null' -# output: ['true', 'false', 'false', 'false'] - program: '(true, true) and (true, false)' input: 'null' output: ['true', 'false', 'true', 'false'] @@ -1866,7 +1860,7 @@ sections: input: 'null' output: ['[false, true]'] - - title: Alternative operator - `//` + - title: "Alternative operator: `//`" body: | A filter of the form `a // b` produces the same @@ -2200,7 +2194,7 @@ sections: fields, and another object which is used to map author usernames to real names. Our input looks like: - {"posts": [{"title": "Frist psot", "author": "anon"}, + {"posts": [{"title": "First post", "author": "anon"}, {"title": "A well-written article", "author": "person1"}], "realnames": {"anon": "Anonymous Coward", "person1": "Person McPherson"}} @@ -2208,7 +2202,7 @@ sections: We want to produce the posts with the author field containing a real name, as in: - {"title": "Frist psot", "author": "Anonymous Coward"} + {"title": "First post", "author": "Anonymous Coward"} {"title": "A well-written article", "author": "Person McPherson"} We use a variable, $names, to store the realnames object, so that we @@ -2222,7 +2216,7 @@ sections: foreach loop. Just as `{foo}` is a handy way of writing `{foo: .foo}`, so - `{$foo}` is a handy way of writing `{foo:$foo}`. + `{$foo}` is a handy way of writing `{foo: $foo}`. Multiple variables may be declared using a single `as` expression by providing a pattern that matches the structure of the input |