Define examples in the "examples" field instead of "example"

Only examples defined in the "examples" field are generated, if they are
defined in "example", they are just ignored.

Also fix a bunch of incorrect tests.

docs/content/manual/manual.yml

@@ -1721,10 +1721,10 @@ sections:
           Emit a copy of the input string with its alphabetic characters (a-z and A-Z)
           converted to the specified case.
 
-        example:
+        examples:
           - program: 'ascii_upcase'
             input: '"useful but not for é"'
-            output: '"USEFUL BUT NOT FOR é"'
+            output: ['"USEFUL BUT NOT FOR é"']
 
       - title: "`while(cond; update)`"
         body: |
@@ -2500,15 +2500,11 @@ sections:
           To capture all the matches for each input string, use the idiom
           `[ expr ]`, e.g. `[ scan(regex) ]`.
 
-        example:
+        examples:
           - program: 'scan("c")'
             input: '"abcdefabc"'
             output: ['"c"', '"c"']
 
-          - program: 'scan("b")'
-            input: ("", "")
-            output: ['[]', '[]']
-
       - title: "`split(regex; flags)`"
         body: |
 
@@ -2517,10 +2513,10 @@ sections:
           For backwards compatibility, when called with a single argument,
           `split` splits on a string, not a regex.
 
-        example:
+        examples:
           - program: 'split(", *"; null)'
             input: '"ab,cd, ef"'
-            output: ['"ab","cd","ef"']
+            output: ['["ab","cd","ef"]']
 
 
       - title: "`splits(regex)`, `splits(regex; flags)`"
@@ -2529,10 +2525,10 @@ sections:
           These provide the same results as their `split` counterparts,
           but as a stream instead of an array.
 
