navigine/jq
1
0 Fork 0
mirror of https://github.com/jqlang/jq.git synced 2026-10-30 10:06:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

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

No files matched your search

docs/content/manual/v1.5/manual.yml
+52 -58
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