From 15fd31de78c7dbc1af0a7cf735587dc5b1729d20 Mon Sep 17 00:00:00 2001 From: Emanuele Torre Date: Tue, 18 Jul 2023 05:54:44 +0200 Subject: [PATCH] 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 | 27 +++++------- jq.1.prebuilt | 80 ++++++++++++++++++++++++++++++++++ tests/man.test | 4 ++ tests/manonig.test | 32 ++++++++++++++ 4 files changed, 127 insertions(+), 16 deletions(-) diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml index 24db2daf..a951b9b2 100644 --- a/docs/content/manual/manual.yml +++ b/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")' - output: ['"ab"', '"cd"', '"ef"', '"gh"'] + input: '"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: - - - program: 'sub("[^a-z]*(?[a-z]*)"; "Z\(.x)"; "g")' + examples: + - program: 'sub("[^a-z]*(?[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("(?.)[^a]*"; "+\(.x)-")' input: '"Abcabc"' output: ['"+A-+a-"'] diff --git a/jq.1.prebuilt b/jq.1.prebuilt index d4979985..3b099332 100644 --- a/jq.1.prebuilt +++ b/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\-z]+)\-(?[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]*(?[a\-z]+)"; "Z\e(\.x)"; "g")\' + "123abc456def" +=> "ZabcZdef" + +jq \'[sub("(?\.)"; "\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("(?\.)[^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\. . diff --git a/tests/man.test b/tests/man.test index 25aeb9dd..02f95329 100644 --- a/tests/man.test +++ b/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] diff --git a/tests/manonig.test b/tests/manonig.test index 36f3b091..11c33fb3 100644 --- a/tests/manonig.test +++ b/tests/manonig.test @@ -42,3 +42,35 @@ capture("(?[a-z]+)-(?[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]*(?[a-z]+)"; "Z\(.x)"; "g") +"123abc456def" +"ZabcZdef" + +[sub("(?.)"; "\(.a|ascii_upcase)", "\(.a|ascii_downcase)")] +"aB" +["AB","aB"] + +gsub("(?.)[^a]*"; "+\(.x)-") +"Abcabc" +"+A-+a-" + +[gsub("p"; "a", "b")] +"p" +["a","b"] +