-        example:
+        examples:
           - 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)`, `sub(regex; tostring; flags)`"
         body: |
@@ -2546,9 +2542,8 @@ sections:
           `tostring`, so a reference to a captured variable named "x"
           would take the form: `"\(.x)"`.
 
-        example:
+        examples:
-
+          - program: 'sub("[^a-z]*(?<x>[a-z]+)"; "Z\(.x)"; "g")'
-          - program: 'sub("[^a-z]*(?<x>[a-z]*)"; "Z\(.x)"; "g")'
             input: '"123abc456def"'
             output: ['"ZabcZdef"']
 
@@ -2563,7 +2558,7 @@ sections:
           replaced by `tostring`, after interpolation. If the second argument is a stream
           of jq strings, then `gsub` will produce a corresponding stream of JSON strings.
 
-        example:
+        examples:
           - program: 'gsub("(?<x>.)[^a]*"; "+\(.x)-")'
             input: '"Abcabc"'
             output: ['"+A-+a-"']

jq.1.prebuilt

@@ -1881,6 +1881,18 @@ jq \'join(" ")\'
 .SS "ascii_downcase, ascii_upcase"
 Emit a copy of the input string with its alphabetic characters (a\-z and A\-Z) converted to the specified case\.
 .
+.IP "" 4
+.
+.nf
+
+jq \'ascii_upcase\'
+   "useful but not for é"
+=> "USEFUL BUT NOT FOR é"
+.
+.fi
+.
+.IP "" 0
+.
 .SS "while(cond; update)"
 The \fBwhile(cond; update)\fR function allows you to repeatedly apply an update to \fB\.\fR until \fBcond\fR is false\.
 .
@@ -2778,21 +2790,89 @@ jq \'capture("(?<a>[a\-z]+)\-(?<n>[0\-9]+)")\'
 .SS "scan(regex), scan(regex; flags)"
 Emit a stream of the non\-overlapping substrings of the input that match the regex in accordance with the flags, if any have been specified\. If there is no match, the stream is empty\. To capture all the matches for each input string, use the idiom \fB[ expr ]\fR, e\.g\. \fB[ scan(regex) ]\fR\.
 .
+.IP "" 4
+.
+.nf
+
+jq \'scan("c")\'
+   "abcdefabc"
+=> "c", "c"
+.
+.fi
+.
+.IP "" 0
+.
 .SS "split(regex; flags)"
 Splits an input string on each regex match\.
 .
 .P
 For backwards compatibility, when called with a single argument, \fBsplit\fR splits on a string, not a regex\.
 .
+.IP "" 4
+.
+.nf
+
+jq \'split(", *"; null)\'
+   "ab,cd, ef"
+=> ["ab","cd","ef"]
+.
+.fi
+.
+.IP "" 0
+.
 .SS "splits(regex), splits(regex; flags)"
 These provide the same results as their \fBsplit\fR counterparts, but as a stream instead of an array\.
 .
+.IP "" 4
+.
+.nf
+
+jq \'splits(", *")\'
+   "ab,cd,   ef, gh"
+=> "ab", "cd", "ef", "gh"
+.
+.fi
+.
+.IP "" 0
+.
 .SS "sub(regex; tostring), sub(regex; tostring; flags)"
 Emit the string obtained by replacing the first match of regex in the input string with \fBtostring\fR, after interpolation\. \fBtostring\fR should be a jq string or a stream of such strings, each of which may contain references to named captures\. The named captures are, in effect, presented as a JSON object (as constructed by \fBcapture\fR) to \fBtostring\fR, so a reference to a captured variable named "x" would take the form: \fB"\e(\.x)"\fR\.
 .
+.IP "" 4
+.
+.nf
+
+jq \'sub("[^a\-z]*(?<x>[a\-z]+)"; "Z\e(\.x)"; "g")\'
+   "123abc456def"
+=> "ZabcZdef"
+
+jq \'[sub("(?<a>\.)"; "\e(\.a|ascii_upcase)", "\e(\.a|ascii_downcase)")]\'
+   "aB"
+=> ["AB","aB"]
+.
+.fi
+.
+.IP "" 0
+.
 .SS "gsub(regex; tostring), gsub(regex; tostring; flags)"
 \fBgsub\fR is like \fBsub\fR but all the non\-overlapping occurrences of the regex are replaced by \fBtostring\fR, after interpolation\. If the second argument is a stream of jq strings, then \fBgsub\fR will produce a corresponding stream of JSON strings\.
 .
+.IP "" 4
+.
+.nf
+
+jq \'gsub("(?<x>\.)[^a]*"; "+\e(\.x)\-")\'
+   "Abcabc"
+=> "+A\-+a\-"
+
+jq \'[gsub("p"; "a", "b")]\'
+   "p"
+=> ["a","b"]
+.
+.fi
+.
+.IP "" 0
+.
 .SH "ADVANCED FEATURES"
 Variables are an absolute necessity in most programming languages, but they\'re relegated to an "advanced feature" in jq\.
 .

tests/man.test

@@ -572,6 +572,10 @@ join(" ")
 ["a",1,2.3,true,null,false]
 "a 1 2.3 true  false"
 
+ascii_upcase
+"useful but not for é"
+"USEFUL BUT NOT FOR é"
+
 [while(.<100; .*2)]
 1
 [1,2,4,8,16,32,64]

tests/manonig.test

@@ -42,3 +42,35 @@ capture("(?<a>[a-z]+)-(?<n>[0-9]+)")
 "xyzzy-14"
 { "a": "xyzzy", "n": "14" }
 
+scan("c")
+"abcdefabc"
+"c"
+"c"
+
+split(", *"; null)
+"ab,cd, ef"
+["ab","cd","ef"]
+
+splits(", *")
+"ab,cd,   ef, gh"
+"ab"
+"cd"
+"ef"
+"gh"
+
+sub("[^a-z]*(?<x>[a-z]+)"; "Z\(.x)"; "g")
+"123abc456def"
+"ZabcZdef"
+
+[sub("(?<a>.)"; "\(.a|ascii_upcase)", "\(.a|ascii_downcase)")]
+"aB"
+["AB","aB"]
+
+gsub("(?<x>.)[^a]*"; "+\(.x)-")
+"Abcabc"
+"+A-+a-"
+
+[gsub("p"; "a", "b")]
+"p"
+["a","b"]
+