diff --git a/docs/content/manual/manual.yml b/docs/content/manual/manual.yml index 24db2daf6c..a951b9b2c7 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 d497998547..3b09933236 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 25aeb9ddc0..02f9532912 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 36f3b091f0..11c33fb3bb 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"] +