mirror/stedolan-jq
1
0
Fork 0
mirror of https://github.com/stedolan/jq.git synced 2024-05-11 05:55:39 +00:00
Code Issues Releases Activity

Fix manual section titles, minor typos, and improve inline codes (#2626)

Browse Source
This commit is contained in:
itchyny
2023-06-22 08:31:38 +09:00
committed by GitHub
parent dd5ce98caf
commit 6864aa8630
5 changed files with 283 additions and 311 deletions
Download Patch File Download Diff File Expand all files Collapse all files

153
docs/content/manual/manual.yml
View File

@@ -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: `.[<string>]`"
- title: "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, but
`.["foo"]` (`.foo` above is a shorthand version of this, but
only for identifier-like strings).
- title: "Array Index: `.[2]`"
- title: "Array Index: `.[<number>]`"
body: |
When the index value is an integer, `.[<value>]` can index
When the index value is an integer, `.[<number>]` 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: `.[<number>:<number>]`"
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 `.[<number>:<number>]` 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 &lt; y"']
# - program: '@html "<span>Anonymous said: \(.)</span>"'
# input: '"<script>alert(\"lol hax\");</script>"'
# output: ["<span>Anonymous said: &lt;script&gt;alert(&quot;lol hax&quot;);&lt;/script&gt;</span>"]
- 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

63
docs/content/manual/v1.3/manual.yml
View File

@@ -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 &lt; y"']
# - program: '@html "<span>Anonymous said: \(.)</span>"'
# input: '"<script>alert(\"lol hax\");</script>"'
# output: ["<span>Anonymous said: &lt;script&gt;alert(&quot;lol hax&quot;);&lt;/script&gt;</span>"]
- 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

69
docs/content/manual/v1.4/manual.yml
View File

@@ -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: "`.[<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.
@@ -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 &lt; y"']
# - program: '@html "<span>Anonymous said: \(.)</span>"'
# input: '"<script>alert(\"lol hax\");</script>"'
# output: ["<span>Anonymous said: &lt;script&gt;alert(&quot;lol hax&quot;);&lt;/script&gt;</span>"]
- 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

110
docs/content/manual/v1.5/manual.yml
View File

@@ -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 &lt; y"']
# - program: '@html "<span>Anonymous said: \(.)</span>"'
# input: '"<script>alert(\"lol hax\");</script>"'
# output: ["<span>Anonymous said: &lt;script&gt;alert(&quot;lol hax&quot;);&lt;/script&gt;</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

199
docs/content/manual/v1.6/manual.yml
View File

@@ -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: `.[<string>]`"
- title: "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, but
`.["foo"]` (`.foo` above is a shorthand version of this, but
only for identifier-like strings).
- title: "Array Index: `.[2]`"
- title: "Array Index: `.[<number>]`"
body: |
When the index value is an integer, `.[<value>]` can index
When the index value is an integer, `.[<number>]` 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: `.[<number>:<number>]`"
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 `.[<number>:<number>]` 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 &lt; y"']
# - program: '@html "<span>Anonymous said: \(.)</span>"'
# input: '"<script>alert(\"lol hax\");</script>"'
# output: ["<span>Anonymous said: &lt;script&gt;alert(&quot;lol hax&quot;);&lt;/script&gt;</span>"]
- 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.
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.
* JOIN($idx; stream; idx_expr):
* JOIN($idx; stream; idx_expr):
Same as `JOIN($idx; stream; idx_expr; .)`.
Same as `JOIN($idx; stream; idx_expr; .)`.
* JOIN($idx; idx_expr):
* JOIN($idx; idx_expr):
This builtin joins the input `.` to the given index, applying
the given index expression to `.` to compute the index key.
The join operation is as described above.
This builtin joins the input `.` to the given index, applying
the given index expression to `.` to compute the index key.
The join operation is as described above.
* IN(s):
* IN(s):
This builtin outputs `true` if `.` appears in the given
stream, otherwise it outputs `false`.
This builtin outputs `true` if `.` appears in the given
stream, otherwise it outputs `false`.
* IN(source; s):
* IN(source; s):
This builtin outputs `true` if any value in the source stream
appears in the second stream, otherwise it outputs `false`.
This builtin outputs `true` if any value in the source stream
appears in the second stream, otherwise it outputs `false`.
- title: "`builtins`"
body: |
@@ -2037,7 +2033,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`
@@ -2047,10 +2043,9 @@ sections:
Checking for false or null is a simpler notion of
"truthiness" than is found in JavaScript or Python, but it
means that you'll sometimes have to be more explicit about
the condition you want: you can't test whether, e.g. a
the condition you want. You can't test whether, e.g. a
string is empty using `if .name then A else B end`, you'll
need something more like `if (.name | length) > 0 then A else
B end` instead.
need something more like `if .name == "" then A else B end` instead.
If the condition `A` produces multiple results, then `B` is evaluated
once for each result that is not false or null, and `C` is evaluated
@@ -2070,7 +2065,7 @@ sections:
input: 2
output: ['"many"']
- title: "`>, >=, <=, <`"
- title: "`>`, `>=`, `<=`, `<`"
body: |
The comparison operators `>`, `>=`, `<=`, `<` return whether
@@ -2085,12 +2080,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.
@@ -2100,12 +2096,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"'
@@ -2114,9 +2110,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']
@@ -2366,7 +2359,7 @@ sections:
input: '("ab,cd", "ef, gh")'
output: ['"ab"', '"cd"', '"ef"', '"gh"']
- title: "`sub(regex; tostring)` `sub(regex; string; flags)`"
- title: "`sub(regex; tostring)`, `sub(regex; string; flags)`"
body: |
Emit the string obtained by replacing the first match of regex in the
@@ -2458,7 +2451,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"}}
@@ -2466,7 +2459,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
@@ -2480,7 +2473,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
@@ -2641,9 +2634,9 @@ sections:
For example, in the following expression there is a binding
which is visible "to the right" of it, `... | .*3 as
$times_three | [. + $times_three] | ...`, but not "to the
$times_three | [. + $times_three] | ...`, but not "to the
left". Consider this expression now, `... | (.*3 as
$times_three | [.+ $times_three]) | ...`: here the binding
$times_three | [. + $times_three]) | ...`: here the binding
`$times_three` is _not_ visible past the closing parenthesis.
- title: Reduce