"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "jq.1.prebuilt" between
jq-1.5.tar.gz and jq-1.6.tar.gz

About: jq is a lightweight and flexible command-line JSON processor.

jq.1.prebuilt  (jq-1.5):jq.1.prebuilt  (jq-1.6)
.\" generated with Ronn/v0.7.3 .\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3 .\" http://github.com/rtomayko/ronn/tree/0.7.3
. .
.TH "JQ" "1" "August 2015" "" "" .TH "JQ" "1" "December 2017" "" ""
. .
.SH "NAME" .SH "NAME"
\fBjq\fR \- Command\-line JSON processor \fBjq\fR \- Command\-line JSON processor
. .
.SH "SYNOPSIS" .SH "SYNOPSIS"
\fBjq\fR [\fIoptions\fR\.\.\.] \fIfilter\fR [\fIfiles\fR\.\.\.] \fBjq\fR [\fIoptions\fR\.\.\.] \fIfilter\fR [\fIfiles\fR\.\.\.]
. .
.P .P
\fBjq\fR can transform JSON in various ways, by selecting, iterating, reducing a nd otherwise mangling JSON documents\. For instance, running the command \fBjq \ 'map(\.price) | add\'\fR will take an array of JSON objects as input and return the sum of their "price" fields\. \fBjq\fR can transform JSON in various ways, by selecting, iterating, reducing a nd otherwise mangling JSON documents\. For instance, running the command \fBjq \ 'map(\.price) | add\'\fR will take an array of JSON objects as input and return the sum of their "price" fields\.
. .
skipping to change at line 55 skipping to change at line 55
.IP "\(bu" 4 .IP "\(bu" 4
\fB\-\-version\fR: \fB\-\-version\fR:
. .
.IP .IP
Output the jq version and exit with zero\. Output the jq version and exit with zero\.
. .
.IP "\(bu" 4 .IP "\(bu" 4
\fB\-\-seq\fR: \fB\-\-seq\fR:
. .
.IP .IP
Use the \fBapplication/json\-seq\fR MIME type scheme for separating JSON texts i n jq\'s input and output\. This means that an ASCII RS (record separator) charac ter is printed before each value on output and an ASCII LF (line feed) is printe d after every output\. Input JSON texts that fail to parse are ignored (but warn ed about), discarding all subsequent input until the next RS\. This more also pa rses the output of jq without the \fB\-\-seq\fR option\. Use the \fBapplication/json\-seq\fR MIME type scheme for separating JSON texts i n jq\'s input and output\. This means that an ASCII RS (record separator) charac ter is printed before each value on output and an ASCII LF (line feed) is printe d after every output\. Input JSON texts that fail to parse are ignored (but warn ed about), discarding all subsequent input until the next RS\. This mode also pa rses the output of jq without the \fB\-\-seq\fR option\.
. .
.IP "\(bu" 4 .IP "\(bu" 4
\fB\-\-stream\fR: \fB\-\-stream\fR:
. .
.IP .IP
Parse the input in streaming fashion, outputing arrays of path and leaf values ( scalars and empty arrays or empty objects)\. For example, \fB"a"\fR becomes \fB[ [],"a"]\fR, and \fB[[],"a",["b"]]\fR becomes \fB[[0],[]]\fR, \fB[[1],"a"]\fR, an d \fB[[1,0],"b"]\fR\. Parse the input in streaming fashion, outputing arrays of path and leaf values ( scalars and empty arrays or empty objects)\. For example, \fB"a"\fR becomes \fB[ [],"a"]\fR, and \fB[[],"a",["b"]]\fR becomes \fB[[0],[]]\fR, \fB[[1],"a"]\fR, an d \fB[[1,0],"b"]\fR\.
. .
.IP .IP
This is useful for processing very large inputs\. Use this in conjunction with f iltering and the \fBreduce\fR and \fBforeach\fR syntax to reduce large inputs in crementally\. This is useful for processing very large inputs\. Use this in conjunction with f iltering and the \fBreduce\fR and \fBforeach\fR syntax to reduce large inputs in crementally\.
. .
skipping to change at line 108 skipping to change at line 108
. .
.IP .IP
Use the given number of spaces (no more than 8) for indentation\. Use the given number of spaces (no more than 8) for indentation\.
. .
.IP "\(bu" 4 .IP "\(bu" 4
\fB\-\-color\-output\fR / \fB\-C\fR and \fB\-\-monochrome\-output\fR / \fB\-M\fR : \fB\-\-color\-output\fR / \fB\-C\fR and \fB\-\-monochrome\-output\fR / \fB\-M\fR :
. .
.IP .IP
By default, jq outputs colored JSON if writing to a terminal\. You can force it to produce color even if writing to a pipe or a file using \fB\-C\fR, and disabl e color with \fB\-M\fR\. By default, jq outputs colored JSON if writing to a terminal\. You can force it to produce color even if writing to a pipe or a file using \fB\-C\fR, and disabl e color with \fB\-M\fR\.
. .
.IP
Colors can be configured with the \fBJQ_COLORS\fR environment variable (see belo
w)\.
.
.IP "\(bu" 4 .IP "\(bu" 4
\fB\-\-ascii\-output\fR / \fB\-a\fR: \fB\-\-ascii\-output\fR / \fB\-a\fR:
. .
.IP .IP
jq usually outputs non\-ASCII Unicode codepoints as UTF\-8, even if the input sp ecified them as escape sequences (like "\eu03bc")\. Using this option, you can f orce jq to produce pure ASCII output with every non\-ASCII character replaced wi th the equivalent escape sequence\. jq usually outputs non\-ASCII Unicode codepoints as UTF\-8, even if the input sp ecified them as escape sequences (like "\eu03bc")\. Using this option, you can f orce jq to produce pure ASCII output with every non\-ASCII character replaced wi th the equivalent escape sequence\.
. .
.IP "\(bu" 4 .IP "\(bu" 4
\fB\-\-unbuffered\fR \fB\-\-unbuffered\fR
. .
.IP .IP
skipping to change at line 156 skipping to change at line 159
. .
.IP .IP
Prepend \fBdirectory\fR to the search list for modules\. If this option is used then no builtin search list is used\. See the section on modules below\. Prepend \fBdirectory\fR to the search list for modules\. If this option is used then no builtin search list is used\. See the section on modules below\.
. .
.IP "\(bu" 4 .IP "\(bu" 4
\fB\-e\fR / \fB\-\-exit\-status\fR: \fB\-e\fR / \fB\-\-exit\-status\fR:
. .
.IP .IP
Sets the exit status of jq to 0 if the last output values was neither \fBfalse\f R nor \fBnull\fR, 1 if the last output value was either \fBfalse\fR or \fBnull\f R, or 4 if no valid result was ever produced\. Normally jq exits with 2 if there was any usage problem or system error, 3 if there was a jq program compile erro r, or 0 if the jq program ran\. Sets the exit status of jq to 0 if the last output values was neither \fBfalse\f R nor \fBnull\fR, 1 if the last output value was either \fBfalse\fR or \fBnull\f R, or 4 if no valid result was ever produced\. Normally jq exits with 2 if there was any usage problem or system error, 3 if there was a jq program compile erro r, or 0 if the jq program ran\.
. .
.IP
Another way to set the exit status is with the \fBhalt_error\fR builtin function
\.
.
.IP "\(bu" 4 .IP "\(bu" 4
\fB\-\-arg name value\fR: \fB\-\-arg name value\fR:
. .
.IP .IP
This option passes a value to the jq program as a predefined variable\. If you r un jq with \fB\-\-arg foo bar\fR, then \fB$foo\fR is available in the program an d has the value \fB"bar"\fR\. Note that \fBvalue\fR will be treated as a string, so \fB\-\-arg foo 123\fR will bind \fB$foo\fR to \fB"123"\fR\. This option passes a value to the jq program as a predefined variable\. If you r un jq with \fB\-\-arg foo bar\fR, then \fB$foo\fR is available in the program an d has the value \fB"bar"\fR\. Note that \fBvalue\fR will be treated as a string, so \fB\-\-arg foo 123\fR will bind \fB$foo\fR to \fB"123"\fR\.
. .
.IP
Named arguments are also available to the jq program as \fB$ARGS\.named\fR\.
.
.IP "\(bu" 4 .IP "\(bu" 4
\fB\-\-argjson name JSON\-text\fR: \fB\-\-argjson name JSON\-text\fR:
. .
.IP .IP
This option passes a JSON\-encoded value to the jq program as a predefined varia ble\. If you run jq with \fB\-\-argjson foo 123\fR, then \fB$foo\fR is available in the program and has the value \fB123\fR\. This option passes a JSON\-encoded value to the jq program as a predefined varia ble\. If you run jq with \fB\-\-argjson foo 123\fR, then \fB$foo\fR is available in the program and has the value \fB123\fR\.
. .
.IP "\(bu" 4 .IP "\(bu" 4
\fB\-\-slurpfile variable\-name filename\fR: \fB\-\-slurpfile variable\-name filename\fR:
. .
.IP .IP
skipping to change at line 184 skipping to change at line 193
.IP "\(bu" 4 .IP "\(bu" 4
\fB\-\-argfile variable\-name filename\fR: \fB\-\-argfile variable\-name filename\fR:
. .
.IP .IP
Do not use\. Use \fB\-\-slurpfile\fR instead\. Do not use\. Use \fB\-\-slurpfile\fR instead\.
. .
.IP .IP
(This option is like \fB\-\-slurpfile\fR, but when the file has just one text, t hen that is used, else an array of texts is used as in \fB\-\-slurpfile\fR\.) (This option is like \fB\-\-slurpfile\fR, but when the file has just one text, t hen that is used, else an array of texts is used as in \fB\-\-slurpfile\fR\.)
. .
.IP "\(bu" 4 .IP "\(bu" 4
\fB\-\-args\fR:
.
.IP
Remaining arguments are positional string arguments\. These are available to the
jq program as \fB$ARGS\.positional[]\fR\.
.
.IP "\(bu" 4
\fB\-\-jsonargs\fR:
.
.IP
Remaining arguments are positional JSON text arguments\. These are available to
the jq program as \fB$ARGS\.positional[]\fR\.
.
.IP "\(bu" 4
\fB\-\-run\-tests [filename]\fR: \fB\-\-run\-tests [filename]\fR:
. .
.IP .IP
Runs the tests in the given file or standard input\. This must be the last optio n given and does not honor all preceding options\. The input consists of comment lines, empty lines, and program lines followed by one input line, as many lines of output as are expected (one per output), and a terminating empty line\. Comp ilation failure tests start with a line containing only "%%FAIL", then a line co ntaining the program to compile, then a line containing an error message to comp are to the actual\. Runs the tests in the given file or standard input\. This must be the last optio n given and does not honor all preceding options\. The input consists of comment lines, empty lines, and program lines followed by one input line, as many lines of output as are expected (one per output), and a terminating empty line\. Comp ilation failure tests start with a line containing only "%%FAIL", then a line co ntaining the program to compile, then a line containing an error message to comp are to the actual\.
. .
.IP .IP
Be warned that this option can change backwards\-incompatibly\. Be warned that this option can change backwards\-incompatibly\.
. .
.IP "" 0 .IP "" 0
. .
.SH "BASIC FILTERS" .SH "BASIC FILTERS"
. .
.SS "\." .SS "Identity: \."
The absolute simplest (and least interesting) filter is \fB\.\fR\. This is a fil The absolute simplest filter is \fB\.\fR \. This is a filter that takes its inpu
ter that takes its input and produces it unchanged as output\. t and produces it unchanged as output\. That is, this is the identity operator\.
. .
.P .P
Since jq by default pretty\-prints all output, this trivial program can be a use ful way of formatting JSON output from, say, \fBcurl\fR\. Since jq by default pretty\-prints all output, this trivial program can be a use ful way of formatting JSON output from, say, \fBcurl\fR\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'\.\' jq \'\.\'
"Hello, world!" "Hello, world!"
=> "Hello, world!" => "Hello, world!"
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "\.foo, \.foo\.bar" .SS "Object Identifier\-Index: \.foo, \.foo\.bar"
The simplest \fIuseful\fR filter is \fB\.foo\fR\. When given a JSON object (aka dictionary or hash) as input, it produces the value at the key "foo", or null if there\'s none present\. The simplest \fIuseful\fR filter is \fB\.foo\fR\. When given a JSON object (aka dictionary or hash) as input, it produces the value at the key "foo", or null if there\'s none present\.
. .
.P .P
If the key contains special characters, you need to surround it with double quot es like this: \fB\."foo$"\fR\. A filter of the form \fB\.foo\.bar\fR is equivalent to \fB\.foo|\.bar\fR\.
. .
.P .P
A filter of the form \fB\.foo\.bar\fR is equivalent to \fB\.foo|\.bar\fR\. This syntax only works for simple, identifier\-like keys, that is, keys that are
all made of alphanumeric characters and underscore, and which do not start with
a digit\.
.
.P
If the key contains special characters, you need to surround it with double quot
es like this: \fB\."foo$"\fR, or else \fB\.["foo$"]\fR\.
.
.P
For example \fB\.["foo::bar"]\fR and \fB\.["foo\.bar"]\fR work while \fB\.foo::b
ar\fR does not, and \fB\.foo\.bar\fR means \fB\.["foo"]\.["bar"]\fR\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'\.foo\' jq \'\.foo\'
{"foo": 42, "bar": "less interesting data"} {"foo": 42, "bar": "less interesting data"}
=> 42 => 42
jq \'\.foo\' jq \'\.foo\'
skipping to change at line 243 skipping to change at line 270
=> null => null
jq \'\.["foo"]\' jq \'\.["foo"]\'
{"foo": 42} {"foo": 42}
=> 42 => 42
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "\.foo?" .SS "Optional Object Identifier\-Index: \.foo?"
Just like \fB\.foo\fR, but does not output even an error when \fB\.\fR is not an array or an object\. Just like \fB\.foo\fR, but does not output even an error when \fB\.\fR is not an array or an object\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'\.foo?\' jq \'\.foo?\'
{"foo": 42, "bar": "less interesting data"} {"foo": 42, "bar": "less interesting data"}
=> 42 => 42
skipping to change at line 270 skipping to change at line 297
=> 42 => 42
jq \'[\.foo?]\' jq \'[\.foo?]\'
[1,2] [1,2]
=> [] => []
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "\.[<string>], \.[2], \.[10:15]" .SS "Generic Object Index: \.[<string>]"
You can also look up fields of an object using syntax like \fB\.["foo"]\fR (\.fo You can also look up fields of an object using syntax like \fB\.["foo"]\fR (\.fo
o above is a shorthand version of this)\. This one works for arrays as well, if o above is a shorthand version of this, but only for identifier\-like strings)\.
the key is an integer\. Arrays are zero\-based (like javascript), so \fB\.[2]\fR
returns the third element of the array\.
.
.P
The \fB\.[10:15]\fR syntax can be used to return a subarray of an array or subst
ring of a string\. The array returned by \fB\.[10:15]\fR will be of length 5, co
ntaining the elements from index 10 (inclusive) to index 15 (exclusive)\. Either
index may be negative (in which case it counts backwards from the end of the ar
ray), or omitted (in which case it refers to the start or end of the array)\.
.
.P
The \fB\.[2]\fR syntax can be used to return the element at the given index\. Ne
gative indices are allowed, with \-1 referring to the last element, \-2 referrin
g to the next to last element, and so on\.
. .
.P .SS "Array Index: \.[2]"
The \fB\.foo\fR syntax only works for simply keys i\.e\. keys that are all alpha When the index value is an integer, \fB\.[<value>]\fR can index arrays\. Arrays
numeric characters\. \fB\.[<string>]\fR works with keys that contain special cha are zero\-based, so \fB\.[2]\fR returns the third element\.
racters such as colons and dots\. For example \fB\.["foo::bar"]\fR and \fB\.["fo
o\.bar"]\fR work while \fB\.foo::bar\fR and \fB\.foo\.bar\fR would not\.
. .
.P .P
The \fB?\fR "operator" can also be used with the slice operator, as in \fB\.[10: 15]?\fR, which outputs values where the inputs are slice\-able\. Negative indices are allowed, with \-1 referring to the last element, \-2 referr ing to the next to last element, and so on\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'\.[0]\' jq \'\.[0]\'
[{"name":"JSON", "good":true}, {"name":"XML", "good":false}] [{"name":"JSON", "good":true}, {"name":"XML", "good":false}]
=> {"name":"JSON", "good":true} => {"name":"JSON", "good":true}
jq \'\.[2]\' jq \'\.[2]\'
[{"name":"JSON", "good":true}, {"name":"XML", "good":false}] [{"name":"JSON", "good":true}, {"name":"XML", "good":false}]
=> null => null
jq \'\.[\-2]\'
[1,2,3]
=> 2
.
.fi
.
.IP "" 0
.
.SS "Array/String Slice: \.[10:15]"
The \fB\.[10:15]\fR syntax can be used to return a subarray of an array or subst
ring of a string\. The array returned by \fB\.[10:15]\fR will be of length 5, co
ntaining the elements from index 10 (inclusive) to index 15 (exclusive)\. Either
index may be negative (in which case it counts backwards from the end of the ar
ray), or omitted (in which case it refers to the start or end of the array)\.
.
.IP "" 4
.
.nf
jq \'\.[2:4]\' jq \'\.[2:4]\'
["a","b","c","d","e"] ["a","b","c","d","e"]
=> ["c", "d"] => ["c", "d"]
jq \'\.[2:4]\' jq \'\.[2:4]\'
"abcdefghi" "abcdefghi"
=> "cd" => "cd"
jq \'\.[:3]\' jq \'\.[:3]\'
["a","b","c","d","e"] ["a","b","c","d","e"]
=> ["a", "b", "c"] => ["a", "b", "c"]
jq \'\.[\-2:]\' jq \'\.[\-2:]\'
["a","b","c","d","e"] ["a","b","c","d","e"]
=> ["d", "e"] => ["d", "e"]
jq \'\.[\-2]\'
[1,2,3]
=> 2
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "\.[]" .SS "Array/Object Value Iterator: \.[]"
If you use the \fB\.[index]\fR syntax, but omit the index entirely, it will retu rn \fIall\fR of the elements of an array\. Running \fB\.[]\fR with the input \fB [1,2,3]\fR will produce the numbers as three separate results, rather than as a single array\. If you use the \fB\.[index]\fR syntax, but omit the index entirely, it will retu rn \fIall\fR of the elements of an array\. Running \fB\.[]\fR with the input \fB [1,2,3]\fR will produce the numbers as three separate results, rather than as a single array\.
. .
.P .P
You can also use this on an object, and it will return all the values of the obj ect\. You can also use this on an object, and it will return all the values of the obj ect\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'\.[]\' jq \'\.[]\'
skipping to change at line 350 skipping to change at line 382
{"a": 1, "b": 1} {"a": 1, "b": 1}
=> 1, 1 => 1, 1
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "\.[]?" .SS "\.[]?"
Like \fB\.[]\fR, but no errors will be output if \. is not an array or object\. Like \fB\.[]\fR, but no errors will be output if \. is not an array or object\.
. .
.SS "," .SS "Comma: ,"
If two filters are separated by a comma, then the input will be fed into both an If two filters are separated by a comma, then the same input will be fed into bo
d there will be multiple outputs: first, all of the outputs produced by the left th and the two filters\' output value streams will be concatenated in order: fir
expression, and then all of the outputs produced by the right\. For instance, f st, all of the outputs produced by the left expression, and then all of the outp
ilter \fB\.foo, \.bar\fR, produces both the "foo" fields and "bar" fields as sep uts produced by the right\. For instance, filter \fB\.foo, \.bar\fR, produces bo
arate outputs\. th the "foo" fields and "bar" fields as separate outputs\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'\.foo, \.bar\' jq \'\.foo, \.bar\'
{"foo": 42, "bar": "something else", "baz": true} {"foo": 42, "bar": "something else", "baz": true}
=> 42, "something else" => 42, "something else"
jq \'\.user, \.projects[]\' jq \'\.user, \.projects[]\'
skipping to change at line 373 skipping to change at line 405
=> "stedolan", "jq", "wikiflow" => "stedolan", "jq", "wikiflow"
jq \'\.[4,2]\' jq \'\.[4,2]\'
["a","b","c","d","e"] ["a","b","c","d","e"]
=> "e", "c" => "e", "c"
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "|" .SS "Pipe: |"
The | operator combines two filters by feeding the output(s) of the one on the l eft into the input of the one on the right\. It\'s pretty much the same as the U nix shell\'s pipe, if you\'re used to that\. The | operator combines two filters by feeding the output(s) of the one on the l eft into the input of the one on the right\. It\'s pretty much the same as the U nix shell\'s pipe, if you\'re used to that\.
. .
.P .P
If the one on the left produces multiple results, the one on the right will be r un for each of those results\. So, the expression \fB\.[] | \.foo\fR retrieves t he "foo" field of each element of the input array\. If the one on the left produces multiple results, the one on the right will be r un for each of those results\. So, the expression \fB\.[] | \.foo\fR retrieves t he "foo" field of each element of the input array\.
. .
.P
Note that \fB\.a\.b\.c\fR is the same as \fB\.a | \.b | \.c\fR\.
.
.P
Note too that \fB\.\fR is the input value at the particular stage in a "pipeline
", specifically: where the \fB\.\fR expression appears\. Thus \fB\.a | \. | \.b\
fR is the same as \fB\.a\.b\fR, as the \fB\.\fR in the middle refers to whatever
value \fB\.a\fR produced\.
.
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'\.[] | \.name\' jq \'\.[] | \.name\'
[{"name":"JSON", "good":true}, {"name":"XML", "good":false}] [{"name":"JSON", "good":true}, {"name":"XML", "good":false}]
=> "JSON", "XML" => "JSON", "XML"
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "Parenthesis"
Parenthesis work as a grouping operator just as in any typical programming langu
age\.
.
.IP "" 4
.
.nf
jq \'(\. + 2) * 5\'
1
=> 15
.
.fi
.
.IP "" 0
.
.SH "TYPES AND VALUES" .SH "TYPES AND VALUES"
jq supports the same set of datatypes as JSON \- numbers, strings, booleans, arr ays, objects (which in JSON\-speak are hashes with only string keys), and "null" \. jq supports the same set of datatypes as JSON \- numbers, strings, booleans, arr ays, objects (which in JSON\-speak are hashes with only string keys), and "null" \.
. .
.P .P
Booleans, null, strings and numbers are written the same way as in javascript\. Just like everything else in jq, these simple values take an input and produce a n output \- \fB42\fR is a valid jq expression that takes an input, ignores it, a nd returns 42 instead\. Booleans, null, strings and numbers are written the same way as in javascript\. Just like everything else in jq, these simple values take an input and produce a n output \- \fB42\fR is a valid jq expression that takes an input, ignores it, a nd returns 42 instead\.
. .
.SS "Array construction \- []" .SS "Array construction: []"
As in JSON, \fB[]\fR is used to construct arrays, as in \fB[1,2,3]\fR\. The elem As in JSON, \fB[]\fR is used to construct arrays, as in \fB[1,2,3]\fR\. The elem
ents of the arrays can be any jq expression\. All of the results produced by all ents of the arrays can be any jq expression, including a pipeline\. All of the r
of the expressions are collected into one big array\. You can use it to constru esults produced by all of the expressions are collected into one big array\. You
ct an array out of a known quantity of values (as in \fB[\.foo, \.bar, \.baz]\fR can use it to construct an array out of a known quantity of values (as in \fB[\
) or to "collect" all the results of a filter into an array (as in \fB[\.items[] .foo, \.bar, \.baz]\fR) or to "collect" all the results of a filter into an arra
\.name]\fR) y (as in \fB[\.items[]\.name]\fR)
. .
.P .P
Once you understand the "," operator, you can look at jq\'s array syntax in a di fferent light: the expression \fB[1,2,3]\fR is not using a built\-in syntax for comma\-separated arrays, but is instead applying the \fB[]\fR operator (collect results) to the expression 1,2,3 (which produces three different results)\. Once you understand the "," operator, you can look at jq\'s array syntax in a di fferent light: the expression \fB[1,2,3]\fR is not using a built\-in syntax for comma\-separated arrays, but is instead applying the \fB[]\fR operator (collect results) to the expression 1,2,3 (which produces three different results)\.
. .
.P .P
If you have a filter \fBX\fR that produces four results, then the expression \fB [X]\fR will produce a single result, an array of four elements\. If you have a filter \fBX\fR that produces four results, then the expression \fB [X]\fR will produce a single result, an array of four elements\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'[\.user, \.projects[]]\' jq \'[\.user, \.projects[]]\'
{"user":"stedolan", "projects": ["jq", "wikiflow"]} {"user":"stedolan", "projects": ["jq", "wikiflow"]}
=> ["stedolan", "jq", "wikiflow"] => ["stedolan", "jq", "wikiflow"]
jq \'[ \.[] | \. * 2]\'
[1, 2, 3]
=> [2, 4, 6]
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "Objects \- {}" .SS "Object Construction: {}"
Like JSON, \fB{}\fR is for constructing objects (aka dictionaries or hashes), as in: \fB{"a": 42, "b": 17}\fR\. Like JSON, \fB{}\fR is for constructing objects (aka dictionaries or hashes), as in: \fB{"a": 42, "b": 17}\fR\.
. .
.P .P
If the keys are "sensible" (all alphabetic characters), then the quotes can be l If the keys are "identifier\-like", then the quotes can be left off, as in \fB{a
eft off\. The value can be any expression (although you may need to wrap it in p :42, b:17}\fR\. Keys generated by expressions need to be parenthesized, e\.g\.,
arentheses if it\'s a complicated one), which gets applied to the {} expression\ \fB{("a"+"b"):59}\fR\.
's input (remember, all filters have an input and an output)\. .
.P
The value can be any expression (although you may need to wrap it in parentheses
if it\'s a complicated one), which gets applied to the {} expression\'s input (
remember, all filters have an input and an output)\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
{foo: \.bar} {foo: \.bar}
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .P
will produce the JSON object \fB{"foo": 42}\fR if given the JSON object \fB{"bar ":42, "baz":43}\fR\. You can use this to select particular fields of an object: if the input is an object with "user", "title", "id", and "content" fields and y ou just want "user" and "title", you can write will produce the JSON object \fB{"foo": 42}\fR if given the JSON object \fB{"bar ":42, "baz":43}\fR as its input\. You can use this to select particular fields o f an object: if the input is an object with "user", "title", "id", and "content" fields and you just want "user" and "title", you can write
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
{user: \.user, title: \.title} {user: \.user, title: \.title}
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .P
Because that\'s so common, there\'s a shortcut syntax: \fB{user, title}\fR\. Because that is so common, there\'s a shortcut syntax for it: \fB{user, title}\f R\.
. .
.P .P
If one of the expressions produces multiple results, multiple dictionaries will be produced\. If the input\'s If one of the expressions produces multiple results, multiple dictionaries will be produced\. If the input\'s
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
{"user":"stedolan","titles":["JQ Primer", "More JQ"]} {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
. .
skipping to change at line 524 skipping to change at line 584
=> {"user":"stedolan", "title": "JQ Primer"}, {"user":"stedolan", "title": "More JQ"} => {"user":"stedolan", "title": "JQ Primer"}, {"user":"stedolan", "title": "More JQ"}
jq \'{(\.user): \.titles}\' jq \'{(\.user): \.titles}\'
{"user":"stedolan","titles":["JQ Primer", "More JQ"]} {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
=> {"stedolan": ["JQ Primer", "More JQ"]} => {"stedolan": ["JQ Primer", "More JQ"]}
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "Recursive Descent: \.\."
Recursively descends \fB\.\fR, producing every value\. This is the same as the z
ero\-argument \fBrecurse\fR builtin (see below)\. This is intended to resemble t
he XPath \fB//\fR operator\. Note that \fB\.\.a\fR does not work; use \fB\.\.|\.
a\fR instead\. In the example below we use \fB\.\.|\.a?\fR to find all the value
s of object keys "a" in any object found "below" \fB\.\fR\.
.
.P
This is particularly useful in conjunction with \fBpath(EXP)\fR (also see below)
and the \fB?\fR operator\.
.
.IP "" 4
.
.nf
jq \'\.\.|\.a?\'
[[{"a":1}]]
=> 1
.
.fi
.
.IP "" 0
.
.SH "BUILTIN OPERATORS AND FUNCTIONS" .SH "BUILTIN OPERATORS AND FUNCTIONS"
Some jq operator (for instance, \fB+\fR) do different things depending on the ty pe of their arguments (arrays, numbers, etc\.)\. However, jq never does implicit type conversions\. If you try to add a string to an object you\'ll get an error message and no result\. Some jq operator (for instance, \fB+\fR) do different things depending on the ty pe of their arguments (arrays, numbers, etc\.)\. However, jq never does implicit type conversions\. If you try to add a string to an object you\'ll get an error message and no result\.
. .
.SS "Addition \- +" .SS "Addition: +"
The operator \fB+\fR takes two filters, applies them both to the same input, and adds the results together\. What "adding" means depends on the types involved: The operator \fB+\fR takes two filters, applies them both to the same input, and adds the results together\. What "adding" means depends on the types involved:
. .
.IP "\(bu" 4 .IP "\(bu" 4
\fBNumbers\fR are added by normal arithmetic\. \fBNumbers\fR are added by normal arithmetic\.
. .
.IP "\(bu" 4 .IP "\(bu" 4
\fBArrays\fR are added by being concatenated into a larger array\. \fBArrays\fR are added by being concatenated into a larger array\.
. .
.IP "\(bu" 4 .IP "\(bu" 4
\fBStrings\fR are added by being joined into a larger string\. \fBStrings\fR are added by being joined into a larger string\.
skipping to change at line 575 skipping to change at line 653
=> 1 => 1
jq \'{a: 1} + {b: 2} + {c: 3} + {a: 42}\' jq \'{a: 1} + {b: 2} + {c: 3} + {a: 42}\'
null null
=> {"a": 42, "b": 2, "c": 3} => {"a": 42, "b": 2, "c": 3}
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "Subtraction \- \-" .SS "Subtraction: \-"
As well as normal arithmetic subtraction on numbers, the \fB\-\fR operator can b e used on arrays to remove all occurrences of the second array\'s elements from the first array\. As well as normal arithmetic subtraction on numbers, the \fB\-\fR operator can b e used on arrays to remove all occurrences of the second array\'s elements from the first array\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'4 \- \.a\' jq \'4 \- \.a\'
{"a":3} {"a":3}
=> 1 => 1
jq \'\. \- ["xml", "yaml"]\' jq \'\. \- ["xml", "yaml"]\'
["xml", "yaml", "json"] ["xml", "yaml", "json"]
=> ["json"] => ["json"]
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "Multiplication, division, modulo \- *, /, and %" .SS "Multiplication, division, modulo: *, /, and %"
These infix operators behave as expected when given two numbers\. Division by ze ro raises an error\. \fBx % y\fR computes x modulo y\. These infix operators behave as expected when given two numbers\. Division by ze ro raises an error\. \fBx % y\fR computes x modulo y\.
. .
.P .P
Multiplying a string by a number produces the concatenation of that string that many times\. \fB"x" * 0\fR produces \fBnull\fR\. Multiplying a string by a number produces the concatenation of that string that many times\. \fB"x" * 0\fR produces \fBnull\fR\.
. .
.P .P
Dividing a string by another splits the first using the second as separators\. Dividing a string by another splits the first using the second as separators\.
. .
.P .P
Multiplying two objects will merge them recursively: this works like addition bu t if both objects contain a value for the same key, and the values are objects, the two are merged with the same strategy\. Multiplying two objects will merge them recursively: this works like addition bu t if both objects contain a value for the same key, and the values are objects, the two are merged with the same strategy\.
skipping to change at line 650 skipping to change at line 728
The length of an \fBobject\fR is the number of key\-value pairs\. The length of an \fBobject\fR is the number of key\-value pairs\.
. .
.IP "\(bu" 4 .IP "\(bu" 4
The length of \fBnull\fR is zero\. The length of \fBnull\fR is zero\.
. .
.IP .IP
jq \'\.[] | length\' [[1,2], "string", {"a":2}, null] => 2, 6, 1, 0 jq \'\.[] | length\' [[1,2], "string", {"a":2}, null] => 2, 6, 1, 0
. .
.IP "" 0 .IP "" 0
. .
.SS "utf8bytelength"
The builtin function \fButf8bytelength\fR outputs the number of bytes used to en
code a string in UTF\-8\.
.
.IP "" 4
.
.nf
jq \'utf8bytelength\'
"\eu03bc"
=> 2
.
.fi
.
.IP "" 0
.
.SS "keys, keys_unsorted" .SS "keys, keys_unsorted"
The builtin function \fBkeys\fR, when given an object, returns its keys in an ar ray\. The builtin function \fBkeys\fR, when given an object, returns its keys in an ar ray\.
. .
.P .P
The keys are sorted "alphabetically", by unicode codepoint order\. This is not a n order that makes particular sense in any particular language, but you can coun t on it being the same for any two objects with the same set of keys, regardless of locale settings\. The keys are sorted "alphabetically", by unicode codepoint order\. This is not a n order that makes particular sense in any particular language, but you can coun t on it being the same for any two objects with the same set of keys, regardless of locale settings\.
. .
.P .P
When \fBkeys\fR is given an array, it returns the valid indices for that array: the integers from 0 to length\-1\. When \fBkeys\fR is given an array, it returns the valid indices for that array: the integers from 0 to length\-1\.
. .
.P .P
skipping to change at line 701 skipping to change at line 794
jq \'map(has(2))\' jq \'map(has(2))\'
[[0,1], ["a","b","c"]] [[0,1], ["a","b","c"]]
=> [false, true] => [false, true]
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "in" .SS "in"
The builtin function \fBin\fR returns the input key is in the given object, or t he input index corresponds to an element in the given array\. It is, essentially , an inversed version of \fBhas\fR\. The builtin function \fBin\fR returns whether or not the input key is in the giv en object, or the input index corresponds to an element in the given array\. It is, essentially, an inversed version of \fBhas\fR\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'\.[] | in({"foo": 42})\' jq \'\.[] | in({"foo": 42})\'
["foo", "bar"] ["foo", "bar"]
=> true, false => true, false
jq \'map(in([0,1]))\' jq \'map(in([0,1]))\'
[2, 0] [2, 0]
=> [false, true] => [false, true]
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "map(x), map_values(x)"
For any filter \fBx\fR, \fBmap(x)\fR will run that filter for each element of th
e input array, and return the outputs in a new array\. \fBmap(\.+1)\fR will incr
ement each element of an array of numbers\.
.
.P
Similarly, \fBmap_values(x)\fR will run that filter for each element, but it wil
l return an object when an object is passed\.
.
.P
\fBmap(x)\fR is equivalent to \fB[\.[] | x]\fR\. In fact, this is how it\'s defi
ned\. Similarly, \fBmap_values(x)\fR is defined as \fB\.[] |= x\fR\.
.
.IP "" 4
.
.nf
jq \'map(\.+1)\'
[1,2,3]
=> [2,3,4]
jq \'map_values(\.+1)\'
{"a": 1, "b": 2, "c": 3}
=> {"a": 2, "b": 3, "c": 4}
.
.fi
.
.IP "" 0
.
.SS "path(path_expression)" .SS "path(path_expression)"
Outputs array representations of the given path expression in \fB\.\fR\. The out puts are arrays of strings (keys in objects0 and/or numbers (array indices\. Outputs array representations of the given path expression in \fB\.\fR\. The out puts are arrays of strings (object keys) and/or numbers (array indices)\.
. .
.P .P
Path expressions are jq expressions like \fB\.a\fR, but also \fB\.[]\fR\. There are two types of path expressions: ones that can match exactly, and ones that ca nnot\. For example, \fB\.a\.b\.c\fR is an exact match path expression, while \fB \.a[]\.b\fR is not\. Path expressions are jq expressions like \fB\.a\fR, but also \fB\.[]\fR\. There are two types of path expressions: ones that can match exactly, and ones that ca nnot\. For example, \fB\.a\.b\.c\fR is an exact match path expression, while \fB \.a[]\.b\fR is not\.
. .
.P .P
\fBpath(exact_path_expression)\fR will produce the array representation of the p ath expression even if it does not exist in \fB\.\fR, if \fB\.\fR is \fBnull\fR or an array or an object\. \fBpath(exact_path_expression)\fR will produce the array representation of the p ath expression even if it does not exist in \fB\.\fR, if \fB\.\fR is \fBnull\fR or an array or an object\.
. .
.P .P
\fBpath(pattern)\fR will produce array representations of the paths matching \fB pattern\fR if the paths exist in \fB\.\fR\. \fBpath(pattern)\fR will produce array representations of the paths matching \fB pattern\fR if the paths exist in \fB\.\fR\.
. .
skipping to change at line 769 skipping to change at line 887
=> {"bar": 9001, "baz": 42} => {"bar": 9001, "baz": 42}
jq \'del(\.[1, 2])\' jq \'del(\.[1, 2])\'
["foo", "bar", "baz"] ["foo", "bar", "baz"]
=> ["foo"] => ["foo"]
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "getpath(PATHS)"
The builtin function \fBgetpath\fR outputs the values in \fB\.\fR found at each
path in \fBPATHS\fR\.
.
.IP "" 4
.
.nf
jq \'getpath(["a","b"])\'
null
=> null
jq \'[getpath(["a","b"], ["a","c"])]\'
{"a":{"b":0, "c":1}}
=> [0, 1]
.
.fi
.
.IP "" 0
.
.SS "setpath(PATHS; VALUE)"
The builtin function \fBsetpath\fR sets the \fBPATHS\fR in \fB\.\fR to \fBVALUE\
fR\.
.
.IP "" 4
.
.nf
jq \'setpath(["a","b"]; 1)\'
null
=> {"a": {"b": 1}}
jq \'setpath(["a","b"]; 1)\'
{"a":{"b":0}}
=> {"a": {"b": 1}}
jq \'setpath([0,"a"]; 1)\'
null
=> [{"a":1}]
.
.fi
.
.IP "" 0
.
.SS "delpaths(PATHS)"
The builtin function \fBdelpaths\fR sets the \fBPATHS\fR in \fB\.\fR\. \fBPATHS\
fR must be an array of paths, where each path is an array of strings and numbers
\.
.
.IP "" 4
.
.nf
jq \'delpaths([["a","b"]])\'
{"a":{"b":1},"x":{"y":2}}
=> {"a":{},"x":{"y":2}}
.
.fi
.
.IP "" 0
.
.SS "to_entries, from_entries, with_entries" .SS "to_entries, from_entries, with_entries"
These functions convert between an object and an array of key\-value pairs\. If \fBto_entries\fR is passed an object, then for each \fBk: v\fR entry in the inpu t, the output array includes \fB{"key": k, "value": v}\fR\. These functions convert between an object and an array of key\-value pairs\. If \fBto_entries\fR is passed an object, then for each \fBk: v\fR entry in the inpu t, the output array includes \fB{"key": k, "value": v}\fR\.
. .
.P .P
\fBfrom_entries\fR does the opposite conversion, and \fBwith_entries(foo)\fR is a shorthand for \fBto_entries | map(foo) | from_entries\fR, useful for doing som e operation to all keys and values of an object\. \fBfrom_entries\fR accepts key , Key, Name, value and Value as keys\. \fBfrom_entries\fR does the opposite conversion, and \fBwith_entries(foo)\fR is a shorthand for \fBto_entries | map(foo) | from_entries\fR, useful for doing som e operation to all keys and values of an object\. \fBfrom_entries\fR accepts key , Key, name, Name, value and Value as keys\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'to_entries\' jq \'to_entries\'
{"a": 1, "b": 2} {"a": 1, "b": 2}
=> [{"key":"a", "value":1}, {"key":"b", "value":2}] => [{"key":"a", "value":1}, {"key":"b", "value":2}]
jq \'from_entries\' jq \'from_entries\'
skipping to change at line 855 skipping to change at line 1030
jq \'[1,2,empty,3]\' jq \'[1,2,empty,3]\'
null null
=> [1,2,3] => [1,2,3]
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "error(message)" .SS "error(message)"
Produces an error, just like \fB\.a\fR applied to values other than null and obj ects would, but with the given message as the error\'s value\. Produces an error, just like \fB\.a\fR applied to values other than null and obj ects would, but with the given message as the error\'s value\. Errors can be cau ght with try/catch; see below\.
. .
.SS "$__loc__" .SS "halt"
Produces an object with a "file" key and a "line" key, with the filename and lin Stops the jq program with no further outputs\. jq will exit with exit status \fB
e number where \fB$__loc__\fR occurs, as values\. 0\fR\.
. .
.IP "" 4 .SS "halt_error, halt_error(exit_code)"
. Stops the jq program with no further outputs\. The input will be printed on \fBs
.nf tderr\fR as raw output (i\.e\., strings will not have double quotes) with no dec
oration, not even a newline\.
jq \'try error("\e($__loc__)") catch \.\'
null
=> "{\e"file\e":\e"<top\-level>\e",\e"line\e":1}"
.
.fi
.
.IP "" 0
.
.SS "map(x), map_values(x)"
For any filter \fBx\fR, \fBmap(x)\fR will run that filter for each element of th
e input array, and produce the outputs a new array\. \fBmap(\.+1)\fR will increm
ent each element of an array of numbers\.
. .
.P .P
Similarly, \fBmap_values(x)\fR will run that filter for each element, but it wil l return an object when an object is passed\. The given \fBexit_code\fR (defaulting to \fB5\fR) will be jq\'s exit status\.
. .
.P .P
\fBmap(x)\fR is equivalent to \fB[\.[] | x]\fR\. In fact, this is how it\'s defi For example, \fB"Error: somthing went wrong\en"|halt_error(1)\fR\.
ned\. Similarly, \fBmap_values(x)\fR is defined as \fB\.[] |= x\fR\. .
.SS "$__loc__"
Produces an object with a "file" key and a "line" key, with the filename and lin
e number where \fB$__loc__\fR occurs, as values\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'map(\.+1)\' jq \'try error("\e($__loc__)") catch \.\'
[1,2,3] null
=> [2,3,4] => "{\e"file\e":\e"<top\-level>\e",\e"line\e":1}"
jq \'map_values(\.+1)\'
{"a": 1, "b": 2, "c": 3}
=> {"a": 2, "b": 3, "c": 4}
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "paths, paths(node_filter), leaf_paths" .SS "paths, paths(node_filter), leaf_paths"
\fBpaths\fR outputs the paths to all the elements in its input (except it does n ot output the empty list, representing \. itself)\. \fBpaths\fR outputs the paths to all the elements in its input (except it does n ot output the empty list, representing \. itself)\.
. .
.P .P
\fBpaths(f)\fR outputs the paths to any values for which \fBf\fR is true\. That is, \fBpaths(numbers)\fR outputs the paths to all numeric values\. \fBpaths(f)\fR outputs the paths to any values for which \fBf\fR is true\. That is, \fBpaths(numbers)\fR outputs the paths to all numeric values\.
skipping to change at line 949 skipping to change at line 1111
jq \'add\' jq \'add\'
[] []
=> null => null
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "any, any(condition), any(generator; condition)" .SS "any, any(condition), any(generator; condition)"
The filter \fBany\fR takes as input an array of boolean values, and produces \fB true\fR as output if any of the the elements of the array is \fBtrue\fR\. The filter \fBany\fR takes as input an array of boolean values, and produces \fB true\fR as output if any of the elements of the array are \fBtrue\fR\.
. .
.P .P
If the input is an empty array, \fBany\fR returns \fBfalse\fR\. If the input is an empty array, \fBany\fR returns \fBfalse\fR\.
. .
.P .P
The \fBany(condition)\fR form applies the given condition to the elements of the input array\. The \fBany(condition)\fR form applies the given condition to the elements of the input array\.
. .
.P .P
The \fBany(generator; condition)\fR form applies the given condition to all the outputs of the given generator\. The \fBany(generator; condition)\fR form applies the given condition to all the outputs of the given generator\.
. .
skipping to change at line 981 skipping to change at line 1143
jq \'any\' jq \'any\'
[] []
=> false => false
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "all, all(condition), all(generator; condition)" .SS "all, all(condition), all(generator; condition)"
The filter \fBall\fR takes as input an array of boolean values, and produces \fB true\fR as output if all of the the elements of the array are \fBtrue\fR\. The filter \fBall\fR takes as input an array of boolean values, and produces \fB true\fR as output if all of the elements of the array are \fBtrue\fR\.
. .
.P .P
The \fBall(condition)\fR form applies the given condition to the elements of the input array\. The \fBall(condition)\fR form applies the given condition to the elements of the input array\.
. .
.P .P
The \fBall(generator; condition)\fR form applies the given condition to all the outputs of the given generator\. The \fBall(generator; condition)\fR form applies the given condition to all the outputs of the given generator\.
. .
.P .P
If the input is an empty array, \fBall\fR returns \fBtrue\fR\. If the input is an empty array, \fBall\fR returns \fBtrue\fR\.
. .
skipping to change at line 1012 skipping to change at line 1174
=> true => true
jq \'all\' jq \'all\'
[] []
=> true => true
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "[Requires 1\.5] flatten, flatten(depth)" .SS "flatten, flatten(depth)"
The filter \fBflatten\fR takes as input an array of nested arrays, and produces a flat array in which all arrays inside the original array have been recursively replaced by their values\. You can pass an argument to it to specify how many l evels of nesting to flatten\. The filter \fBflatten\fR takes as input an array of nested arrays, and produces a flat array in which all arrays inside the original array have been recursively replaced by their values\. You can pass an argument to it to specify how many l evels of nesting to flatten\.
. .
.P .P
\fBflatten(2)\fR is like \fBflatten\fR, but going only up to two levels deep\. \fBflatten(2)\fR is like \fBflatten\fR, but going only up to two levels deep\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'flatten\' jq \'flatten\'
skipping to change at line 1531 skipping to change at line 1693
.nf .nf
jq \'implode\' jq \'implode\'
[65, 66, 67] [65, 66, 67]
=> "ABC" => "ABC"
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "split" .SS "split(str)"
Splits an input string on the separator argument\. Splits an input string on the separator argument\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'split(", ")\' jq \'split(", ")\'
"a, b,c,d, e, " "a, b,c,d, e, "
=> ["a","b,c,d","e",""] => ["a","b,c,d","e",""]
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "join(str)" .SS "join(str)"
Joins the array of elements given as input, using the argument as separator\. It is the inverse of \fBsplit\fR: that is, running \fBsplit("foo") | join("foo")\f R over any input string returns said input string\. Joins the array of elements given as input, using the argument as separator\. It is the inverse of \fBsplit\fR: that is, running \fBsplit("foo") | join("foo")\f R over any input string returns said input string\.
. .
.P
Numbers and booleans in the input are converted to strings\. Null values are tre
ated as empty strings\. Arrays and objects in the input are not supported\.
.
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'join(", ")\' jq \'join(", ")\'
["a","b,c,d","e"] ["a","b,c,d","e"]
=> "a, b,c,d, e" => "a, b,c,d, e"
jq \'join(" ")\'
["a",1,2\.3,true,null,false]
=> "a 1 2\.3 true false"
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "ascii_downcase, ascii_upcase" .SS "ascii_downcase, ascii_upcase"
Emit a copy of the input string with its alphabetic characters (a\-z and A\-Z) c onverted to the specified case\. Emit a copy of the input string with its alphabetic characters (a\-z and A\-Z) c onverted to the specified case\.
. .
.SS "while(cond; update)" .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\. The \fBwhile(cond; update)\fR function allows you to repeatedly apply an update to \fB\.\fR until \fBcond\fR is false\.
skipping to change at line 1667 skipping to change at line 1836
=> {"a":0,"b":[1]}, 0, [1], 1 => {"a":0,"b":[1]}, 0, [1], 1
jq \'recurse(\. * \.; \. < 20)\' jq \'recurse(\. * \.; \. < 20)\'
2 2
=> 2, 4, 16 => 2, 4, 16
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "\.\." .SS "walk(f)"
Short\-hand for \fBrecurse\fR without arguments\. This is intended to resemble t The \fBwalk(f)\fR function applies f recursively to every component of the input
he XPath \fB//\fR operator\. Note that \fB\.\.a\fR does not work; use \fB\.\.|a\ entity\. When an array is encountered, f is first applied to its elements and t
fR instead\. In the example below we use \fB\.\.|\.a?\fR to find all the values hen to the array itself; when an object is encountered, f is first applied to al
of object keys "a" in any object found "below" \fB\.\fR\. l the values and then to the object\. In practice, f will usually test the type
of its input, as illustrated in the following examples\. The first example highl
ights the usefulness of processing the elements of an array of arrays before pro
cessing the array itself\. The second example shows how all the keys of all the
objects within the input can be considered for alteration\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'\.\.|\.a?\' jq \'walk(if type == "array" then sort else \. end)\'
[[{"a":1}]] [[4, 1, 7], [8, 5, 2], [3, 6, 9]]
=> 1 => [[1,4,7],[2,5,8],[3,6,9]]
jq \'walk( if type == "object" then with_entries( \.key |= sub( "^_+"; "") ) els
e \. end )\'
[ { "_a": { "__b": 2 } } ]
=> [{"a":{"b":2}}]
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "env" .SS "$ENV, env"
Outputs an object representing jq\'s environment\. \fB$ENV\fR is an object representing the environment variables as set when the j
q program started\.
.
.P
\fBenv\fR outputs an object representing jq\'s current environment\.
.
.P
At the moment there is no builtin for setting environment variables\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'$ENV\.PAGER\'
null
=> "less"
jq \'env\.PAGER\' jq \'env\.PAGER\'
null null
=> "less" => "less"
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "transpose" .SS "transpose"
Transpose a possibly jagged matrix (an array of arrays)\. Rows are padded with n ulls so the result is always rectangular\. Transpose a possibly jagged matrix (an array of arrays)\. Rows are padded with n ulls so the result is always rectangular\.
skipping to change at line 1824 skipping to change at line 2007
. .
.IP .IP
The input is escaped suitable for use in a command\-line for a POSIX shell\. If the input is an array, the output will be a series of space\-separated strings\. The input is escaped suitable for use in a command\-line for a POSIX shell\. If the input is an array, the output will be a series of space\-separated strings\.
. .
.TP .TP
\fB@base64\fR: \fB@base64\fR:
. .
.IP .IP
The input is converted to base64 as specified by RFC 4648\. The input is converted to base64 as specified by RFC 4648\.
. .
.TP
\fB@base64d\fR:
.
.IP
The inverse of \fB@base64\fR, input is decoded as specified by RFC 4648\. Note:
If the decoded string is not UTF\-8, the results are undefined\.
.
.P .P
This syntax can be combined with string interpolation in a useful way\. You can follow a \fB@foo\fR token with a string literal\. The contents of the string lit eral will \fInot\fR be escaped\. However, all interpolations made inside that st ring literal will be escaped\. For instance, This syntax can be combined with string interpolation in a useful way\. You can follow a \fB@foo\fR token with a string literal\. The contents of the string lit eral will \fInot\fR be escaped\. However, all interpolations made inside that st ring literal will be escaped\. For instance,
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
@uri "https://www\.google\.com/search?q=\e(\.search)" @uri "https://www\.google\.com/search?q=\e(\.search)"
. .
.fi .fi
skipping to change at line 1864 skipping to change at line 2053
. .
.nf .nf
jq \'@html\' jq \'@html\'
"This works if x < y" "This works if x < y"
=> "This works if x &lt; y" => "This works if x &lt; y"
jq \'@sh "echo \e(\.)"\' jq \'@sh "echo \e(\.)"\'
"O\'Hara\'s Ale" "O\'Hara\'s Ale"
=> "echo \'O\'\e\e\'\'Hara\'\e\e\'\'s Ale\'" => "echo \'O\'\e\e\'\'Hara\'\e\e\'\'s Ale\'"
jq \'@base64\'
"This is a message"
=> "VGhpcyBpcyBhIG1lc3NhZ2U="
jq \'@base64d\'
"VGhpcyBpcyBhIG1lc3NhZ2U="
=> "This is a message"
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "Dates" .SS "Dates"
jq provides some basic date handling functionality, with some high\-level and lo w\-level builtins\. In all cases these builtins deal exclusively with time in UT C\. jq provides some basic date handling functionality, with some high\-level and lo w\-level builtins\. In all cases these builtins deal exclusively with time in UT C\.
. .
.P .P
The \fBfromdateiso8601\fR builtin parses datetimes in the ISO 8601 format to a n umber of seconds since the Unix epoch (1970\-01\-01T00:00:00Z)\. The \fBtodateis o8601\fR builtin does the inverse\. The \fBfromdateiso8601\fR builtin parses datetimes in the ISO 8601 format to a n umber of seconds since the Unix epoch (1970\-01\-01T00:00:00Z)\. The \fBtodateis o8601\fR builtin does the inverse\.
skipping to change at line 1885 skipping to change at line 2082
.P .P
The \fBfromdate\fR builtin parses datetime strings\. Currently \fBfromdate\fR on ly supports ISO 8601 datetime strings, but in the future it will attempt to pars e datetime strings in more formats\. The \fBfromdate\fR builtin parses datetime strings\. Currently \fBfromdate\fR on ly supports ISO 8601 datetime strings, but in the future it will attempt to pars e datetime strings in more formats\.
. .
.P .P
The \fBtodate\fR builtin is an alias for \fBtodateiso8601\fR\. The \fBtodate\fR builtin is an alias for \fBtodateiso8601\fR\.
. .
.P .P
The \fBnow\fR builtin outputs the current time, in seconds since the Unix epoch\ . The \fBnow\fR builtin outputs the current time, in seconds since the Unix epoch\ .
. .
.P .P
Low\-level jq interfaces to the C\-library time functions are also provided: \fB Low\-level jq interfaces to the C\-library time functions are also provided: \fB
strptime\fR, \fBstrftime\fR, \fBmktime\fR, and \fBgmtime\fR\. Refer to your host strptime\fR, \fBstrftime\fR, \fBstrflocaltime\fR, \fBmktime\fR, \fBgmtime\fR, an
operating system\'s documentation for the format strings used by \fBstrptime\fR d \fBlocaltime\fR\. Refer to your host operating system\'s documentation for the
and \fBstrftime\fR\. Note: these are not necessarily stable interfaces in jq, p format strings used by \fBstrptime\fR and \fBstrftime\fR\. Note: these are not
articularly as to their localization functionality\. necessarily stable interfaces in jq, particularly as to their localization funct
ionality\.
.
.P
The \fBgmtime\fR builtin consumes a number of seconds since the Unix epoch and o
utputs a "broken down time" representation of Greenwhich Meridian time as an arr
ay of numbers representing (in this order): the year, the month (zero\-based), t
he day of the month (one\-based), the hour of the day, the minute of the hour, t
he second of the minute, the day of the week, and the day of the year \-\- all o
ne\-based unless otherwise stated\. The day of the week number may be wrong on s
ome systems for dates before March 1st 1900, or after December 31 2099\.
. .
.P .P
The \fBgmtime\fR builtin consumes a number of seconds since the Unix epoch and o utputs a "broken down time" representation of time as an array of numbers repres enting (in this order): the year, the month (zero\-based), the day of the month, the hour of the day, the minute of the hour, the second of the minute, the day of the week, and the day of the year \-\- all one\-based unless otherwise stated \. The \fBlocaltime\fR builtin works like the \fBgmtime\fR builtin, but using the l ocal timezone setting\.
. .
.P .P
The \fBmktime\fR builtin consumes "broken down time" representations of time out put by \fBgmtime\fR and \fBstrptime\fR\. The \fBmktime\fR builtin consumes "broken down time" representations of time out put by \fBgmtime\fR and \fBstrptime\fR\.
. .
.P .P
The \fBstrptime(fmt)\fR builtin parses input strings matching the \fBfmt\fR argu ment\. The output is in the "broken down time" representation consumed by \fBgmt ime\fR and output by \fBmktime\fR\. The \fBstrptime(fmt)\fR builtin parses input strings matching the \fBfmt\fR argu ment\. The output is in the "broken down time" representation consumed by \fBgmt ime\fR and output by \fBmktime\fR\.
. .
.P .P
The \fBstrftime(fmt)\fR builtin formats a time with the given format\. The \fBstrftime(fmt)\fR builtin formats a time (GMT) with the given format\. The \fBstrflocaltime\fR does the same, but using the local timezone setting\.
. .
.P .P
The format strings for \fBstrptime\fR and \fBstrftime\fR are described in typica l C library documentation\. The format string for ISO 8601 datetime is \fB"%Y\-% m\-%dT%H:%M:%SZ"\fR\. The format strings for \fBstrptime\fR and \fBstrftime\fR are described in typica l C library documentation\. The format string for ISO 8601 datetime is \fB"%Y\-% m\-%dT%H:%M:%SZ"\fR\.
. .
.P .P
jq may not support some or all of this date functionality on some systems\. jq may not support some or all of this date functionality on some systems\. In p articular, the \fB%u\fR and \fB%j\fR specifiers for \fBstrptime(fmt)\fR are not supported on macOS\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'fromdate\' jq \'fromdate\'
"2015\-03\-05T23:51:47Z" "2015\-03\-05T23:51:47Z"
=> 1425599507 => 1425599507
jq \'strptime("%Y\-%m\-%dT%H:%M:%SZ")\' jq \'strptime("%Y\-%m\-%dT%H:%M:%SZ")\'
skipping to change at line 1925 skipping to change at line 2125
=> [2015,2,5,23,51,47,4,63] => [2015,2,5,23,51,47,4,63]
jq \'strptime("%Y\-%m\-%dT%H:%M:%SZ")|mktime\' jq \'strptime("%Y\-%m\-%dT%H:%M:%SZ")|mktime\'
"2015\-03\-05T23:51:47Z" "2015\-03\-05T23:51:47Z"
=> 1425599507 => 1425599507
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "SQL\-Style Operators"
jq provides a few SQL\-style operators\.
.
.TP
INDEX(stream; index_expression):
.
.IP
This builtin produces an object whose keys are computed by the given index expre
ssion applied to each value from the given stream\.
.
.TP
JOIN($idx; stream; idx_expr; join_expr):
.
.IP
This builtin joins the values from the given stream to the given index\. The ind
ex\'s keys are computed by applying the given index expression to each value fro
m the given stream\. An array of the value in the stream and the corresponding v
alue from the index is fed to the given join expression to produce each result\.
.
.TP
JOIN($idx; stream; idx_expr):
.
.IP
Same as \fBJOIN($idx; stream; idx_expr; \.)\fR\.
.
.TP
JOIN($idx; idx_expr):
.
.IP
This builtin joins the input \fB\.\fR to the given index, applying the given ind
ex expression to \fB\.\fR to compute the index key\. The join operation is as de
scribed above\.
.
.TP
IN(s):
.
.IP
This builtin outputs \fBtrue\fR if \fB\.\fR appears in the given stream, otherwi
se it outputs \fBfalse\fR\.
.
.TP
IN(source; s):
.
.IP
This builtin outputs \fBtrue\fR if any value in the source stream appears in the
second stream, otherwise it outputs \fBfalse\fR\.
.
.SS "builtins"
Returns a list of all builtin functions in the format \fBname/arity\fR\. Since f
unctions with the same name but different arities are considered separate functi
ons, \fBall/0\fR, \fBall/1\fR, and \fBall/2\fR would all be present in the list\
.
.
.SH "CONDITIONALS AND COMPARISONS" .SH "CONDITIONALS AND COMPARISONS"
. .
.SS "==, !=" .SS "==, !="
The expression \'a == b\' will produce \'true\' if the result of a and b are equ al (that is, if they represent equivalent JSON documents) and \'false\' otherwis e\. In particular, strings are never considered equal to numbers\. If you\'re co ming from Javascript, jq\'s == is like Javascript\'s === \- considering values e qual only when they have the same type as well as the same value\. The expression \'a == b\' will produce \'true\' if the result of a and b are equ al (that is, if they represent equivalent JSON documents) and \'false\' otherwis e\. In particular, strings are never considered equal to numbers\. If you\'re co ming from Javascript, jq\'s == is like Javascript\'s === \- considering values e qual only when they have the same type as well as the same value\.
. .
.P .P
!= is "not equal", and \'a != b\' returns the opposite value of \'a == b\' != is "not equal", and \'a != b\' returns the opposite value of \'a == b\'
. .
.IP "" 4 .IP "" 4
. .
skipping to change at line 1952 skipping to change at line 2194
. .
.IP "" 0 .IP "" 0
. .
.SS "if\-then\-else" .SS "if\-then\-else"
\fBif A then B else C end\fR will act the same as \fBB\fR if \fBA\fR produces a value other than false or null, but act the same as \fBC\fR otherwise\. \fBif A then B else C end\fR will act the same as \fBB\fR if \fBA\fR produces a value other than false or null, but act the same as \fBC\fR otherwise\.
. .
.P .P
Checking for false or null is a simpler notion of "truthiness" than is found in Javascript or Python, but it means that you\'ll sometimes have to be more explic it about the condition you want: you can\'t test whether, e\.g\. a string is emp ty using \fBif \.name then A else B end\fR, you\'ll need something more like \fB if (\.name | length) > 0 then A else B end\fR instead\. Checking for false or null is a simpler notion of "truthiness" than is found in Javascript or Python, but it means that you\'ll sometimes have to be more explic it about the condition you want: you can\'t test whether, e\.g\. a string is emp ty using \fBif \.name then A else B end\fR, you\'ll need something more like \fB if (\.name | length) > 0 then A else B end\fR instead\.
. .
.P .P
If the condition A produces multiple results, it is considered "true" if any of those results is not false or null\. If it produces zero results, it\'s consider ed false\. If the condition \fBA\fR produces multiple results, then \fBB\fR is evaluated on ce for each result that is not false or null, and \fBC\fR is evaluated once for each false or null\.
. .
.P .P
More cases can be added to an if using \fBelif A then B\fR syntax\. More cases can be added to an if using \fBelif A then B\fR syntax\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'if \. == 0 then jq \'if \. == 0 then
. .
skipping to change at line 2024 skipping to change at line 2266
=> true, false, true, false => true, false, true, false
jq \'[true, false | not]\' jq \'[true, false | not]\'
null null
=> [false, true] => [false, true]
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "Alternative operator \- //" .SS "Alternative operator: //"
A filter of the form \fBa // b\fR produces the same results as \fBa\fR, if \fBa\ fR produces results other than \fBfalse\fR and \fBnull\fR\. Otherwise, \fBa // b \fR produces the same results as \fBb\fR\. A filter of the form \fBa // b\fR produces the same results as \fBa\fR, if \fBa\ fR produces results other than \fBfalse\fR and \fBnull\fR\. Otherwise, \fBa // b \fR produces the same results as \fBb\fR\.
. .
.P .P
This is useful for providing defaults: \fB\.foo // 1\fR will evaluate to \fB1\fR if there\'s no \fB\.foo\fR element in the input\. It\'s similar to how \fBor\fR is sometimes used in Python (jq\'s \fBor\fR operator is reserved for strictly B oolean operations)\. This is useful for providing defaults: \fB\.foo // 1\fR will evaluate to \fB1\fR if there\'s no \fB\.foo\fR element in the input\. It\'s similar to how \fBor\fR is sometimes used in Python (jq\'s \fBor\fR operator is reserved for strictly B oolean operations)\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'\.foo // 42\' jq \'\.foo // 42\'
skipping to change at line 2139 skipping to change at line 2381
break $out break $out
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .P
because no label \fB$out\fR is visible\. because no label \fB$out\fR is visible\.
. .
.SS "? operator" .SS "Error Suppression / Optional Operator: ?"
The \fB?\fR operator, used as \fBEXP?\fR, is shorthand for \fBtry EXP\fR\. The \fB?\fR operator, used as \fBEXP?\fR, is shorthand for \fBtry EXP\fR\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'[\.[]|(\.a)?]\' jq \'[\.[]|(\.a)?]\'
[{}, true, {"a":1}] [{}, true, {"a":1}]
=> [null, 1] => [null, 1]
. .
skipping to change at line 2224 skipping to change at line 2466
Note that certain flags may also be specified within REGEX, e\.g\. Note that certain flags may also be specified within REGEX, e\.g\.
. .
.IP "\(bu" 4 .IP "\(bu" 4
jq \-n \'("test", "TEst", "teST", "TEST") | test( "(?i)te(?\-i)st" )\' jq \-n \'("test", "TEst", "teST", "TEST") | test( "(?i)te(?\-i)st" )\'
. .
.IP "" 0 .IP "" 0
. .
.P .P
evaluates to: true, true, false, false\. evaluates to: true, true, false, false\.
. .
.SS "[Requires 1\.5] test(val), test(regex; flags)" .SS "test(val), test(regex; flags)"
Like \fBmatch\fR, but does not return match objects, only \fBtrue\fR or \fBfalse \fR for whether or not the regex matches the input\. Like \fBmatch\fR, but does not return match objects, only \fBtrue\fR or \fBfalse \fR for whether or not the regex matches the input\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'test("foo")\' jq \'test("foo")\'
"foo" "foo"
=> true => true
jq \'\.[] | test("a b c # spaces are ignored"; "ix")\' jq \'\.[] | test("a b c # spaces are ignored"; "ix")\'
["xabcd", "ABC"] ["xabcd", "ABC"]
=> true, true => true, true
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "[Requires 1\.5] match(val), match(regex; flags)" .SS "match(val), match(regex; flags)"
\fBmatch\fR outputs an object for each match it finds\. Matches have the followi ng fields: \fBmatch\fR outputs an object for each match it finds\. Matches have the followi ng fields:
. .
.IP "\(bu" 4 .IP "\(bu" 4
\fBoffset\fR \- offset in UTF\-8 codepoints from the beginning of the input \fBoffset\fR \- offset in UTF\-8 codepoints from the beginning of the input
. .
.IP "\(bu" 4 .IP "\(bu" 4
\fBlength\fR \- length in UTF\-8 codepoints of the match \fBlength\fR \- length in UTF\-8 codepoints of the match
. .
.IP "\(bu" 4 .IP "\(bu" 4
\fBstring\fR \- the string that it matched \fBstring\fR \- the string that it matched
skipping to change at line 2308 skipping to change at line 2550
=> {"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": 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"}]}
jq \'[ match("\."; "g")] | length\' jq \'[ match("\."; "g")] | length\'
"abc" "abc"
=> 3 => 3
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "[Requires 1\.5] capture(val), capture(regex; flags)" .SS "capture(val), capture(regex; flags)"
Collects the named captures in a JSON object, with the name of each capture as t he key, and the matched string as the corresponding value\. Collects the named captures in a JSON object, with the name of each capture as t he key, and the matched string as the corresponding value\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'capture("(?<a>[a\-z]+)\-(?<n>[0\-9]+)")\' jq \'capture("(?<a>[a\-z]+)\-(?<n>[0\-9]+)")\'
"xyzzy\-14" "xyzzy\-14"
=> { "a": "xyzzy", "n": "14" } => { "a": "xyzzy", "n": "14" }
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "[Requires 1\.5] scan(regex), scan(regex; flags)" .SS "scan(regex), scan(regex; flags)"
Emit a stream of the non\-overlapping substrings of the input that match the reg ex in accordance with the flags, if any have been specified\. If there is no mat ch, 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\. Emit a stream of the non\-overlapping substrings of the input that match the reg ex in accordance with the flags, if any have been specified\. If there is no mat ch, 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\.
. .
.SS "split(regex; flags)" .SS "split(regex; flags)"
For backwards compatibility, \fBsplit\fR splits on a string, not a regex\. For backwards compatibility, \fBsplit\fR splits on a string, not a regex\.
. .
.SS "[Requires 1\.5] splits(regex), splits(regex; flags)" .SS "splits(regex), splits(regex; flags)"
These provide the same results as their \fBsplit\fR counterparts, but as a strea m instead of an array\. These provide the same results as their \fBsplit\fR counterparts, but as a strea m instead of an array\.
. .
.SS "[Requires 1\.5] sub(regex; tostring) sub(regex; string; flags)" .SS "sub(regex; tostring) sub(regex; string; flags)"
Emit the string obtained by replacing the first match of regex in the input stri ng with \fBtostring\fR, after interpolation\. \fBtostring\fR should be a jq stri ng, and may contain references to named captures\. The named captures are, in ef fect, presented as a JSON object (as constructed by \fBcapture\fR) to \fBtostrin g\fR, so a reference to a captured variable named "x" would take the form: "(\.x )"\. Emit the string obtained by replacing the first match of regex in the input stri ng with \fBtostring\fR, after interpolation\. \fBtostring\fR should be a jq stri ng, and may contain references to named captures\. The named captures are, in ef fect, presented as a JSON object (as constructed by \fBcapture\fR) to \fBtostrin g\fR, so a reference to a captured variable named "x" would take the form: "(\.x )"\.
. .
.SS "[Requires 1\.5] gsub(regex; string), gsub(regex; string; flags)" .SS "gsub(regex; string), gsub(regex; string; flags)"
\fBgsub\fR is like \fBsub\fR but all the non\-overlapping occurrences of the reg ex are replaced by the string, after interpolation\. \fBgsub\fR is like \fBsub\fR but all the non\-overlapping occurrences of the reg ex are replaced by the string, after interpolation\.
. .
.SH "ADVANCED FEATURES" .SH "ADVANCED FEATURES"
Variables are an absolute necessity in most programming languages, but they\'re relegated to an "advanced feature" in jq\. Variables are an absolute necessity in most programming languages, but they\'re relegated to an "advanced feature" in jq\.
. .
.P .P
In most languages, variables are the only means of passing around data\. If you calculate a value, and you want to use it more than once, you\'ll need to store it in a variable\. To pass a value to another part of the program, you\'ll need that part of the program to define a variable (as a function parameter, object m ember, or whatever) in which to place the data\. In most languages, variables are the only means of passing around data\. If you calculate a value, and you want to use it more than once, you\'ll need to store it in a variable\. To pass a value to another part of the program, you\'ll need that part of the program to define a variable (as a function parameter, object m ember, or whatever) in which to place the data\.
. .
.P .P
It is also possible to define functions in jq, although this is is a feature who se biggest use is defining jq\'s standard library (many jq functions such as \fB map\fR and \fBfind\fR are in fact written in jq)\. It is also possible to define functions in jq, although this is is a feature who se biggest use is defining jq\'s standard library (many jq functions such as \fB map\fR and \fBfind\fR are in fact written in jq)\.
skipping to change at line 2359 skipping to change at line 2601
. .
.P .P
It may not be obvious at first, but jq is all about generators (yes, as often fo und in other languages)\. Some utilities are provided to help deal with generato rs\. It may not be obvious at first, but jq is all about generators (yes, as often fo und in other languages)\. Some utilities are provided to help deal with generato rs\.
. .
.P .P
Some minimal I/O support (besides reading JSON from standard input, and writing JSON to standard output) is available\. Some minimal I/O support (besides reading JSON from standard input, and writing JSON to standard output) is available\.
. .
.P .P
Finally, there is a module/library system\. Finally, there is a module/library system\.
. .
.SS "Variables" .SS "Variable / Symbolic Binding Operator: \.\.\. as $identifier | \.\.\."
In jq, all filters have an input and an output, so manual plumbing is not necess ary to pass a value from one part of a program to the next\. Many expressions, f or instance \fBa + b\fR, pass their input to two distinct subexpressions (here \ fBa\fR and \fBb\fR are both passed the same input), so variables aren\'t usually necessary in order to use a value twice\. In jq, all filters have an input and an output, so manual plumbing is not necess ary to pass a value from one part of a program to the next\. Many expressions, f or instance \fBa + b\fR, pass their input to two distinct subexpressions (here \ fBa\fR and \fBb\fR are both passed the same input), so variables aren\'t usually necessary in order to use a value twice\.
. .
.P .P
For instance, calculating the average value of an array of numbers requires a fe w variables in most languages \- at least one to hold the array, perhaps one for each element or for a loop counter\. In jq, it\'s simply \fBadd / length\fR \- the \fBadd\fR expression is given the array and produces its sum, and the \fBlen gth\fR expression is given the array and produces its length\. For instance, calculating the average value of an array of numbers requires a fe w variables in most languages \- at least one to hold the array, perhaps one for each element or for a loop counter\. In jq, it\'s simply \fBadd / length\fR \- the \fBadd\fR expression is given the array and produces its sum, and the \fBlen gth\fR expression is given the array and produces its length\.
. .
.P .P
So, there\'s generally a cleaner way to solve most problems in jq than defining variables\. Still, sometimes they do make things easier, so jq lets you define v ariables using \fBexpression as $variable\fR\. All variable names start with \fB $\fR\. Here\'s a slightly uglier version of the array\-averaging example: So, there\'s generally a cleaner way to solve most problems in jq than defining variables\. Still, sometimes they do make things easier, so jq lets you define v ariables using \fBexpression as $variable\fR\. All variable names start with \fB $\fR\. Here\'s a slightly uglier version of the array\-averaging example:
. .
.IP "" 4 .IP "" 4
. .
skipping to change at line 2516 skipping to change at line 2758
. .
.nf .nf
def increment: \. + 1; def increment: \. + 1;
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .P
From then on, \fBincrement\fR is usable as a filter just like a builtin function (in fact, this is how some of the builtins are defined)\. A function may take a rguments: From then on, \fBincrement\fR is usable as a filter just like a builtin function (in fact, this is how many of the builtins are defined)\. A function may take a rguments:
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
def map(f): [\.[] | f]; def map(f): [\.[] | f];
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .P
Arguments are passed as filters, not as values\. The same argument may be refere nced multiple times with different inputs (here \fBf\fR is run for each element of the input array)\. Arguments to a function work more like callbacks than like value arguments\. This is important to understand\. Consider: Arguments are passed as \fIfilters\fR (functions with no arguments), \fInot\fR a s values\. The same argument may be referenced multiple times with different inp uts (here \fBf\fR is run for each element of the input array)\. Arguments to a f unction work more like callbacks than like value arguments\. This is important t o understand\. Consider:
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
def foo(f): f|f; def foo(f): f|f;
5|foo(\.*2) 5|foo(\.*2)
. .
.fi .fi
. .
skipping to change at line 2572 skipping to change at line 2814
. .
.nf .nf
def addvalue($f): \.\.\.; def addvalue($f): \.\.\.;
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.P .P
With either definition, \fBaddvalue(\.foo)\fR will add the current input\'s \fB\ .foo\fR field to each element of the array\. With either definition, \fBaddvalue(\.foo)\fR will add the current input\'s \fB\ .foo\fR field to each element of the array\. Do note that calling \fBaddvalue(\. [])\fR will cause the \fBmap(\. + $f)\fR part to be evaluated once per value in the value of \fB\.\fR at the call site\.
. .
.P .P
Multiple definitions using the same function name are allowed\. Each re\-definit ion replaces the previous one for the same number of function arguments, but onl y for references from functions (or main program) subsequent to the re\-definiti on\. Multiple definitions using the same function name are allowed\. Each re\-definit ion replaces the previous one for the same number of function arguments, but onl y for references from functions (or main program) subsequent to the re\-definiti on\. See also the section below on scoping\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'def addvalue(f): \. + [f]; map(addvalue(\.[0]))\' jq \'def addvalue(f): \. + [f]; map(addvalue(\.[0]))\'
[[1,2],[10,20]] [[1,2],[10,20]]
=> [[1,2,1], [10,20,10]] => [[1,2,1], [10,20,10]]
jq \'def addvalue(f): f as $x | map(\. + $x); addvalue(\.[0])\' jq \'def addvalue(f): f as $x | map(\. + $x); addvalue(\.[0])\'
[[1,2],[10,20]] [[1,2],[10,20]]
=> [[1,2,1,2], [10,20,1,2]] => [[1,2,1,2], [10,20,1,2]]
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "Scoping"
There are two types of symbols in jq: value bindings (a\.k\.a\., "variables"), a
nd functions\. Both are scoped lexically, with expressions being able to refer o
nly to symbols that have been defined "to the left" of them\. The only exception
to this rule is that functions can refer to themselves so as to be able to crea
te recursive functions\.
.
.P
For example, in the following expression there is a binding which is visible "to
the right" of it, \fB\.\.\. | \.*3 as $times_three | [\. + $times_three] | \.\.
\.\fR, but not "to the left"\. Consider this expression now, \fB\.\.\. | (\.*3 a
s $times_three | [\.+ $times_three]) | \.\.\.\fR: here the binding \fB$times_thr
ee\fR is \fInot\fR visible past the closing parenthesis\.
.
.SS "Reduce" .SS "Reduce"
The \fBreduce\fR syntax in jq allows you to combine all of the results of an exp ression by accumulating them into a single answer\. As an example, we\'ll pass \ fB[3,2,1]\fR to this expression: The \fBreduce\fR syntax in jq allows you to combine all of the results of an exp ression by accumulating them into a single answer\. As an example, we\'ll pass \ fB[3,2,1]\fR to this expression:
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
reduce \.[] as $item (0; \. + $item) reduce \.[] as $item (0; \. + $item)
. .
.fi .fi
skipping to change at line 2625 skipping to change at line 2873
(1 as $item | \. + $item) (1 as $item | \. + $item)
jq \'reduce \.[] as $item (0; \. + $item)\' jq \'reduce \.[] as $item (0; \. + $item)\'
[10,2,5,3] [10,2,5,3]
=> 20 => 20
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "isempty(exp)"
Returns true if \fBexp\fR produces no outputs, false otherwise\.
.
.IP "" 4
.
.nf
jq \'isempty(empty)\'
null
=> true
.
.fi
.
.IP "" 0
.
.SS "limit(n; exp)" .SS "limit(n; exp)"
The \fBlimit\fR function extracts up to \fBn\fR outputs from \fBexp\fR\. The \fBlimit\fR function extracts up to \fBn\fR outputs from \fBexp\fR\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'[limit(3;\.[])]\' jq \'[limit(3;\.[])]\'
[0,1,2,3,4,5,6,7,8,9] [0,1,2,3,4,5,6,7,8,9]
=> [0,1,2] => [0,1,2]
skipping to change at line 2758 skipping to change at line 3021
=> [1,2,4,8,16,32,64] => [1,2,4,8,16,32,64]
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SH "MATH" .SH "MATH"
jq currently only has IEEE754 double\-precision (64\-bit) floating point number support\. jq currently only has IEEE754 double\-precision (64\-bit) floating point number support\.
. .
.P .P
Besides simple arithmetic operators such as \fB+\fR, jq also has most standard m ath functions from the C math library\. C math functions that take a single inpu t argument (e\.g\., \fBsin()\fR) are available as zero\-argument jq functions\. C math functions that take two input arguments (e\.g\., \fBpow()\fR) are availab le as two\-argument jq functions that ignore \fB\.\fR\. Besides simple arithmetic operators such as \fB+\fR, jq also has most standard m ath functions from the C math library\. C math functions that take a single inpu t argument (e\.g\., \fBsin()\fR) are available as zero\-argument jq functions\. C math functions that take two input arguments (e\.g\., \fBpow()\fR) are availab le as two\-argument jq functions that ignore \fB\.\fR\. C math functions that ta ke three input arguments are available as three\-argument jq functions that igno re \fB\.\fR\.
. .
.P .P
Availability of standard math functions depends on the availability of the corre sponding math functions in your operating system and C math library\. Unavailabl e math functions will be defined but will raise an error\. Availability of standard math functions depends on the availability of the corre sponding math functions in your operating system and C math library\. Unavailabl e math functions will be defined but will raise an error\.
. .
.P
One\-input C math functions: \fBacos\fR \fBacosh\fR \fBasin\fR \fBasinh\fR \fBat
an\fR \fBatanh\fR \fBcbrt\fR \fBceil\fR \fBcos\fR \fBcosh\fR \fBerf\fR \fBerfc\f
R \fBexp\fR \fBexp10\fR \fBexp2\fR \fBexpm1\fR \fBfabs\fR \fBfloor\fR \fBgamma\f
R \fBj0\fR \fBj1\fR \fBlgamma\fR \fBlog\fR \fBlog10\fR \fBlog1p\fR \fBlog2\fR \f
Blogb\fR \fBnearbyint\fR \fBpow10\fR \fBrint\fR \fBround\fR \fBsignificand\fR \f
Bsin\fR \fBsinh\fR \fBsqrt\fR \fBtan\fR \fBtanh\fR \fBtgamma\fR \fBtrunc\fR \fBy
0\fR \fBy1\fR\.
.
.P
Two\-input C math functions: \fBatan2\fR \fBcopysign\fR \fBdrem\fR \fBfdim\fR \f
Bfmax\fR \fBfmin\fR \fBfmod\fR \fBfrexp\fR \fBhypot\fR \fBjn\fR \fBldexp\fR \fBm
odf\fR \fBnextafter\fR \fBnexttoward\fR \fBpow\fR \fBremainder\fR \fBscalb\fR \f
Bscalbln\fR \fByn\fR\.
.
.P
Three\-input C math functions: \fBfma\fR\.
.
.P
See your system\'s manual for more information on each of these\.
.
.SH "I/O" .SH "I/O"
At this time jq has minimal support for I/O, mostly in the form of control over when inputs are read\. Two builtins functions are provided for this, \fBinput\fR and \fBinputs\fR, that read from the same sources (e\.g\., \fBstdin\fR, files n amed on the command\-line) as jq itself\. These two builtins, and jq\'s own read ing actions, can be interleaved with each other\. At this time jq has minimal support for I/O, mostly in the form of control over when inputs are read\. Two builtins functions are provided for this, \fBinput\fR and \fBinputs\fR, that read from the same sources (e\.g\., \fBstdin\fR, files n amed on the command\-line) as jq itself\. These two builtins, and jq\'s own read ing actions, can be interleaved with each other\.
. .
.P .P
One builtin provides minimal output capabilities, \fBdebug\fR\. (Recall that a j Two builtins provide minimal output capabilities, \fBdebug\fR, and \fBstderr\fR\
q program\'s output values are always output as JSON texts on \fBstdout\fR\.) Th . (Recall that a jq program\'s output values are always output as JSON texts on
e \fBdebug\fR builtin can have application\-specific behavior, such as for execu \fBstdout\fR\.) The \fBdebug\fR builtin can have application\-specific behavior,
tables that use the libjq C API but aren\'t the jq executable itself\. such as for executables that use the libjq C API but aren\'t the jq executable
itself\. The \fBstderr\fR builtin outputs its input in raw mode to stder with no
additional decoration, not even a newline\.
.
.P
Most jq builtins are referentially transparent, and yield constant and repeatabl
e value streams when applied to constant inputs\. This is not true of I/O builti
ns\.
. .
.SS "input" .SS "input"
Outputs one new input\. Outputs one new input\.
. .
.SS "inputs" .SS "inputs"
Outputs all remaining inputs, one by one\. Outputs all remaining inputs, one by one\.
. .
.P .P
This is primarily useful for reductions over a program\'s inputs\. This is primarily useful for reductions over a program\'s inputs\.
. .
.SS "debug" .SS "debug"
Causes a debug message based on the input value to be produced\. The jq executab le wraps the input value with \fB["DEBUG:", <input\-value>]\fR and prints that a nd a newline on stderr, compactly\. This may change in the future\. Causes a debug message based on the input value to be produced\. The jq executab le wraps the input value with \fB["DEBUG:", <input\-value>]\fR and prints that a nd a newline on stderr, compactly\. This may change in the future\.
. .
.SS "stderr"
Prints its input in raw and compact mode to stderr with no additional decoration
, not even a newline\.
.
.SS "input_filename" .SS "input_filename"
Returns the name of the file whose input is currently being filtered\. Note that this will not work well unless jq is running in a UTF\-8 locale\. Returns the name of the file whose input is currently being filtered\. Note that this will not work well unless jq is running in a UTF\-8 locale\.
. .
.SS "input_line_number" .SS "input_line_number"
Returns the line number of the input currently being filtered\. Returns the line number of the input currently being filtered\.
. .
.SH "STREAMING" .SH "STREAMING"
With the \fB\-\-stream\fR option jq can parse input texts in a streaming fashion , allowing jq programs to start processing large JSON texts immediately rather t han after the parse completes\. If you have a single JSON text that is 1GB in si ze, streaming it will allow you to process it much more quickly\. With the \fB\-\-stream\fR option jq can parse input texts in a streaming fashion , allowing jq programs to start processing large JSON texts immediately rather t han after the parse completes\. If you have a single JSON text that is 1GB in si ze, streaming it will allow you to process it much more quickly\.
. .
.P .P
However, streaming isn\'t easy to deal with as the jq program will have \fB[<pat h>, <leaf\-value>]\fR (and a few other forms) as inputs\. However, streaming isn\'t easy to deal with as the jq program will have \fB[<pat h>, <leaf\-value>]\fR (and a few other forms) as inputs\.
. .
.P .P
Several builtins are provided to make handling streams easier\. Several builtins are provided to make handling streams easier\.
. .
.P .P
The examples below use the the streamed form of \fB[0,[1]]\fR, which is \fB[[0], 0],[[1,0],1],[[1,0]],[[1]]\fR\. The examples below use the streamed form of \fB[0,[1]]\fR, which is \fB[[0],0],[ [1,0],1],[[1,0]],[[1]]\fR\.
. .
.P .P
Streaming forms include \fB[<path>, <leaf\-value>]\fR (to indicate any scalar va lue, empty array, or empty object), and \fB[<path>]\fR (to indicate the end of a n array or object)\. Future versions of jq run with \fB\-\-stream\fR and \fB\-se q\fR may output additional forms such as \fB["error message"]\fR when an input t ext fails to parse\. Streaming forms include \fB[<path>, <leaf\-value>]\fR (to indicate any scalar va lue, empty array, or empty object), and \fB[<path>]\fR (to indicate the end of a n array or object)\. Future versions of jq run with \fB\-\-stream\fR and \fB\-se q\fR may output additional forms such as \fB["error message"]\fR when an input t ext fails to parse\.
. .
.SS "truncate_stream(stream_expression)" .SS "truncate_stream(stream_expression)"
Consumes a number as input and truncates the corresponding number of path elemen ts from the left of the outputs of the given streaming expression\. Consumes a number as input and truncates the corresponding number of path elemen ts from the left of the outputs of the given streaming expression\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
skipping to change at line 2851 skipping to change at line 3132
=> true => true
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SH "ASSIGNMENT" .SH "ASSIGNMENT"
Assignment works a little differently in jq than in most programming languages\. jq doesn\'t distinguish between references to and copies of something \- two ob jects or arrays are either equal or not equal, without any further notion of bei ng "the same object" or "not the same object"\. Assignment works a little differently in jq than in most programming languages\. jq doesn\'t distinguish between references to and copies of something \- two ob jects or arrays are either equal or not equal, without any further notion of bei ng "the same object" or "not the same object"\.
. .
.P .P
If an object has two fields which are arrays, \fB\.foo\fR and \fB\.bar\fR, and y If an object has two fields which are arrays, \fB\.foo\fR and \fB\.bar\fR, and y
ou append something to \fB\.foo\fR, then \fB\.bar\fR will not get bigger\. Even ou append something to \fB\.foo\fR, then \fB\.bar\fR will not get bigger, even i
if you\'ve just set \fB\.bar = \.foo\fR\. If you\'re used to programming in lang f you\'ve previously set \fB\.bar = \.foo\fR\. If you\'re used to programming in
uages like Python, Java, Ruby, Javascript, etc\. then you can think of it as tho languages like Python, Java, Ruby, Javascript, etc\. then you can think of it a
ugh jq does a full deep copy of every object before it does the assignment (for s though jq does a full deep copy of every object before it does the assignment
performance, it doesn\'t actually do that, but that\'s the general idea)\. (for performance it doesn\'t actually do that, but that\'s the general idea)\.
.
.P
All the assignment operators in jq have path expressions on the left\-hand side\
.
.
.SS "="
The filter \fB\.foo = 1\fR will take as input an object and produce as output an
object with the "foo" field set to 1\. There is no notion of "modifying" or "ch
anging" something in jq \- all jq values are immutable\. For instance,
.
.P
\&\.foo = \.bar | \.foo\.baz = 1
.
.P
will not have the side\-effect of setting \.bar\.baz to be set to 1, as the simi
lar\-looking program in Javascript, Python, Ruby or other languages would\. Unli
ke these languages (but like Haskell and some other functional languages), there
is no notion of two arrays or objects being "the same array" or "the same objec
t"\. They can be equal, or not equal, but if we change one of them in no circums
tances will the other change behind our backs\.
. .
.P .P
This means that it\'s impossible to build circular values in jq (such as an arra y whose first element is itself)\. This is quite intentional, and ensures that a nything a jq program can produce can be represented in JSON\. This means that it\'s impossible to build circular values in jq (such as an arra y whose first element is itself)\. This is quite intentional, and ensures that a nything a jq program can produce can be represented in JSON\.
. .
.P .P
Note that the left\-hand side of \'=\' refers to a value in \fB\.\fR\. Thus \fB$ var\.foo = 1\fR won\'t work as expected (\fB$var\.foo\fR is not a valid or usefu l path expression in \fB\.\fR); use \fB$var | \.foo = 1\fR instead\. All the assignment operators in jq have path expressions on the left\-hand side (LHS)\. The right\-hand side (RHS) procides values to set to the paths named by the LHS path expressions\.
. .
.P .P
If the right\-hand side of \'=\' produces multiple values, then for each such va lue jq will set the paths on the left\-hand side to the value and then it will o utput the modified \fB\.\fR\. For example, \fB(\.a,\.b)=range(2)\fR outputs \fB{ "a":0,"b":0}\fR, then \fB{"a":1,"b":1}\fR\. The "update" assignment forms (see b elow) do not do this\. Values in jq are always immutable\. Internally, assignment works by using a redu ction to compute new, replacement values for \fB\.\fR that have had all the desi red assignments applied to \fB\.\fR, then outputting the modified value\. This m ight be made clear by this example: \fB{a:{b:{c:1}}} | (\.a\.b|=3), \.\fR\. This will output \fB{"a":{"b":3}}\fR and \fB{"a":{"b":{"c":1}}}\fR because the last sub\-expression, \fB\.\fR, sees the original value, not the modified value\.
. .
.P .P
Note too that \fB\.a,\.b=0\fR does not set \fB\.a\fR and \fB\.b\fR, but \fB(\.a, Most users will want to use modification assignment operators, such as \fB|=\fR
\.b)=0\fR sets both\. or \fB+=\fR, rather than \fB=\fR\.
.
.SS "|="
As well as the assignment operator \'=\', jq provides the "update" operator \'|=
\', which takes a filter on the right\-hand side and works out the new value for
the property of \fB\.\fR being assigned to by running the old value through thi
s expression\. For instance, \.foo |= \.+1 will build an object with the "foo" f
ield set to the input\'s "foo" plus 1\.
. .
.P .P
This example should show the difference between \'=\' and \'|=\': Note that the LHS of assignment operators refers to a value in \fB\.\fR\. Thus \ fB$var\.foo = 1\fR won\'t work as expected (\fB$var\.foo\fR is not a valid or us eful path expression in \fB\.\fR); use \fB$var | \.foo = 1\fR instead\.
. .
.P .P
Provide input \'{"a": {"b": 10}, "b": 20}\' to the programs: Note too that \fB\.a,\.b=0\fR does not set \fB\.a\fR and \fB\.b\fR, but \fB(\.a,
. \.b)=0\fR sets both\.
.P
\&\.a = \.b \.a |= \.b
. .
.P .SS "Update\-assignment: |="
The former will set the "a" field of the input to the "b" field of the input, an This is the "update" operator \'|=\'\. It takes a filter on the right\-hand side
d produce the output {"a": 20}\. The latter will set the "a" field of the input and works out the new value for the property of \fB\.\fR being assigned to by r
to the "a" field\'s "b" field, producing {"a": 10}\. unning the old value through this expression\. For instance, (\.foo, \.bar) |= \
.+1 will build an object with the "foo" field set to the input\'s "foo" plus 1,
and the "bar" field set to the input\'s "bar" plus 1\.
. .
.P .P
The left\-hand side can be any general path expression; see \fBpath()\fR\. The left\-hand side can be any general path expression; see \fBpath()\fR\.
. .
.P .P
Note that the left\-hand side of \'|=\' refers to a value in \fB\.\fR\. Thus \fB $var\.foo |= \. + 1\fR won\'t work as expected (\fB$var\.foo\fR is not a valid o r useful path expression in \fB\.\fR); use \fB$var | \.foo |= \. + 1\fR instead\ . Note that the left\-hand side of \'|=\' refers to a value in \fB\.\fR\. Thus \fB $var\.foo |= \. + 1\fR won\'t work as expected (\fB$var\.foo\fR is not a valid o r useful path expression in \fB\.\fR); use \fB$var | \.foo |= \. + 1\fR instead\ .
. .
.P .P
If the right\-hand side outputs multiple values, only the last one will be used\ If the right\-hand side outputs no values (i\.e\., \fBempty\fR), then the left\-
. hand side path will be deleted, as with \fBdel(path)\fR\.
.
.P
If the right\-hand side outputs multiple values, only the first one will be used
(COMPATIBILITY NOTE: in jq 1\.5 and earlier releases, it used to be that only t
he last one was used)\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'(\.\.|select(type=="boolean")) |= if \. then 1 else 0 end\' jq \'(\.\.|select(type=="boolean")) |= if \. then 1 else 0 end\'
[true,false,[5,true,[true,[false]],false]] [true,false,[5,true,[true,[false]],false]]
=> [1,0,[5,1,[1,[0]],0]] => [1,0,[5,1,[1,[0]],0]]
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "+=, \-=, *=, /=, %=, //=" .SS "Arithmetic update\-assignment: +=, \-=, *=, /=, %=, //="
jq has a few operators of the form \fBa op= b\fR, which are all equivalent to \f jq has a few operators of the form \fBa op= b\fR, which are all equivalent to \f
Ba |= \. op b\fR\. So, \fB+= 1\fR can be used to increment values\. Ba |= \. op b\fR\. So, \fB+= 1\fR can be used to increment values, being the sam
e as \fB|= \. + 1\fR\.
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
jq \'\.foo += 1\' jq \'\.foo += 1\'
{"foo": 42} {"foo": 42}
=> {"foo": 43} => {"foo": 43}
. .
.fi .fi
. .
.IP "" 0 .IP "" 0
. .
.SS "Plain assignment: ="
This is the plain assignment operator\. Unlike the others, the input to the righ
t\-hand\-side (RHS) is the same as the input to the left\-hand\-side (LHS) rathe
r than the value at the LHS path, and all values output by the RHS will be used
(as shown below)\.
.
.P
If the RHS of \'=\' produces multiple values, then for each such value jq will s
et the paths on the left\-hand side to the value and then it will output the mod
ified \fB\.\fR\. For example, \fB(\.a,\.b)=range(2)\fR outputs \fB{"a":0,"b":0}\
fR, then \fB{"a":1,"b":1}\fR\. The "update" assignment forms (see above) do not
do this\.
.
.P
This example should show the difference between \'=\' and \'|=\':
.
.P
Provide input \'{"a": {"b": 10}, "b": 20}\' to the programs:
.
.P
\&\.a = \.b
.
.P
\&\.a |= \.b
.
.P
The former will set the "a" field of the input to the "b" field of the input, an
d produce the output {"a": 20, "b": 20}\. The latter will set the "a" field of t
he input to the "a" field\'s "b" field, producing {"a": 10, "b": 20}\.
.
.P
Another example of the difference between \'=\' and \'|=\':
.
.P
null|(\.a,\.b)=range(3)
.
.P
outputs \'{"a":0,"b":0}\', \'{"a":1,"b":1}\', and \'{"a":2,"b":2}\', while
.
.P
null|(\.a,\.b)|=range(3)
.
.P
outputs just \'{"a":0,"b":0}\'\.
.
.SS "Complex assignments" .SS "Complex assignments"
Lots more things are allowed on the left\-hand side of a jq assignment than in m ost languages\. We\'ve already seen simple field accesses on the left hand side, and it\'s no surprise that array accesses work just as well: Lots more things are allowed on the left\-hand side of a jq assignment than in m ost languages\. We\'ve already seen simple field accesses on the left hand side, and it\'s no surprise that array accesses work just as well:
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
\&\.posts[0]\.title = "JQ Manual" \&\.posts[0]\.title = "JQ Manual"
. .
.fi .fi
skipping to change at line 3062 skipping to change at line 3364
. .
.P .P
The metadata must be a constant jq expression\. It should be an object with keys like "homepage"\. At this time jq doesn\'t use this metadata, but it is made av ailable to users via the \fBmodulemeta\fR builtin\. The metadata must be a constant jq expression\. It should be an object with keys like "homepage"\. At this time jq doesn\'t use this metadata, but it is made av ailable to users via the \fBmodulemeta\fR builtin\.
. .
.SS "modulemeta" .SS "modulemeta"
Takes a module name as input and outputs the module\'s metadata as an object, wi th the module\'s imports (including metadata) as an array value for the "deps" k ey\. Takes a module name as input and outputs the module\'s metadata as an object, wi th the module\'s imports (including metadata) as an array value for the "deps" k ey\.
. .
.P .P
Programs can use this to query a module\'s metadata, which they could then use t o, for example, search for, download, and install missing dependencies\. Programs can use this to query a module\'s metadata, which they could then use t o, for example, search for, download, and install missing dependencies\.
. .
.SH "COLORS"
To configure alternative colors just set the \fBJQ_COLORS\fR environment variabl
e to colon\-delimited list of partial terminal escape sequences like \fB"1;31"\f
R, in this order:
.
.IP "\(bu" 4
color for \fBnull\fR
.
.IP "\(bu" 4
color for \fBfalse\fR
.
.IP "\(bu" 4
color for \fBtrue\fR
.
.IP "\(bu" 4
color for numbers
.
.IP "\(bu" 4
color for strings
.
.IP "\(bu" 4
color for arrays
.
.IP "\(bu" 4
color for objects
.
.IP "" 0
.
.P
The default color scheme is the same as setting \fB"JQ_COLORS=1;30:0;39:0;39:0;3
9:0;32:1;39:1;39"\fR\.
.
.P
This is not a manual for VT100/ANSI escapes\. However, each of these color speci
fications should consist of two numbers separated by a semi\-colon, where the fi
rst number is one of these:
.
.IP "\(bu" 4
1 (bright)
.
.IP "\(bu" 4
2 (dim)
.
.IP "\(bu" 4
4 (underscore)
.
.IP "\(bu" 4
5 (blink)
.
.IP "\(bu" 4
7 (reverse)
.
.IP "\(bu" 4
8 (hidden)
.
.IP "" 0
.
.P
and the second is one of these:
.
.IP "\(bu" 4
30 (black)
.
.IP "\(bu" 4
31 (red)
.
.IP "\(bu" 4
32 (green)
.
.IP "\(bu" 4
33 (yellow)
.
.IP "\(bu" 4
34 (blue)
.
.IP "\(bu" 4
35 (magenta)
.
.IP "\(bu" 4
36 (cyan)
.
.IP "\(bu" 4
37 (white)
.
.IP "" 0
.
.SH "BUGS" .SH "BUGS"
Presumably\. Report them or discuss them at: Presumably\. Report them or discuss them at:
. .
.IP "" 4 .IP "" 4
. .
.nf .nf
https://github\.com/stedolan/jq/issues https://github\.com/stedolan/jq/issues
. .
.fi .fi
 End of changes. 93 change blocks. 
188 lines changed or deleted 648 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)