Skip to content

Commit

Permalink
Fix manual section titles, minor typos, and improve inline codes (#2626)
Browse files Browse the repository at this point in the history
  • Loading branch information
@itchyny
itchyny authored Jun 21, 2023
1 parent dd5ce98 commit 6864aa8
Show file tree
Hide file tree
Showing 5 changed files with 283 additions and 311 deletions.
153 changes: 74 additions & 79 deletions docs/content/manual/manual.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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: '.'
Expand Down Expand Up @@ -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.
Expand All @@ -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]'
Expand Down Expand Up @@ -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: `[]`"
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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)'
Expand Down Expand Up @@ -1013,19 +1013,19 @@ 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
key-value pairs. If `to_entries` is passed an object, then
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'
Expand All @@ -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))`
Expand Down Expand Up @@ -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
Expand All @@ -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]']

Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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'\""]
Expand Down Expand Up @@ -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`
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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"'
Expand All @@ -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']
Expand Down Expand Up @@ -2568,15 +2563,15 @@ 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"}}
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
Expand All @@ -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
Expand Down
Loading

0 comments on commit 6864aa8

Please sign in to comment.