Merge pull request #651 from eiiches/fix-examples
Fix several errors in the manual
This commit is contained in:
Nico Williams committed
commit
e0f9b6a5cd
2 files changed
+139
-139
No files matched your search
+136
-136
@@ -1094,7 +1094,7 @@ sections:
|
|||||||
output: ['[{"foo": 1, "bar": 2}, {"foo": 4, "bar": 5}]']
|
output: ['[{"foo": 1, "bar": 2}, {"foo": 4, "bar": 5}]']
|
||||||
- program: 'unique_by(length)'
|
- program: 'unique_by(length)'
|
||||||
input: '["chunky", "bacon", "kitten", "cicada", "asparagus"]'
|
input: '["chunky", "bacon", "kitten", "cicada", "asparagus"]'
|
||||||
output: ['["chunky", "bacon", "asparagus"]']
|
output: ['["bacon", "chunky", "asparagus"]']
|
||||||
|
|
||||||
- title: "`reverse`"
|
- title: "`reverse`"
|
||||||
body: |
|
body: |
|
||||||
@@ -1164,7 +1164,7 @@ sections:
|
|||||||
- program: 'index(", ")'
|
- program: 'index(", ")'
|
||||||
input: '"a,b, cd, efg, hijk"'
|
input: '"a,b, cd, efg, hijk"'
|
||||||
output: ['3']
|
output: ['3']
|
||||||
- program: 'rindex(", ")]'
|
- program: 'rindex(", ")'
|
||||||
input: '"a,b, cd, efg, hijk"'
|
input: '"a,b, cd, efg, hijk"'
|
||||||
output: ['12']
|
output: ['12']
|
||||||
|
|
||||||
@@ -1343,6 +1343,7 @@ sections:
|
|||||||
- program: 'recurse'
|
- program: 'recurse'
|
||||||
input: '{"a":0,"b":[1]}'
|
input: '{"a":0,"b":[1]}'
|
||||||
output:
|
output:
|
||||||
|
- '{"a":0,"b":[1]}'
|
||||||
- '0'
|
- '0'
|
||||||
- '[1]'
|
- '[1]'
|
||||||
- '1'
|
- '1'
|
||||||
@@ -1668,181 +1669,180 @@ sections:
|
|||||||
The jq regex filters are defined so that they can be used using
|
The jq regex filters are defined so that they can be used using
|
||||||
one of these patterns:
|
one of these patterns:
|
||||||
|
|
||||||
STRING | FILTER( REGEX )
|
STRING | FILTER( REGEX )
|
||||||
STRING | FILTER( REGEX; FLAGS )
|
STRING | FILTER( REGEX; FLAGS )
|
||||||
STRING | FILTER( [REGEX] )
|
STRING | FILTER( [REGEX] )
|
||||||
STRING | FILTER( [REGEX, FLAGS] )
|
STRING | FILTER( [REGEX, FLAGS] )
|
||||||
|
|
||||||
where:
|
where:
|
||||||
* STRING, REGEX and FLAGS are jq strings and subject to jq string interpolation;
|
* STRING, REGEX and FLAGS are jq strings and subject to jq string interpolation;
|
||||||
* REGEX, after string interpolation, should be a valid PCRE regex;
|
* REGEX, after string interpolation, should be a valid PCRE regex;
|
||||||
* FILTER is one of `test`, `match`, or `capture`, as described below.
|
* FILTER is one of `test`, `match`, or `capture`, as described below.
|
||||||
|
|
||||||
FLAGS is a string consisting of one of more of the supported flags:
|
FLAGS is a string consisting of one of more of the supported flags:
|
||||||
|
|
||||||
* `g` - Global search (find all matches, not just the first)
|
* `g` - Global search (find all matches, not just the first)
|
||||||
* `i` - Case insensitive search
|
* `i` - Case insensitive search
|
||||||
* `m` - Multi line mode ('.' will match newlines)
|
* `m` - Multi line mode ('.' will match newlines)
|
||||||
* `n` - Ignore empty matches
|
* `n` - Ignore empty matches
|
||||||
* `p` - Both s and m modes are enabled
|
* `p` - Both s and m modes are enabled
|
||||||
* `s` - Single line mode ('^' -> '\A', '$' -> '\Z')
|
* `s` - Single line mode ('^' -> '\A', '$' -> '\Z')
|
||||||
* `l` - Find longest possible matches
|
* `l` - Find longest possible matches
|
||||||
* `x` - Extended regex format (ignore whitespace and comments)
|
* `x` - Extended regex format (ignore whitespace and comments)
|
||||||
|
|
||||||
To match whitespace in an x pattern use an escape such as \s, e.g.
|
To match whitespace in an x pattern use an escape such as \s, e.g.
|
||||||
|
|
||||||
* test( "a\\sb", "x" ).
|
* test( "a\\sb", "x" ).
|
||||||
|
|
||||||
Note that certain flags may also be specified within REGEX, e.g.
|
Note that certain flags may also be specified within REGEX, e.g.
|
||||||
|
|
||||||
* jq -n '("test", "TEst", "teST", "TEST") | test( "(?i)te(?-i)st" )'
|
* jq -n '("test", "TEst", "teST", "TEST") | test( "(?i)te(?-i)st" )'
|
||||||
|
|
||||||
evaluates to: true, true, false, false.
|
evaluates to: true, true, false, false.
|
||||||
|
|
||||||
entries:
|
entries:
|
||||||
- title: "`test(val)`, `test(regex; flags)`"
|
- title: "`test(val)`, `test(regex; flags)`"
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
Like `match`, but does not return match objects, only `true` or `false`
|
Like `match`, but does not return match objects, only `true` or `false`
|
||||||
for whether or not the regex matches the input.
|
for whether or not the regex matches the input.
|
||||||
|
|
||||||
examples:
|
examples:
|
||||||
- program: 'test("foo")'
|
- program: 'test("foo")'
|
||||||
input: '"foo"'
|
input: '"foo"'
|
||||||
output: 'true'
|
output: ['true']
|
||||||
- program: 'test("a b c # spaces are ignored"; "ix")'
|
- program: '.[] | test("a b c # spaces are ignored"; "ix")'
|
||||||
input: '"xabcd" "ABC"'
|
input: '["xabcd", "ABC"]'
|
||||||
output: true
|
output: ['true', 'true']
|
||||||
true
|
|
||||||
|
|
||||||
- title: "`match(val)`, `match(regex; flags)`"
|
- title: "`match(val)`, `match(regex; flags)`"
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
**match** outputs an object for each match it finds. Matches have
|
**match** outputs an object for each match it finds. Matches have
|
||||||
the following fields:
|
the following fields:
|
||||||
|
|
||||||
* `offset` - offset in UTF-8 codepoints from the beginning of the input
|
* `offset` - offset in UTF-8 codepoints from the beginning of the input
|
||||||
* `length` - length in UTF-8 codepoints of the match
|
* `length` - length in UTF-8 codepoints of the match
|
||||||
* `string` - the string that it matched
|
* `string` - the string that it matched
|
||||||
* `captures` - an array of objects representing capturing groups.
|
* `captures` - an array of objects representing capturing groups.
|
||||||
|
|
||||||
Capturing group objects have the following fields:
|
Capturing group objects have the following fields:
|
||||||
|
|
||||||
* `offset` - offset in UTF-8 codepoints from the beginning of the input
|
* `offset` - offset in UTF-8 codepoints from the beginning of the input
|
||||||
* `length` - length in UTF-8 codepoints of this capturing group
|
* `length` - length in UTF-8 codepoints of this capturing group
|
||||||
* `string` - the string that was captured
|
* `string` - the string that was captured
|
||||||
* `name` - the name of the capturing group (or `null` if it was unnamed)
|
* `name` - the name of the capturing group (or `null` if it was unnamed)
|
||||||
|
|
||||||
Capturing groups that did not match anything return an offset of -1
|
Capturing groups that did not match anything return an offset of -1
|
||||||
|
|
||||||
examples:
|
examples:
|
||||||
- program: 'match("(abc)+"; "g")'
|
- program: 'match("(abc)+"; "g")'
|
||||||
input: '"abc abc"'
|
input: '"abc abc"'
|
||||||
output:
|
output:
|
||||||
- '{"offset": 0, "length": 3, "string": "abc", "captures": [{"offset": 0, "length": 3, "string": "abc", "name": null}]}'
|
- '{"offset": 0, "length": 3, "string": "abc", "captures": [{"offset": 0, "length": 3, "string": "abc", "name": null}]}'
|
||||||
- '{"offset": 4, "length": 3, "string": "abc", "captures": [{"offset": 4, "length": 3, "string": "abc", "name": null}]}'
|
- '{"offset": 4, "length": 3, "string": "abc", "captures": [{"offset": 4, "length": 3, "string": "abc", "name": null}]}'
|
||||||
- program: 'match("foo")'
|
- program: 'match("foo")'
|
||||||
input: '"foo bar foo"'
|
input: '"foo bar foo"'
|
||||||
output: ['{"offset": 0, "length": 3, "string": "foo", "captures": []}']
|
output: ['{"offset": 0, "length": 3, "string": "foo", "captures": []}']
|
||||||
- program: 'match(["foo", "ig"])'
|
- program: 'match(["foo", "ig"])'
|
||||||
input: '"foo bar FOO"'
|
input: '"foo bar FOO"'
|
||||||
output:
|
output:
|
||||||
- '{"offset": 0, "length": 3, "string": "foo", "captures": []}'
|
- '{"offset": 0, "length": 3, "string": "foo", "captures": []}'
|
||||||
- '{"offset": 8, "length": 3, "string": "FOO", "captures": []}'
|
- '{"offset": 8, "length": 3, "string": "FOO", "captures": []}'
|
||||||
- program: 'match("foo (?<bar123>bar)? foo"; "ig")'
|
- program: 'match("foo (?<bar123>bar)? foo"; "ig")'
|
||||||
input: '"foo bar foo foo foo"'
|
input: '"foo bar foo foo foo"'
|
||||||
output:
|
output:
|
||||||
- '{"offset": 0, "length": 11, "string": "foo bar foo", "captures": [{"offset": 4, "length": 3, "string": "bar", "name": "bar123"}]}'
|
- '{"offset": 0, "length": 11, "string": "foo bar foo", "captures": [{"offset": 4, "length": 3, "string": "bar", "name": "bar123"}]}'
|
||||||
- '{"offset": 12, "length": 8, "string": "foo foo", "captures": [{"offset": -1, "length": 0, "string": null, "name": "bar123"}]}'
|
- '{"offset": 12, "length": 8, "string": "foo foo", "captures": [{"offset": -1, "length": 0, "string": null, "name": "bar123"}]}'
|
||||||
|
|
||||||
- program: '[ match("."; "g")] | length'
|
- program: '[ match("."; "g")] | length'
|
||||||
input: '"abc"'
|
input: '"abc"'
|
||||||
output: 3
|
output: [3]
|
||||||
|
|
||||||
|
|
||||||
- title: "`capture(val)`, `capture(regex; flags)`"
|
- title: "`capture(val)`, `capture(regex; flags)`"
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
Collects the named captures in a JSON object, with the name
|
Collects the named captures in a JSON object, with the name
|
||||||
of each capture as the key, and the matched string as the
|
of each capture as the key, and the matched string as the
|
||||||
corresponding value.
|
corresponding value.
|
||||||
|
|
||||||
examples:
|
examples:
|
||||||
- program: 'capture("(?<a>[a-z]+)-(?<n>[0-9]+)")'
|
- program: 'capture("(?<a>[a-z]+)-(?<n>[0-9]+)")'
|
||||||
input: '"xyzzy-14"'
|
input: '"xyzzy-14"'
|
||||||
output: ['{ "a": "xyzzy", "n": "14" }']
|
output: ['{ "a": "xyzzy", "n": "14" }']
|
||||||
|
|
||||||
- title: "`scan(regex)`, `scan(regex; flags)`"
|
- title: "`scan(regex)`, `scan(regex; flags)`"
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
Emit a stream of the non-overlapping substrings of the input
|
Emit a stream of the non-overlapping substrings of the input
|
||||||
that match the regex in accordance with the flags, if any
|
that match the regex in accordance with the flags, if any
|
||||||
have been specified. If there is no match, the stream is empty.
|
have been specified. If there is no match, the stream is empty.
|
||||||
To capture all the matches for each input string, use the idiom
|
To capture all the matches for each input string, use the idiom
|
||||||
`[ expr ]`, e.g. `[ scan(regex) ]`.
|
`[ expr ]`, e.g. `[ scan(regex) ]`.
|
||||||
|
|
||||||
example:
|
example:
|
||||||
- program: 'scan("c")'
|
- program: 'scan("c")'
|
||||||
input: '"abcdefabc"'
|
input: '"abcdefabc"'
|
||||||
output: ['"c"', '"c"']
|
output: ['"c"', '"c"']
|
||||||
|
|
||||||
- program: 'scan("b")'
|
- program: 'scan("b")'
|
||||||
input: ("", "")
|
input: ("", "")
|
||||||
output: ['[]', '[]']
|
output: ['[]', '[]']
|
||||||
|
|
||||||
- title: "`split(regex; flags)`"
|
- title: "`split(regex; flags)`"
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
For backwards compatibility, `split` emits an array of the strings
|
For backwards compatibility, `split` emits an array of the strings
|
||||||
corresponding to the successive segments of the input string after it
|
corresponding to the successive segments of the input string after it
|
||||||
has been split at the boundaries defined by the regex and any
|
has been split at the boundaries defined by the regex and any
|
||||||
specified flags. The substrings corresponding to the boundaries
|
specified flags. The substrings corresponding to the boundaries
|
||||||
themselves are excluded. If regex is the empty string, then the first
|
themselves are excluded. If regex is the empty string, then the first
|
||||||
match will be the empty string.
|
match will be the empty string.
|
||||||
|
|
||||||
example:
|
example:
|
||||||
- program: 'split(", *"; null)'
|
- program: 'split(", *"; null)'
|
||||||
input: '"ab,cd, ef"'
|
input: '"ab,cd, ef"'
|
||||||
output: ['"ab","cd","ef"']
|
output: ['"ab","cd","ef"']
|
||||||
|
|
||||||
|
|
||||||
- title: "`splits(regex)`, splits(regex; flags)`"
|
- title: "`splits(regex)`, `splits(regex; flags)`"
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
These provide the same results as their `split` counterparts,
|
These provide the same results as their `split` counterparts,
|
||||||
but as a stream instead of an array.
|
but as a stream instead of an array.
|
||||||
|
|
||||||
example:
|
example:
|
||||||
- program: 'splits(", *")'
|
- program: 'splits(", *")'
|
||||||
input: '("ab,cd", "ef, gh")'
|
input: '("ab,cd", "ef, gh")'
|
||||||
output: ['"ab"', '"cd"', '"ef"', '"gh"']
|
output: ['"ab"', '"cd"', '"ef"', '"gh"']
|
||||||
|
|
||||||
- title: "`sub(regex; tostring)`"
|
- title: "`sub(regex; tostring)`"
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
Emit the string obtained by replacing the first match of regex in the
|
Emit the string obtained by replacing the first match of regex in the
|
||||||
input string with `tostring`, after interpolation. `tostring` should
|
input string with `tostring`, after interpolation. `tostring` should
|
||||||
be a jq string, and may contain references to named captures. The
|
be a jq string, and may contain references to named captures. The
|
||||||
named captures are, in effect, presented as a JSON object (as
|
named captures are, in effect, presented as a JSON object (as
|
||||||
constructed by `capture`) to `tostring`, so a reference to a captured
|
constructed by `capture`) to `tostring`, so a reference to a captured
|
||||||
variable named "x" would take the form: "\(.x)".
|
variable named "x" would take the form: "\(.x)".
|
||||||
|
|
||||||
example:
|
example:
|
||||||
- program: 'sub("^[^a-z]*(?<x>[a-z]*).*")'
|
- program: 'sub("^[^a-z]*(?<x>[a-z]*).*")'
|
||||||
input: '"123abc456"'
|
input: '"123abc456"'
|
||||||
output: '"ZabcZabc"'
|
output: '"ZabcZabc"'
|
||||||
|
|
||||||
|
|
||||||
- title: "`gsub(regex; string)`"
|
- title: "`gsub(regex; string)`"
|
||||||
body: |
|
body: |
|
||||||
|
|
||||||
`gsub` is like `sub` but all the non-overlapping occurrences of the regex are
|
`gsub` is like `sub` but all the non-overlapping occurrences of the regex are
|
||||||
replaced by the string, after interpolation.
|
replaced by the string, after interpolation.
|
||||||
|
|
||||||
example:
|
example:
|
||||||
- program: 'gsub("(?<x>.)[^a]*"; "+\(.x)-")'
|
- program: 'gsub("(?<x>.)[^a]*"; "+\(.x)-")'
|
||||||
input: '"Abcabc"'
|
input: '"Abcabc"'
|
||||||
output: '"+A-+a-"'
|
output: '"+A-+a-"'
|
||||||
|
|
||||||
|
|
||||||
- title: Advanced features
|
- title: Advanced features
|
||||||
|
|||||||
Vendored
+3
-3
@@ -70,8 +70,8 @@
|
|||||||
|
|
||||||
{% for example in entry.examples %}
|
{% for example in entry.examples %}
|
||||||
<table class="manual-example">
|
<table class="manual-example">
|
||||||
<tr><th></th><td class="jqprogram">jq '{{example.program}}'</td></tr>
|
<tr><th></th><td class="jqprogram">jq '{{example.program | escape}}'</td></tr>
|
||||||
<tr><th>Input</th><td>{{example.input}}</td></tr>
|
<tr><th>Input</th><td>{{example.input | escape}}</td></tr>
|
||||||
{% unless example.output[0] %}
|
{% unless example.output[0] %}
|
||||||
<tr>
|
<tr>
|
||||||
<th>Output</th>
|
<th>Output</th>
|
||||||
@@ -85,7 +85,7 @@
|
|||||||
{% else %}
|
{% else %}
|
||||||
<th></th>
|
<th></th>
|
||||||
{% endif %}
|
{% endif %}
|
||||||
<td>{{output}}</td>
|
<td>{{output | escape}}</td>
|
||||||
</tr>
|
</tr>
|
||||||
{% endfor %}
|
{% endfor %}
|
||||||
|
|
||||||
|
|||||||
Reference in new issue
Block a user