From 6864aa8630237836f31c99a2bc47ca99fdec3f56 Mon Sep 17 00:00:00 2001 From: itchyny Date: Thu, 22 Jun 2023 08:31:38 +0900 Subject: Fix manual section titles, minor typos, and improve inline codes (#2626) --- docs/content/manual/manual.yml | 153 ++++++++++++++------------- docs/content/manual/v1.3/manual.yml | 63 ++++++------ docs/content/manual/v1.4/manual.yml | 69 ++++++------- docs/content/manual/v1.5/manual.yml | 110 ++++++++++---------- docs/content/manual/v1.6/manual.yml | 199 +++++++++++++++++------------------- 5 files changed, 283 insertions(+), 311 deletions(-) diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml index 454c05ce..68cc091f 100644 --- a/docs/content/manual/manual.yml +++ b/docs/content/manual/manual.yml @@ -97,9 +97,9 @@ sections: program and backslash-escaped double-quotes (`\"`) inside the jq program. - Unix shells: `jq '.["foo"]'` - Powershell: `jq '.[\"foo\"]'` - Windows command shell: `jq ".[\"foo\"]"` + * Unix shells: `jq '.["foo"]'` + * Powershell: `jq '.[\"foo\"]'` + * Windows command shell: `jq ".[\"foo\"]"` You can affect how jq reads and writes its input and output using some command-line options: @@ -284,7 +284,7 @@ sections: Remaining arguments are positional JSON text arguments. These are available to the jq program as `$ARGS.positional[]`. - + * `--`: Terminates argument processing. Remaining arguments are @@ -318,19 +318,19 @@ sections: program can be a useful way of formatting JSON output from, say, `curl`. - An important point about the identity filter is that it - guarantees to preserve the literal decimal representation - of values. This is particularly important when dealing with numbers - which can't be losslessly converted to an IEEE754 double precision + An important point about the identity filter is that it + guarantees to preserve the literal decimal representation + of values. This is particularly important when dealing with numbers + which can't be losslessly converted to an IEEE754 double precision representation. jq doesn't truncate the literal numbers to double unless there is a need to make arithmetic operations with the number. - Comparisons are carried out over the untruncated big decimal + Comparisons are carried out over the untruncated big decimal representation of the number. jq will also try to maintain the original decimal precision of the provided - number literal. See below for examples. + number literal. See below for examples. examples: - program: '.' @@ -400,17 +400,17 @@ sections: input: '[1,2]' output: ['[]'] - - title: "Generic Object Index: `.[]`" + - title: "Object Index: `.[]`" body: | You can also look up fields of an object using syntax like - `.["foo"]` (.foo above is a shorthand version of this, but + `.["foo"]` (`.foo` above is a shorthand version of this, but only for identifier-like strings). - - title: "Array Index: `.[2]`" + - title: "Array Index: `.[]`" body: | - When the index value is an integer, `.[]` can index + When the index value is an integer, `.[]` can index arrays. Arrays are zero-based, so `.[2]` returns the third element. @@ -430,16 +430,16 @@ sections: input: '[1,2,3]' output: ['2'] - - title: "Array/String Slice: `.[10:15]`" + - title: "Array/String Slice: `.[:]`" 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). + The `.[:]` 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]' @@ -564,15 +564,15 @@ sections: expression that takes an input, ignores it, and returns 42 instead. - Numbers in jq are internally represented by their IEEE754 double - precision approximation. Any arithmetic operation with numbers, - whether they are literals or results of previous filters, will + Numbers in jq are internally represented by their IEEE754 double + precision approximation. Any arithmetic operation with numbers, + whether they are literals or results of previous filters, will produce a double precision floating point result. However, when parsing a literal jq will store the original literal string. If no mutation is applied to this value then it will make - to the output in its original form, even if conversion to double - would result in a loss. + to the output in its original form, even if conversion to double + would result in a loss. entries: - title: "Array construction: `[]`" @@ -699,21 +699,21 @@ 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. - Please note that all numbers are converted to IEEE754 double precision + Please note that all numbers are converted to IEEE754 double precision floating point representation. Arithmetic and logical operators are working - with these converted doubles. Results of all such operations are also limited - to the double precision. + with these converted doubles. Results of all such operations are also limited + to the double precision. - The only exception to this behaviour of number is a snapshot of original number + The only exception to this behaviour of number is a snapshot of original number literal. When a number which originally was provided as a literal is never - mutated until the end of the program then it is printed to the output in its - original literal form. This also includes cases when the original literal + mutated until the end of the program then it is printed to the output in its + original literal form. This also includes cases when the original literal would be truncated when converted to the IEEE754 double precision floating point number. @@ -772,7 +772,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. @@ -903,18 +903,18 @@ sections: input: '[2, 0]' output: ['[false, true]'] - - 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)' @@ -1013,7 +1013,7 @@ sections: input: '{"a":{"b":1},"x":{"y":2}}' output: ['{"a":{},"x":{"y":2}}'] - - 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 @@ -1021,11 +1021,11 @@ sections: for each `k: v` entry in the input, the output array 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, Name, value and Value as keys. + `from_entries` does the opposite conversion, and `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"`, `"Name"`, + `"value"`, and `"Value"` as keys. examples: - program: 'to_entries' @@ -1042,8 +1042,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))` @@ -1244,12 +1244,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 @@ -1262,22 +1262,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]'] @@ -1383,8 +1383,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' @@ -1866,7 +1866,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 @@ -1976,10 +1976,6 @@ sections: input: '"This works if x < y"' output: ['"This works if x < y"'] -# - program: '@html "Anonymous said: \(.)"' -# input: '""' -# output: ["Anonymous said: <script>alert("lol hax");</script>"] - - program: '@sh "echo \(.)"' input: "\"O'Hara's Ale\"" output: ["\"echo 'O'\\\\''Hara'\\\\''s Ale'\""] @@ -2134,7 +2130,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` @@ -2159,17 +2155,18 @@ sections: More cases can be added to an if using `elif A then B` syntax. examples: - - program: 'if . == 0 then + - program: |- + if . == 0 then "zero" elif . == 1 then "one" else "many" - end' + end input: 2 output: ['"many"'] - - title: "`>, >=, <=, <`" + - title: "`>`, `>=`, `<=`, `<`" body: | The comparison operators `>`, `>=`, `<=`, `<` return whether @@ -2184,12 +2181,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. @@ -2199,12 +2197,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"' @@ -2213,9 +2211,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'] @@ -2568,7 +2563,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"}} @@ -2576,7 +2571,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 @@ -2590,7 +2585,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 diff --git a/docs/content/manual/v1.3/manual.yml b/docs/content/manual/v1.3/manual.yml index 95c759d4..34ddcf72 100644 --- a/docs/content/manual/v1.3/manual.yml +++ b/docs/content/manual/v1.3/manual.yml @@ -171,7 +171,7 @@ sections: 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. @@ -285,7 +285,7 @@ sections: instead. entries: - - title: Array construction - `[]` + - title: "Array construction: `[]`" body: | As in JSON, `[]` is used to construct arrays, as in @@ -310,7 +310,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 @@ -371,14 +371,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 @@ -416,7 +416,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 `-` @@ -431,7 +431,7 @@ sections: input: '["xml", "yaml", "json"]' output: ['["json"]'] - - title: Multiplication, division - `*` and `/` + - title: "Multiplication, division: `*` and `/`" body: | These operators only work on numbers, and do the expected. @@ -504,7 +504,7 @@ sections: input: '[[0,1], ["a","b","c"]]' output: ['[false, true]'] - - 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 @@ -513,9 +513,9 @@ 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. + `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. examples: - program: 'to_entries' @@ -559,14 +559,14 @@ sections: input: 'null' output: ['[1,2,3]'] - - title: '`map(x)`' + - title: '`map(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 produce the outputs a new array. `map(.+1)` will increment each element of an array of numbers. - `map(x)` is equivalent to `[.[] | x]`. In fact, this is how + `map(f)` is equivalent to `[.[] | f]`. In fact, this is how it's defined. examples: @@ -648,7 +648,7 @@ sections: input: '[0, false, [], {}, null, "hello"]' output: ['["number", "boolean", "array", "object", "null", "string"]'] - - title: '`sort, sort_by`' + - title: '`sort`, `sort_by`' body: | The `sort` functions sorts its input, which must be an @@ -796,7 +796,7 @@ sections: - '{"foo":[]}' - - title: String interpolation - `\(foo)` + - title: "String interpolation: `\\(exp)`" body: | Inside a string, you can put an expression inside parens @@ -872,10 +872,6 @@ sections: input: '"This works if x < y"' output: ['"This works if x < y"'] -# - program: '@html "Anonymous said: \(.)"' -# input: '""' -# output: ["Anonymous said: <script>alert("lol hax");</script>"] - - program: '@sh "echo \(.)"' input: "\"O'Hara's Ale\"" output: ["\"echo 'O'\\\\''Hara'\\\\''s Ale'\""] @@ -898,7 +894,8 @@ sections: - program: '.[] == 1' 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` @@ -931,7 +928,7 @@ sections: input: 2 output: ['"many"'] - - title: '`>, >=, <=, <`' + - title: "`>`, `>=`, `<=`, `<`" body: | The comparison operators `>`, `>=`, `<=`, `<` return whether @@ -946,12 +943,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. @@ -961,12 +959,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"' @@ -975,9 +973,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'] @@ -985,7 +980,7 @@ sections: input: 'null' output: ['[false, true]'] - - title: Alternative operator - `//` + - title: "Alternative operator: `//`" body: | A filter of the form `a // b` produces the same @@ -1061,7 +1056,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"}} @@ -1069,7 +1064,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 diff --git a/docs/content/manual/v1.4/manual.yml b/docs/content/manual/v1.4/manual.yml index a8923e11..b51b3b1a 100644 --- a/docs/content/manual/v1.4/manual.yml +++ b/docs/content/manual/v1.4/manual.yml @@ -142,7 +142,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 @@ -166,7 +166,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 @@ -248,11 +248,11 @@ sections: input: '[1,2]' output: ['[]'] - - title: "`.[]`, `.[2]`, `.[10:15]`" + - title: "`.[]`, `.[]`, `.[:]`" 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. @@ -381,7 +381,7 @@ sections: instead. entries: - - title: Array construction - `[]` + - title: "Array construction: `[]`" body: | As in JSON, `[]` is used to construct arrays, as in @@ -406,7 +406,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 @@ -467,14 +467,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 @@ -513,7 +513,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 `-` @@ -528,7 +528,7 @@ sections: input: '["xml", "yaml", "json"]' output: ['["json"]'] - - title: Multiplication, division, modulo - `*`, `/`, and `%` + - title: "Multiplication, division, modulo: `*`, `/`, `%`" body: | These operators only work on numbers, and do the expected. @@ -632,7 +632,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 @@ -641,9 +641,9 @@ 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. + `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. examples: - program: 'to_entries' @@ -700,14 +700,14 @@ sections: input: 'null' output: ['[1,2,3]'] - - title: "`map(x)`" + - title: "`map(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 produce the outputs a new array. `map(.+1)` will increment each element of an array of numbers. - `map(x)` is equivalent to `[.[] | x]`. In fact, this is how + `map(f)` is equivalent to `[.[] | f]`. In fact, this is how it's defined. examples: @@ -875,7 +875,7 @@ sections: input: '[0, false, [], {}, null, "hello"]' output: ['["number", "boolean", "array", "object", "null", "string"]'] - - title: "`sort, sort_by`" + - title: "`sort`, `sort_by`" body: | The `sort` functions sorts its input, which must be an @@ -1179,7 +1179,7 @@ sections: input: '[[{"a":1}]]' output: ['1'] - - title: "String interpolation - `\\(foo)`" + - title: "String interpolation: `\\(exp)`" body: | Inside a string, you can put an expression inside parens @@ -1274,10 +1274,6 @@ sections: input: '"This works if x < y"' output: ['"This works if x < y"'] -# - program: '@html "Anonymous said: \(.)"' -# input: '""' -# output: ["Anonymous said: <script>alert("lol hax");</script>"] - - program: '@sh "echo \(.)"' input: "\"O'Hara's Ale\"" output: ["\"echo 'O'\\\\''Hara'\\\\''s Ale'\""] @@ -1300,7 +1296,8 @@ sections: - program: '.[] == 1' 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` @@ -1333,7 +1330,7 @@ sections: input: 2 output: ['"many"'] - - title: "`>, >=, <=, <`" + - title: "`>`, `>=`, `<=`, `<`" body: | The comparison operators `>`, `>=`, `<=`, `<` return whether @@ -1348,12 +1345,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. @@ -1363,12 +1361,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"' @@ -1377,9 +1375,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'] @@ -1387,7 +1382,7 @@ sections: input: 'null' output: ['[false, true]'] - - title: Alternative operator - `//` + - title: "Alternative operator: `//`" body: | A filter of the form `a // b` produces the same @@ -1463,7 +1458,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"}} @@ -1471,7 +1466,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 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: "`.[]`, `.[2]`, `.[10:15]`" + - title: "`.[]`, `.[]`, `.[:]`" 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\":\"\",\"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 "Anonymous said: \(.)"' -# input: '""' -# output: ["Anonymous said: <script>alert("lol hax");</script>"] - - 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 diff --git a/docs/content/manual/v1.6/manual.yml b/docs/content/manual/v1.6/manual.yml index 4e75bf5d..09ced514 100644 --- a/docs/content/manual/v1.6/manual.yml +++ b/docs/content/manual/v1.6/manual.yml @@ -95,10 +95,10 @@ sections: (`pwsh`/`pwsh.exe`), use single-quote characters around the jq program and backslash-escaped double-quotes (`\"`) inside the jq program. - - Unix shells: `jq '.["foo"]'` - Powershell: `jq '.[\"foo\"]'` - Windows command shell: `jq ".[\"foo\"]"` + + * Unix shells: `jq '.["foo"]'` + * Powershell: `jq '.[\"foo\"]'` + * Windows command shell: `jq ".[\"foo\"]"` You can affect how jq reads and writes its input and output using some command-line options: @@ -123,7 +123,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 @@ -179,7 +179,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 @@ -213,7 +213,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 @@ -357,17 +357,17 @@ sections: input: '[1,2]' output: ['[]'] - - title: "Generic Object Index: `.[]`" + - title: "Object Index: `.[]`" body: | You can also look up fields of an object using syntax like - `.["foo"]` (.foo above is a shorthand version of this, but + `.["foo"]` (`.foo` above is a shorthand version of this, but only for identifier-like strings). - - title: "Array Index: `.[2]`" + - title: "Array Index: `.[]`" body: | - When the index value is an integer, `.[]` can index + When the index value is an integer, `.[]` can index arrays. Arrays are zero-based, so `.[2]` returns the third element. @@ -387,16 +387,16 @@ sections: input: '[1,2,3]' output: ['2'] - - title: "Array/String Slice: `.[10:15]`" + - title: "Array/String Slice: `.[:]`" 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). + The `.[:]` 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]' @@ -654,10 +654,10 @@ sections: - **Strings** are added by being joined into a larger string. - **Objects** are added by merging, that is, inserting all - the key-value pairs from both objects into a single - combined object. If both objects contain a value for the - same key, the object on the right of the `+` wins. (For - recursive merge use the `*` operator.) + the key-value pairs from both objects into a single + combined object. If both objects contain a value for the + same key, the object on the right of the `+` wins. (For + recursive merge use the `*` operator.) `null` can be added to any value, and returns the other value unchanged. @@ -694,7 +694,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. @@ -825,18 +825,18 @@ sections: input: '[2, 0]' output: ['[false, true]'] - - 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)' @@ -935,7 +935,7 @@ sections: input: '{"a":{"b":1},"x":{"y":2}}' output: ['{"a":{},"x":{"y":2}}'] - - 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 @@ -943,11 +943,11 @@ sections: for each `k: v` entry in the input, the output array 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, Name, value and Value as keys. + `from_entries` does the opposite conversion, and `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"`, `"Name"`, + `"value"`, and `"Value"` as keys. examples: - program: 'to_entries' @@ -964,8 +964,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))` @@ -1166,12 +1166,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 @@ -1184,22 +1184,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]'] @@ -1283,7 +1283,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 @@ -1305,8 +1305,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' @@ -1387,7 +1387,7 @@ sections: body: | The filter `contains(b)` will produce true if b is - completely contained within the input. String B is + completely contained within the input. A string B is contained in a string A if B is a substring of A. An array B is contained in an array A if all elements in B are contained in any element in A. An object B is contained in @@ -1749,13 +1749,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: @@ -1769,7 +1769,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 @@ -1785,9 +1785,9 @@ sections: body: | The `tojson` and `fromjson` builtins dump values as JSON texts - or parse JSON texts into values, respectively. The tojson - builtin differs from tostring in that tostring returns strings - unmodified, while tojson encodes strings as JSON strings. + or parse JSON texts into values, respectively. The `tojson` + builtin differs from `tostring` in that `tostring` returns strings + unmodified, while `tojson` encodes strings as JSON strings. examples: - program: '[.[]|tostring]' @@ -1879,10 +1879,6 @@ sections: input: '"This works if x < y"' output: ['"This works if x < y"'] -# - program: '@html "Anonymous said: \(.)"' -# input: '""' -# output: ["Anonymous said: <script>alert("lol hax");</script>"] - - program: '@sh "echo \(.)"' input: "\"O'Hara's Ale\"" output: ["\"echo 'O'\\\\''Hara'\\\\''s Ale'\""] @@ -1975,40 +1971,40 @@ sections: jq provides a few SQL-style operators. - * INDEX(stream; index_expression): + * INDEX(stream; index_expression): - This builtin produces an object whose keys are computed by - the given index expression applied to each value from the - given stream. + This builtin produces an object whose keys are computed by + the given index expression applied to each value from the + given stream. - * JOIN($idx; stream; idx_expr; join_expr): + * JOIN($idx; stream; idx_expr; join_expr): - This builtin joins the values from the given stream to the - given index. The index's keys are computed by applying the - given index expression to each value from the given stream. - An array of the value in the stream and the corresponding - value from the index is fed to the given join expression to - produce each result