From 2e5c3f490ca015ecfa542c848bb59a74e5e020ed Mon Sep 17 00:00:00 2001 From: itchyny Date: Wed, 14 Jun 2023 07:36:06 +0900 Subject: Fix regular expression section on PCRE (fix #2439), also improve example format (#2613) --- docs/content/manual/manual.yml | 28 ++++++++++++++-------------- docs/content/manual/v1.5/manual.yml | 31 ++++++++++++++++--------------- docs/content/manual/v1.6/manual.yml | 31 ++++++++++++++++--------------- 3 files changed, 46 insertions(+), 44 deletions(-) diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml index b32100f6..fec53b0a 100644 --- a/docs/content/manual/manual.yml +++ b/docs/content/manual/manual.yml @@ -2293,48 +2293,48 @@ sections: output: ['[null, 1]'] - - title: Regular expressions (PCRE) + - title: Regular expressions body: | jq uses the [Oniguruma regular expression library](https://github.com/kkos/oniguruma/blob/master/doc/RE), - as do php, ruby, TextMate, Sublime Text, etc, so the + as do PHP, Ruby, TextMate, Sublime Text, etc, so the description here will focus on jq specifics. The jq regex filters are defined so that they can be used using one of these patterns: - STRING | FILTER( REGEX ) - STRING | FILTER( REGEX; FLAGS ) - STRING | FILTER( [REGEX] ) - STRING | FILTER( [REGEX, FLAGS] ) + STRING | FILTER(REGEX) + STRING | FILTER(REGEX; FLAGS) + STRING | FILTER([REGEX]) + STRING | FILTER([REGEX, FLAGS]) where: - * STRING, REGEX and FLAGS are jq strings and subject to jq string interpolation; - * REGEX, after string interpolation, should be a valid PCRE regex; + * STRING, REGEX, and FLAGS are jq strings and subject to jq string interpolation; + * REGEX, after string interpolation, should be a valid regular expression; * FILTER is one of `test`, `match`, or `capture`, as described below. FLAGS is a string consisting of one of more of the supported flags: * `g` - Global search (find all matches, not just the first) * `i` - Case insensitive search - * `m` - Multi line mode ('.' will match newlines) + * `m` - Multi line mode (`.` will match newlines) * `n` - Ignore empty matches * `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 * `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 a whitespace with the `x` flag, use `\s`, e.g. - * test( "a\\\\sb"; "x" ) + jq -n '"a b" | test("a\\sb"; "x")' 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: - title: "`test(val)`, `test(regex; flags)`" diff --git a/docs/content/manual/v1.5/manual.yml b/docs/content/manual/v1.5/manual.yml index 7f9bed4b..2ef584af 100644 --- a/docs/content/manual/v1.5/manual.yml +++ b/docs/content/manual/v1.5/manual.yml @@ -1954,46 +1954,47 @@ sections: output: ['[null, 1]'] - - title: Regular expressions (PCRE) + - title: Regular expressions body: | - jq uses the Oniguruma regular expression library, as do php, - ruby, TextMate, Sublime Text, etc, so the description here + jq uses the Oniguruma regular expression library, as do PHP, + Ruby, TextMate, Sublime Text, etc, so the description here will focus on jq specifics. The jq regex filters are defined so that they can be used using one of these patterns: - STRING | FILTER( REGEX ) - STRING | FILTER( REGEX; FLAGS ) - STRING | FILTER( [REGEX] ) - STRING | FILTER( [REGEX, FLAGS] ) + STRING | FILTER(REGEX) + STRING | FILTER(REGEX; FLAGS) + STRING | FILTER([REGEX]) + STRING | FILTER([REGEX, FLAGS]) where: - * STRING, REGEX and FLAGS are jq strings and subject to jq string interpolation; - * REGEX, after string interpolation, should be a valid PCRE regex; + + * STRING, REGEX, and FLAGS are jq strings and subject to jq string interpolation; + * REGEX, after string interpolation, should be a valid regular expression; * FILTER is one of `test`, `match`, or `capture`, as described below. FLAGS is a string consisting of one of more of the supported flags: * `g` - Global search (find all matches, not just the first) * `i` - Case insensitive search - * `m` - Multi line mode ('.' will match newlines) + * `m` - Multi line mode (`.` will match newlines) * `n` - Ignore empty matches * `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 * `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 a whitespace with the `x` flag, use `\s`, e.g. - * test( "a\\\\sb"; "x" ) + jq -n '"a b" | test("a\\sb"; "x")' 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: - title: "`test(val)`, `test(regex; flags)`" diff --git a/docs/content/manual/v1.6/manual.yml b/docs/content/manual/v1.6/manual.yml index 7ea6add3..5aadf0cc 100644 --- a/docs/content/manual/v1.6/manual.yml +++ b/docs/content/manual/v1.6/manual.yml @@ -2200,46 +2200,47 @@ sections: output: ['[null, 1]'] - - title: Regular expressions (PCRE) + - title: Regular expressions body: | - jq uses the Oniguruma regular expression library, as do php, - ruby, TextMate, Sublime Text, etc, so the description here + jq uses the Oniguruma regular expression library, as do PHP, + Ruby, TextMate, Sublime Text, etc, so the description here will focus on jq specifics. The jq regex filters are defined so that they can be used using one of these patterns: - STRING | FILTER( REGEX ) - STRING | FILTER( REGEX; FLAGS ) - STRING | FILTER( [REGEX] ) - STRING | FILTER( [REGEX, FLAGS] ) + STRING | FILTER(REGEX) + STRING | FILTER(REGEX; FLAGS) + STRING | FILTER([REGEX]) + STRING | FILTER([REGEX, FLAGS]) where: - * STRING, REGEX and FLAGS are jq strings and subject to jq string interpolation; - * REGEX, after string interpolation, should be a valid PCRE regex; + + * STRING, REGEX, and FLAGS are jq strings and subject to jq string interpolation; + * REGEX, after string interpolation, should be a valid regular expression; * FILTER is one of `test`, `match`, or `capture`, as described below. FLAGS is a string consisting of one of more of the supported flags: * `g` - Global search (find all matches, not just the first) * `i` - Case insensitive search - * `m` - Multi line mode ('.' will match newlines) + * `m` - Multi line mode (`.` will match newlines) * `n` - Ignore empty matches * `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 * `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 a whitespace with the `x` flag, use `\s`, e.g. - * test( "a\\\\sb"; "x" ) + jq -n '"a b" | test("a\\sb"; "x")' 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: - title: "`test(val)`, `test(regex; flags)`" -- cgit v1.2.3