"Fossies" - the Fresh Open Source Software Archive

Member "jq-1.6/jq.1.prebuilt" (2 Nov 2018, 100874 Bytes) of package /linux/misc/jq-1.6.tar.gz:

    1 .\" generated with Ronn/v0.7.3
    2 .\" http://github.com/rtomayko/ronn/tree/0.7.3
    3 .
    4 .TH "JQ" "1" "December 2017" "" ""
    5 .
    6 .SH "NAME"
    7 \fBjq\fR \- Command\-line JSON processor
    8 .
    9 .SH "SYNOPSIS"
   10 \fBjq\fR [\fIoptions\fR\.\.\.] \fIfilter\fR [\fIfiles\fR\.\.\.]
   11 .
   12 .P
   13 \fBjq\fR can transform JSON in various ways, by selecting, iterating, reducing and 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\.
   14 .
   15 .P
   16 \fBjq\fR can accept text input as well, but by default, \fBjq\fR reads a stream of JSON entities (including numbers and other literals) from \fBstdin\fR\. Whitespace is only needed to separate entities such as 1 and 2, and true and false\. One or more \fIfiles\fR may be specified, in which case \fBjq\fR will read input from those instead\.
   17 .
   18 .P
   19 The \fIoptions\fR are described in the \fIINVOKING JQ\fR section; they mostly concern input and output formatting\. The \fIfilter\fR is written in the jq language and specifies how to transform the input file or document\.
   20 .
   21 .SH "FILTERS"
   22 A jq program is a "filter": it takes an input, and produces an output\. There are a lot of builtin filters for extracting a particular field of an object, or converting a number to a string, or various other standard tasks\.
   23 .
   24 .P
   25 Filters can be combined in various ways \- you can pipe the output of one filter into another filter, or collect the output of a filter into an array\.
   26 .
   27 .P
   28 Some filters produce multiple results, for instance there\'s one that produces all the elements of its input array\. Piping that filter into a second runs the second filter for each element of the array\. Generally, things that would be done with loops and iteration in other languages are just done by gluing filters together in jq\.
   29 .
   30 .P
   31 It\'s important to remember that every filter has an input and an output\. Even literals like "hello" or 42 are filters \- they take an input but always produce the same literal as output\. Operations that combine two filters, like addition, generally feed the same input to both and combine the results\. So, you can implement an averaging filter as \fBadd / length\fR \- feeding the input array both to the \fBadd\fR filter and the \fBlength\fR filter and then performing the division\.
   32 .
   33 .P
   34 But that\'s getting ahead of ourselves\. :) Let\'s start with something simpler:
   35 .
   36 .SH "INVOKING JQ"
   37 jq filters run on a stream of JSON data\. The input to jq is parsed as a sequence of whitespace\-separated JSON values which are passed through the provided filter one at a time\. The output(s) of the filter are written to standard out, again as a sequence of whitespace\-separated JSON data\.
   38 .
   39 .P
   40 Note: it is important to mind the shell\'s quoting rules\. As a general rule it\'s best to always quote (with single\-quote characters) the jq program, as too many characters with special meaning to jq are also shell meta\-characters\. For example, \fBjq "foo"\fR will fail on most Unix shells because that will be the same as \fBjq foo\fR, which will generally fail because \fBfoo is not defined\fR\. When using the Windows command shell (cmd\.exe) it\'s best to use double quotes around your jq program when given on the command\-line (instead of the \fB\-f program\-file\fR option), but then double\-quotes in the jq program need backslash escaping\.
   41 .
   42 .P
   43 You can affect how jq reads and writes its input and output using some command\-line options:
   44 .
   45 .IP "\(bu" 4
   46 \fB\-\-version\fR:
   47 .
   48 .IP
   49 Output the jq version and exit with zero\.
   50 .
   51 .IP "\(bu" 4
   52 \fB\-\-seq\fR:
   53 .
   54 .IP
   55 Use the \fBapplication/json\-seq\fR MIME type scheme for separating JSON texts in jq\'s input and output\. This means that an ASCII RS (record separator) character is printed before each value on output and an ASCII LF (line feed) is printed after every output\. Input JSON texts that fail to parse are ignored (but warned about), discarding all subsequent input until the next RS\. This mode also parses the output of jq without the \fB\-\-seq\fR option\.
   56 .
   57 .IP "\(bu" 4
   58 \fB\-\-stream\fR:
   59 .
   60 .IP
   61 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, and \fB[[1,0],"b"]\fR\.
   62 .
   63 .IP
   64 This is useful for processing very large inputs\. Use this in conjunction with filtering and the \fBreduce\fR and \fBforeach\fR syntax to reduce large inputs incrementally\.
   65 .
   66 .IP "\(bu" 4
   67 \fB\-\-slurp\fR/\fB\-s\fR:
   68 .
   69 .IP
   70 Instead of running the filter for each JSON object in the input, read the entire input stream into a large array and run the filter just once\.
   71 .
   72 .IP "\(bu" 4
   73 \fB\-\-raw\-input\fR/\fB\-R\fR:
   74 .
   75 .IP
   76 Don\'t parse the input as JSON\. Instead, each line of text is passed to the filter as a string\. If combined with \fB\-\-slurp\fR, then the entire input is passed to the filter as a single long string\.
   77 .
   78 .IP "\(bu" 4
   79 \fB\-\-null\-input\fR/\fB\-n\fR:
   80 .
   81 .IP
   82 Don\'t read any input at all! Instead, the filter is run once using \fBnull\fR as the input\. This is useful when using jq as a simple calculator or to construct JSON data from scratch\.
   83 .
   84 .IP "\(bu" 4
   85 \fB\-\-compact\-output\fR / \fB\-c\fR:
   86 .
   87 .IP
   88 By default, jq pretty\-prints JSON output\. Using this option will result in more compact output by instead putting each JSON object on a single line\.
   89 .
   90 .IP "\(bu" 4
   91 \fB\-\-tab\fR:
   92 .
   93 .IP
   94 Use a tab for each indentation level instead of two spaces\.
   95 .
   96 .IP "\(bu" 4
   97 \fB\-\-indent n\fR:
   98 .
   99 .IP
  100 Use the given number of spaces (no more than 8) for indentation\.
  101 .
  102 .IP "\(bu" 4
  103 \fB\-\-color\-output\fR / \fB\-C\fR and \fB\-\-monochrome\-output\fR / \fB\-M\fR:
  104 .
  105 .IP
  106 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 disable color with \fB\-M\fR\.
  107 .
  108 .IP
  109 Colors can be configured with the \fBJQ_COLORS\fR environment variable (see below)\.
  110 .
  111 .IP "\(bu" 4
  112 \fB\-\-ascii\-output\fR / \fB\-a\fR:
  113 .
  114 .IP
  115 jq usually outputs non\-ASCII Unicode codepoints as UTF\-8, even if the input specified them as escape sequences (like "\eu03bc")\. Using this option, you can force jq to produce pure ASCII output with every non\-ASCII character replaced with the equivalent escape sequence\.
  116 .
  117 .IP "\(bu" 4
  118 \fB\-\-unbuffered\fR
  119 .
  120 .IP
  121 Flush the output after each JSON object is printed (useful if you\'re piping a slow data source into jq and piping jq\'s output elsewhere)\.
  122 .
  123 .IP "\(bu" 4
  124 \fB\-\-sort\-keys\fR / \fB\-S\fR:
  125 .
  126 .IP
  127 Output the fields of each object with the keys in sorted order\.
  128 .
  129 .IP "\(bu" 4
  130 \fB\-\-raw\-output\fR / \fB\-r\fR:
  131 .
  132 .IP
  133 With this option, if the filter\'s result is a string then it will be written directly to standard output rather than being formatted as a JSON string with quotes\. This can be useful for making jq filters talk to non\-JSON\-based systems\.
  134 .
  135 .IP "\(bu" 4
  136 \fB\-\-join\-output\fR / \fB\-j\fR:
  137 .
  138 .IP
  139 Like \fB\-r\fR but jq won\'t print a newline after each output\.
  140 .
  141 .IP "\(bu" 4
  142 \fB\-f filename\fR / \fB\-\-from\-file filename\fR:
  143 .
  144 .IP
  145 Read filter from the file rather than from a command line, like awk\'s \-f option\. You can also use \'#\' to make comments\.
  146 .
  147 .IP "\(bu" 4
  148 \fB\-Ldirectory\fR / \fB\-L directory\fR:
  149 .
  150 .IP
  151 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\.
  152 .
  153 .IP "\(bu" 4
  154 \fB\-e\fR / \fB\-\-exit\-status\fR:
  155 .
  156 .IP
  157 Sets the exit status of jq to 0 if the last output values was neither \fBfalse\fR nor \fBnull\fR, 1 if the last output value was either \fBfalse\fR or \fBnull\fR, 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 error, or 0 if the jq program ran\.
  158 .
  159 .IP
  160 Another way to set the exit status is with the \fBhalt_error\fR builtin function\.
  161 .
  162 .IP "\(bu" 4
  163 \fB\-\-arg name value\fR:
  164 .
  165 .IP
  166 This option passes a value to the jq program as a predefined variable\. If you run jq with \fB\-\-arg foo bar\fR, then \fB$foo\fR is available in the program and 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\.
  167 .
  168 .IP
  169 Named arguments are also available to the jq program as \fB$ARGS\.named\fR\.
  170 .
  171 .IP "\(bu" 4
  172 \fB\-\-argjson name JSON\-text\fR:
  173 .
  174 .IP
  175 This option passes a JSON\-encoded value to the jq program as a predefined variable\. 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\.
  176 .
  177 .IP "\(bu" 4
  178 \fB\-\-slurpfile variable\-name filename\fR:
  179 .
  180 .IP
  181 This option reads all the JSON texts in the named file and binds an array of the parsed JSON values to the given global variable\. If you run jq with \fB\-\-argfile foo bar\fR, then \fB$foo\fR is available in the program and has an array whose elements correspond to the texts in the file named \fBbar\fR\.
  182 .
  183 .IP "\(bu" 4
  184 \fB\-\-argfile variable\-name filename\fR:
  185 .
  186 .IP
  187 Do not use\. Use \fB\-\-slurpfile\fR instead\.
  188 .
  189 .IP
  190 (This option is like \fB\-\-slurpfile\fR, but when the file has just one text, then that is used, else an array of texts is used as in \fB\-\-slurpfile\fR\.)
  191 .
  192 .IP "\(bu" 4
  193 \fB\-\-args\fR:
  194 .
  195 .IP
  196 Remaining arguments are positional string arguments\. These are available to the jq program as \fB$ARGS\.positional[]\fR\.
  197 .
  198 .IP "\(bu" 4
  199 \fB\-\-jsonargs\fR:
  200 .
  201 .IP
  202 Remaining arguments are positional JSON text arguments\. These are available to the jq program as \fB$ARGS\.positional[]\fR\.
  203 .
  204 .IP "\(bu" 4
  205 \fB\-\-run\-tests [filename]\fR:
  206 .
  207 .IP
  208 Runs the tests in the given file or standard input\. This must be the last option 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\. Compilation failure tests start with a line containing only "%%FAIL", then a line containing the program to compile, then a line containing an error message to compare to the actual\.
  209 .
  210 .IP
  211 Be warned that this option can change backwards\-incompatibly\.
  212 .
  213 .IP "" 0
  214 .
  215 .SH "BASIC FILTERS"
  216 .
  217 .SS "Identity: \."
  218 The absolute simplest filter is \fB\.\fR \. This is a filter that takes its input and produces it unchanged as output\. That is, this is the identity operator\.
  219 .
  220 .P
  221 Since jq by default pretty\-prints all output, this trivial program can be a useful way of formatting JSON output from, say, \fBcurl\fR\.
  222 .
  223 .IP "" 4
  224 .
  225 .nf
  226 
  227 jq \'\.\'
  228    "Hello, world!"
  229 => "Hello, world!"
  230 .
  231 .fi
  232 .
  233 .IP "" 0
  234 .
  235 .SS "Object Identifier\-Index: \.foo, \.foo\.bar"
  236 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\.
  237 .
  238 .P
  239 A filter of the form \fB\.foo\.bar\fR is equivalent to \fB\.foo|\.bar\fR\.
  240 .
  241 .P
  242 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\.
  243 .
  244 .P
  245 If the key contains special characters, you need to surround it with double quotes like this: \fB\."foo$"\fR, or else \fB\.["foo$"]\fR\.
  246 .
  247 .P
  248 For example \fB\.["foo::bar"]\fR and \fB\.["foo\.bar"]\fR work while \fB\.foo::bar\fR does not, and \fB\.foo\.bar\fR means \fB\.["foo"]\.["bar"]\fR\.
  249 .
  250 .IP "" 4
  251 .
  252 .nf
  253 
  254 jq \'\.foo\'
  255    {"foo": 42, "bar": "less interesting data"}
  256 => 42
  257 
  258 jq \'\.foo\'
  259    {"notfoo": true, "alsonotfoo": false}
  260 => null
  261 
  262 jq \'\.["foo"]\'
  263    {"foo": 42}
  264 => 42
  265 .
  266 .fi
  267 .
  268 .IP "" 0
  269 .
  270 .SS "Optional Object Identifier\-Index: \.foo?"
  271 Just like \fB\.foo\fR, but does not output even an error when \fB\.\fR is not an array or an object\.
  272 .
  273 .IP "" 4
  274 .
  275 .nf
  276 
  277 jq \'\.foo?\'
  278    {"foo": 42, "bar": "less interesting data"}
  279 => 42
  280 
  281 jq \'\.foo?\'
  282    {"notfoo": true, "alsonotfoo": false}
  283 => null
  284 
  285 jq \'\.["foo"]?\'
  286    {"foo": 42}
  287 => 42
  288 
  289 jq \'[\.foo?]\'
  290    [1,2]
  291 => []
  292 .
  293 .fi
  294 .
  295 .IP "" 0
  296 .
  297 .SS "Generic Object Index: \.[<string>]"
  298 You can also look up fields of an object using syntax like \fB\.["foo"]\fR (\.foo above is a shorthand version of this, but only for identifier\-like strings)\.
  299 .
  300 .SS "Array Index: \.[2]"
  301 When the index value is an integer, \fB\.[<value>]\fR can index arrays\. Arrays are zero\-based, so \fB\.[2]\fR returns the third element\.
  302 .
  303 .P
  304 Negative indices are allowed, with \-1 referring to the last element, \-2 referring to the next to last element, and so on\.
  305 .
  306 .IP "" 4
  307 .
  308 .nf
  309 
  310 jq \'\.[0]\'
  311    [{"name":"JSON", "good":true}, {"name":"XML", "good":false}]
  312 => {"name":"JSON", "good":true}
  313 
  314 jq \'\.[2]\'
  315    [{"name":"JSON", "good":true}, {"name":"XML", "good":false}]
  316 => null
  317 
  318 jq \'\.[\-2]\'
  319    [1,2,3]
  320 => 2
  321 .
  322 .fi
  323 .
  324 .IP "" 0
  325 .
  326 .SS "Array/String Slice: \.[10:15]"
  327 The \fB\.[10:15]\fR syntax can be used to return a subarray of an array or substring of a string\. The array returned by \fB\.[10:15]\fR will be of length 5, containing 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 array), or omitted (in which case it refers to the start or end of the array)\.
  328 .
  329 .IP "" 4
  330 .
  331 .nf
  332 
  333 jq \'\.[2:4]\'
  334    ["a","b","c","d","e"]
  335 => ["c", "d"]
  336 
  337 jq \'\.[2:4]\'
  338    "abcdefghi"
  339 => "cd"
  340 
  341 jq \'\.[:3]\'
  342    ["a","b","c","d","e"]
  343 => ["a", "b", "c"]
  344 
  345 jq \'\.[\-2:]\'
  346    ["a","b","c","d","e"]
  347 => ["d", "e"]
  348 .
  349 .fi
  350 .
  351 .IP "" 0
  352 .
  353 .SS "Array/Object Value Iterator: \.[]"
  354 If you use the \fB\.[index]\fR syntax, but omit the index entirely, it will return \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\.
  355 .
  356 .P
  357 You can also use this on an object, and it will return all the values of the object\.
  358 .
  359 .IP "" 4
  360 .
  361 .nf
  362 
  363 jq \'\.[]\'
  364    [{"name":"JSON", "good":true}, {"name":"XML", "good":false}]
  365 => {"name":"JSON", "good":true}, {"name":"XML", "good":false}
  366 
  367 jq \'\.[]\'
  368    []
  369 =>
  370 
  371 jq \'\.[]\'
  372    {"a": 1, "b": 1}
  373 => 1, 1
  374 .
  375 .fi
  376 .
  377 .IP "" 0
  378 .
  379 .SS "\.[]?"
  380 Like \fB\.[]\fR, but no errors will be output if \. is not an array or object\.
  381 .
  382 .SS "Comma: ,"
  383 If two filters are separated by a comma, then the same input will be fed into both and the two filters\' output value streams will be concatenated in order: first, all of the outputs produced by the left expression, and then all of the outputs produced by the right\. For instance, filter \fB\.foo, \.bar\fR, produces both the "foo" fields and "bar" fields as separate outputs\.
  384 .
  385 .IP "" 4
  386 .
  387 .nf
  388 
  389 jq \'\.foo, \.bar\'
  390    {"foo": 42, "bar": "something else", "baz": true}
  391 => 42, "something else"
  392 
  393 jq \'\.user, \.projects[]\'
  394    {"user":"stedolan", "projects": ["jq", "wikiflow"]}
  395 => "stedolan", "jq", "wikiflow"
  396 
  397 jq \'\.[4,2]\'
  398    ["a","b","c","d","e"]
  399 => "e", "c"
  400 .
  401 .fi
  402 .
  403 .IP "" 0
  404 .
  405 .SS "Pipe: |"
  406 The | operator combines two filters by feeding the output(s) of the one on the left into the input of the one on the right\. It\'s pretty much the same as the Unix shell\'s pipe, if you\'re used to that\.
  407 .
  408 .P
  409 If the one on the left produces multiple results, the one on the right will be run for each of those results\. So, the expression \fB\.[] | \.foo\fR retrieves the "foo" field of each element of the input array\.
  410 .
  411 .P
  412 Note that \fB\.a\.b\.c\fR is the same as \fB\.a | \.b | \.c\fR\.
  413 .
  414 .P
  415 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\.
  416 .
  417 .IP "" 4
  418 .
  419 .nf
  420 
  421 jq \'\.[] | \.name\'
  422    [{"name":"JSON", "good":true}, {"name":"XML", "good":false}]
  423 => "JSON", "XML"
  424 .
  425 .fi
  426 .
  427 .IP "" 0
  428 .
  429 .SS "Parenthesis"
  430 Parenthesis work as a grouping operator just as in any typical programming language\.
  431 .
  432 .IP "" 4
  433 .
  434 .nf
  435 
  436 jq \'(\. + 2) * 5\'
  437    1
  438 => 15
  439 .
  440 .fi
  441 .
  442 .IP "" 0
  443 .
  444 .SH "TYPES AND VALUES"
  445 jq supports the same set of datatypes as JSON \- numbers, strings, booleans, arrays, objects (which in JSON\-speak are hashes with only string keys), and "null"\.
  446 .
  447 .P
  448 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 an output \- \fB42\fR is a valid jq expression that takes an input, ignores it, and returns 42 instead\.
  449 .
  450 .SS "Array construction: []"
  451 As in JSON, \fB[]\fR is used to construct arrays, as in \fB[1,2,3]\fR\. The elements of the arrays can be any jq expression, including a pipeline\. All of the results produced by all of the expressions are collected into one big array\. You can use it to construct an array out of a known quantity of values (as in \fB[\.foo, \.bar, \.baz]\fR) or to "collect" all the results of a filter into an array (as in \fB[\.items[]\.name]\fR)
  452 .
  453 .P
  454 Once you understand the "," operator, you can look at jq\'s array syntax in a different 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)\.
  455 .
  456 .P
  457 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\.
  458 .
  459 .IP "" 4
  460 .
  461 .nf
  462 
  463 jq \'[\.user, \.projects[]]\'
  464    {"user":"stedolan", "projects": ["jq", "wikiflow"]}
  465 => ["stedolan", "jq", "wikiflow"]
  466 
  467 jq \'[ \.[] | \. * 2]\'
  468    [1, 2, 3]
  469 => [2, 4, 6]
  470 .
  471 .fi
  472 .
  473 .IP "" 0
  474 .
  475 .SS "Object Construction: {}"
  476 Like JSON, \fB{}\fR is for constructing objects (aka dictionaries or hashes), as in: \fB{"a": 42, "b": 17}\fR\.
  477 .
  478 .P
  479 If the keys are "identifier\-like", then the quotes can be left off, as in \fB{a:42, b:17}\fR\. Keys generated by expressions need to be parenthesized, e\.g\., \fB{("a"+"b"):59}\fR\.
  480 .
  481 .P
  482 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)\.
  483 .
  484 .IP "" 4
  485 .
  486 .nf
  487 
  488 {foo: \.bar}
  489 .
  490 .fi
  491 .
  492 .IP "" 0
  493 .
  494 .P
  495 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 of 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
  496 .
  497 .IP "" 4
  498 .
  499 .nf
  500 
  501 {user: \.user, title: \.title}
  502 .
  503 .fi
  504 .
  505 .IP "" 0
  506 .
  507 .P
  508 Because that is so common, there\'s a shortcut syntax for it: \fB{user, title}\fR\.
  509 .
  510 .P
  511 If one of the expressions produces multiple results, multiple dictionaries will be produced\. If the input\'s
  512 .
  513 .IP "" 4
  514 .
  515 .nf
  516 
  517 {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
  518 .
  519 .fi
  520 .
  521 .IP "" 0
  522 .
  523 .P
  524 then the expression
  525 .
  526 .IP "" 4
  527 .
  528 .nf
  529 
  530 {user, title: \.titles[]}
  531 .
  532 .fi
  533 .
  534 .IP "" 0
  535 .
  536 .P
  537 will produce two outputs:
  538 .
  539 .IP "" 4
  540 .
  541 .nf
  542 
  543 {"user":"stedolan", "title": "JQ Primer"}
  544 {"user":"stedolan", "title": "More JQ"}
  545 .
  546 .fi
  547 .
  548 .IP "" 0
  549 .
  550 .P
  551 Putting parentheses around the key means it will be evaluated as an expression\. With the same input as above,
  552 .
  553 .IP "" 4
  554 .
  555 .nf
  556 
  557 {(\.user): \.titles}
  558 .
  559 .fi
  560 .
  561 .IP "" 0
  562 .
  563 .P
  564 produces
  565 .
  566 .IP "" 4
  567 .
  568 .nf
  569 
  570 {"stedolan": ["JQ Primer", "More JQ"]}
  571 
  572 jq \'{user, title: \.titles[]}\'
  573    {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
  574 => {"user":"stedolan", "title": "JQ Primer"}, {"user":"stedolan", "title": "More JQ"}
  575 
  576 jq \'{(\.user): \.titles}\'
  577    {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
  578 => {"stedolan": ["JQ Primer", "More JQ"]}
  579 .
  580 .fi
  581 .
  582 .IP "" 0
  583 .
  584 .SS "Recursive Descent: \.\."
  585 Recursively descends \fB\.\fR, producing every value\. This is the same as the zero\-argument \fBrecurse\fR builtin (see below)\. This is intended to resemble the 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 values of object keys "a" in any object found "below" \fB\.\fR\.
  586 .
  587 .P
  588 This is particularly useful in conjunction with \fBpath(EXP)\fR (also see below) and the \fB?\fR operator\.
  589 .
  590 .IP "" 4
  591 .
  592 .nf
  593 
  594 jq \'\.\.|\.a?\'
  595    [[{"a":1}]]
  596 => 1
  597 .
  598 .fi
  599 .
  600 .IP "" 0
  601 .
  602 .SH "BUILTIN OPERATORS AND FUNCTIONS"
  603 Some jq operator (for instance, \fB+\fR) do different things depending on the type 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\.
  604 .
  605 .SS "Addition: +"
  606 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:
  607 .
  608 .IP "\(bu" 4
  609 \fBNumbers\fR are added by normal arithmetic\.
  610 .
  611 .IP "\(bu" 4
  612 \fBArrays\fR are added by being concatenated into a larger array\.
  613 .
  614 .IP "\(bu" 4
  615 \fBStrings\fR are added by being joined into a larger string\.
  616 .
  617 .IP "\(bu" 4
  618 \fBObjects\fR are added by merging, that is, inserting all the key\-value pairs from both objects into a single combined object\. If both objects contain a value for the same key, the object on the right of the \fB+\fR wins\. (For recursive merge use the \fB*\fR operator\.)
  619 .
  620 .IP "" 0
  621 .
  622 .P
  623 \fBnull\fR can be added to any value, and returns the other value unchanged\.
  624 .
  625 .IP "" 4
  626 .
  627 .nf
  628 
  629 jq \'\.a + 1\'
  630    {"a": 7}
  631 => 8
  632 
  633 jq \'\.a + \.b\'
  634    {"a": [1,2], "b": [3,4]}
  635 => [1,2,3,4]
  636 
  637 jq \'\.a + null\'
  638    {"a": 1}
  639 => 1
  640 
  641 jq \'\.a + 1\'
  642    {}
  643 => 1
  644 
  645 jq \'{a: 1} + {b: 2} + {c: 3} + {a: 42}\'
  646    null
  647 => {"a": 42, "b": 2, "c": 3}
  648 .
  649 .fi
  650 .
  651 .IP "" 0
  652 .
  653 .SS "Subtraction: \-"
  654 As well as normal arithmetic subtraction on numbers, the \fB\-\fR operator can be used on arrays to remove all occurrences of the second array\'s elements from the first array\.
  655 .
  656 .IP "" 4
  657 .
  658 .nf
  659 
  660 jq \'4 \- \.a\'
  661    {"a":3}
  662 => 1
  663 
  664 jq \'\. \- ["xml", "yaml"]\'
  665    ["xml", "yaml", "json"]
  666 => ["json"]
  667 .
  668 .fi
  669 .
  670 .IP "" 0
  671 .
  672 .SS "Multiplication, division, modulo: *, /, and %"
  673 These infix operators behave as expected when given two numbers\. Division by zero raises an error\. \fBx % y\fR computes x modulo y\.
  674 .
  675 .P
  676 Multiplying a string by a number produces the concatenation of that string that many times\. \fB"x" * 0\fR produces \fBnull\fR\.
  677 .
  678 .P
  679 Dividing a string by another splits the first using the second as separators\.
  680 .
  681 .P
  682 Multiplying two objects will merge them recursively: this works like addition but if both objects contain a value for the same key, and the values are objects, the two are merged with the same strategy\.
  683 .
  684 .IP "" 4
  685 .
  686 .nf
  687 
  688 jq \'10 / \. * 3\'
  689    5
  690 => 6
  691 
  692 jq \'\. / ", "\'
  693    "a, b,c,d, e"
  694 => ["a","b,c,d","e"]
  695 
  696 jq \'{"k": {"a": 1, "b": 2}} * {"k": {"a": 0,"c": 3}}\'
  697    null
  698 => {"k": {"a": 0, "b": 2, "c": 3}}
  699 
  700 jq \'\.[] | (1 / \.)?\'
  701    [1,0,\-1]
  702 => 1, \-1
  703 .
  704 .fi
  705 .
  706 .IP "" 0
  707 .
  708 .SS "length"
  709 The builtin function \fBlength\fR gets the length of various different types of value:
  710 .
  711 .IP "\(bu" 4
  712 The length of a \fBstring\fR is the number of Unicode codepoints it contains (which will be the same as its JSON\-encoded length in bytes if it\'s pure ASCII)\.
  713 .
  714 .IP "\(bu" 4
  715 The length of an \fBarray\fR is the number of elements\.
  716 .
  717 .IP "\(bu" 4
  718 The length of an \fBobject\fR is the number of key\-value pairs\.
  719 .
  720 .IP "\(bu" 4
  721 The length of \fBnull\fR is zero\.
  722 .
  723 .IP
  724 jq \'\.[] | length\' [[1,2], "string", {"a":2}, null] => 2, 6, 1, 0
  725 .
  726 .IP "" 0
  727 .
  728 .SS "utf8bytelength"
  729 The builtin function \fButf8bytelength\fR outputs the number of bytes used to encode a string in UTF\-8\.
  730 .
  731 .IP "" 4
  732 .
  733 .nf
  734 
  735 jq \'utf8bytelength\'
  736    "\eu03bc"
  737 => 2
  738 .
  739 .fi
  740 .
  741 .IP "" 0
  742 .
  743 .SS "keys, keys_unsorted"
  744 The builtin function \fBkeys\fR, when given an object, returns its keys in an array\.
  745 .
  746 .P
  747 The keys are sorted "alphabetically", by unicode codepoint order\. This is not an order that makes particular sense in any particular language, but you can count on it being the same for any two objects with the same set of keys, regardless of locale settings\.
  748 .
  749 .P
  750 When \fBkeys\fR is given an array, it returns the valid indices for that array: the integers from 0 to length\-1\.
  751 .
  752 .P
  753 The \fBkeys_unsorted\fR function is just like \fBkeys\fR, but if the input is an object then the keys will not be sorted, instead the keys will roughly be in insertion order\.
  754 .
  755 .IP "" 4
  756 .
  757 .nf
  758 
  759 jq \'keys\'
  760    {"abc": 1, "abcd": 2, "Foo": 3}
  761 => ["Foo", "abc", "abcd"]
  762 
  763 jq \'keys\'
  764    [42,3,35]
  765 => [0,1,2]
  766 .
  767 .fi
  768 .
  769 .IP "" 0
  770 .
  771 .SS "has(key)"
  772 The builtin function \fBhas\fR returns whether the input object has the given key, or the input array has an element at the given index\.
  773 .
  774 .P
  775 \fBhas($key)\fR has the same effect as checking whether \fB$key\fR is a member of the array returned by \fBkeys\fR, although \fBhas\fR will be faster\.
  776 .
  777 .IP "" 4
  778 .
  779 .nf
  780 
  781 jq \'map(has("foo"))\'
  782    [{"foo": 42}, {}]
  783 => [true, false]
  784 
  785 jq \'map(has(2))\'
  786    [[0,1], ["a","b","c"]]
  787 => [false, true]
  788 .
  789 .fi
  790 .
  791 .IP "" 0
  792 .
  793 .SS "in"
  794 The builtin function \fBin\fR returns whether or not the input key is in the given object, or the input index corresponds to an element in the given array\. It is, essentially, an inversed version of \fBhas\fR\.
  795 .
  796 .IP "" 4
  797 .
  798 .nf
  799 
  800 jq \'\.[] | in({"foo": 42})\'
  801    ["foo", "bar"]
  802 => true, false
  803 
  804 jq \'map(in([0,1]))\'
  805    [2, 0]
  806 => [false, true]
  807 .
  808 .fi
  809 .
  810 .IP "" 0
  811 .
  812 .SS "map(x), map_values(x)"
  813 For any filter \fBx\fR, \fBmap(x)\fR will run that filter for each element of the input array, and return the outputs in a new array\. \fBmap(\.+1)\fR will increment each element of an array of numbers\.
  814 .
  815 .P
  816 Similarly, \fBmap_values(x)\fR will run that filter for each element, but it will return an object when an object is passed\.
  817 .
  818 .P
  819 \fBmap(x)\fR is equivalent to \fB[\.[] | x]\fR\. In fact, this is how it\'s defined\. Similarly, \fBmap_values(x)\fR is defined as \fB\.[] |= x\fR\.
  820 .
  821 .IP "" 4
  822 .
  823 .nf
  824 
  825 jq \'map(\.+1)\'
  826    [1,2,3]
  827 => [2,3,4]
  828 
  829 jq \'map_values(\.+1)\'
  830    {"a": 1, "b": 2, "c": 3}
  831 => {"a": 2, "b": 3, "c": 4}
  832 .
  833 .fi
  834 .
  835 .IP "" 0
  836 .
  837 .SS "path(path_expression)"
  838 Outputs array representations of the given path expression in \fB\.\fR\. The outputs are arrays of strings (object keys) and/or numbers (array indices)\.
  839 .
  840 .P
  841 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 cannot\. For example, \fB\.a\.b\.c\fR is an exact match path expression, while \fB\.a[]\.b\fR is not\.
  842 .
  843 .P
  844 \fBpath(exact_path_expression)\fR will produce the array representation of the path expression even if it does not exist in \fB\.\fR, if \fB\.\fR is \fBnull\fR or an array or an object\.
  845 .
  846 .P
  847 \fBpath(pattern)\fR will produce array representations of the paths matching \fBpattern\fR if the paths exist in \fB\.\fR\.
  848 .
  849 .P
  850 Note that the path expressions are not different from normal expressions\. The expression \fBpath(\.\.|select(type=="boolean"))\fR outputs all the paths to boolean values in \fB\.\fR, and only those paths\.
  851 .
  852 .IP "" 4
  853 .
  854 .nf
  855 
  856 jq \'path(\.a[0]\.b)\'
  857    null
  858 => ["a",0,"b"]
  859 
  860 jq \'[path(\.\.)]\'
  861    {"a":[{"b":1}]}
  862 => [[],["a"],["a",0],["a",0,"b"]]
  863 .
  864 .fi
  865 .
  866 .IP "" 0
  867 .
  868 .SS "del(path_expression)"
  869 The builtin function \fBdel\fR removes a key and its corresponding value from an object\.
  870 .
  871 .IP "" 4
  872 .
  873 .nf
  874 
  875 jq \'del(\.foo)\'
  876    {"foo": 42, "bar": 9001, "baz": 42}
  877 => {"bar": 9001, "baz": 42}
  878 
  879 jq \'del(\.[1, 2])\'
  880    ["foo", "bar", "baz"]
  881 => ["foo"]
  882 .
  883 .fi
  884 .
  885 .IP "" 0
  886 .
  887 .SS "getpath(PATHS)"
  888 The builtin function \fBgetpath\fR outputs the values in \fB\.\fR found at each path in \fBPATHS\fR\.
  889 .
  890 .IP "" 4
  891 .
  892 .nf
  893 
  894 jq \'getpath(["a","b"])\'
  895    null
  896 => null
  897 
  898 jq \'[getpath(["a","b"], ["a","c"])]\'
  899    {"a":{"b":0, "c":1}}
  900 => [0, 1]
  901 .
  902 .fi
  903 .
  904 .IP "" 0
  905 .
  906 .SS "setpath(PATHS; VALUE)"
  907 The builtin function \fBsetpath\fR sets the \fBPATHS\fR in \fB\.\fR to \fBVALUE\fR\.
  908 .
  909 .IP "" 4
  910 .
  911 .nf
  912 
  913 jq \'setpath(["a","b"]; 1)\'
  914    null
  915 => {"a": {"b": 1}}
  916 
  917 jq \'setpath(["a","b"]; 1)\'
  918    {"a":{"b":0}}
  919 => {"a": {"b": 1}}
  920 
  921 jq \'setpath([0,"a"]; 1)\'
  922    null
  923 => [{"a":1}]
  924 .
  925 .fi
  926 .
  927 .IP "" 0
  928 .
  929 .SS "delpaths(PATHS)"
  930 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\.
  931 .
  932 .IP "" 4
  933 .
  934 .nf
  935 
  936 jq \'delpaths([["a","b"]])\'
  937    {"a":{"b":1},"x":{"y":2}}
  938 => {"a":{},"x":{"y":2}}
  939 .
  940 .fi
  941 .
  942 .IP "" 0
  943 .
  944 .SS "to_entries, from_entries, with_entries"
  945 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 input, the output array includes \fB{"key": k, "value": v}\fR\.
  946 .
  947 .P
  948 \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 some operation to all keys and values of an object\. \fBfrom_entries\fR accepts key, Key, name, Name, value and Value as keys\.
  949 .
  950 .IP "" 4
  951 .
  952 .nf
  953 
  954 jq \'to_entries\'
  955    {"a": 1, "b": 2}
  956 => [{"key":"a", "value":1}, {"key":"b", "value":2}]
  957 
  958 jq \'from_entries\'
  959    [{"key":"a", "value":1}, {"key":"b", "value":2}]
  960 => {"a": 1, "b": 2}
  961 
  962 jq \'with_entries(\.key |= "KEY_" + \.)\'
  963    {"a": 1, "b": 2}
  964 => {"KEY_a": 1, "KEY_b": 2}
  965 .
  966 .fi
  967 .
  968 .IP "" 0
  969 .
  970 .SS "select(boolean_expression)"
  971 The function \fBselect(foo)\fR produces its input unchanged if \fBfoo\fR returns true for that input, and produces no output otherwise\.
  972 .
  973 .P
  974 It\'s useful for filtering lists: \fB[1,2,3] | map(select(\. >= 2))\fR will give you \fB[2,3]\fR\.
  975 .
  976 .IP "" 4
  977 .
  978 .nf
  979 
  980 jq \'map(select(\. >= 2))\'
  981    [1,5,3,0,7]
  982 => [5,3,7]
  983 
  984 jq \'\.[] | select(\.id == "second")\'
  985    [{"id": "first", "val": 1}, {"id": "second", "val": 2}]
  986 => {"id": "second", "val": 2}
  987 .
  988 .fi
  989 .
  990 .IP "" 0
  991 .
  992 .SS "arrays, objects, iterables, booleans, numbers, normals, finites, strings, nulls, values, scalars"
  993 These built\-ins select only inputs that are arrays, objects, iterables (arrays or objects), booleans, numbers, normal numbers, finite numbers, strings, null, non\-null values, and non\-iterables, respectively\.
  994 .
  995 .IP "" 4
  996 .
  997 .nf
  998 
  999 jq \'\.[]|numbers\'
 1000    [[],{},1,"foo",null,true,false]
 1001 => 1
 1002 .
 1003 .fi
 1004 .
 1005 .IP "" 0
 1006 .
 1007 .SS "empty"
 1008 \fBempty\fR returns no results\. None at all\. Not even \fBnull\fR\.
 1009 .
 1010 .P
 1011 It\'s useful on occasion\. You\'ll know if you need it :)
 1012 .
 1013 .IP "" 4
 1014 .
 1015 .nf
 1016 
 1017 jq \'1, empty, 2\'
 1018    null
 1019 => 1, 2
 1020 
 1021 jq \'[1,2,empty,3]\'
 1022    null
 1023 => [1,2,3]
 1024 .
 1025 .fi
 1026 .
 1027 .IP "" 0
 1028 .
 1029 .SS "error(message)"
 1030 Produces an error, just like \fB\.a\fR applied to values other than null and objects would, but with the given message as the error\'s value\. Errors can be caught with try/catch; see below\.
 1031 .
 1032 .SS "halt"
 1033 Stops the jq program with no further outputs\. jq will exit with exit status \fB0\fR\.
 1034 .
 1035 .SS "halt_error, halt_error(exit_code)"
 1036 Stops the jq program with no further outputs\. The input will be printed on \fBstderr\fR as raw output (i\.e\., strings will not have double quotes) with no decoration, not even a newline\.
 1037 .
 1038 .P
 1039 The given \fBexit_code\fR (defaulting to \fB5\fR) will be jq\'s exit status\.
 1040 .
 1041 .P
 1042 For example, \fB"Error: somthing went wrong\en"|halt_error(1)\fR\.
 1043 .
 1044 .SS "$__loc__"
 1045 Produces an object with a "file" key and a "line" key, with the filename and line number where \fB$__loc__\fR occurs, as values\.
 1046 .
 1047 .IP "" 4
 1048 .
 1049 .nf
 1050 
 1051 jq \'try error("\e($__loc__)") catch \.\'
 1052    null
 1053 => "{\e"file\e":\e"<top\-level>\e",\e"line\e":1}"
 1054 .
 1055 .fi
 1056 .
 1057 .IP "" 0
 1058 .
 1059 .SS "paths, paths(node_filter), leaf_paths"
 1060 \fBpaths\fR outputs the paths to all the elements in its input (except it does not output the empty list, representing \. itself)\.
 1061 .
 1062 .P
 1063 \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\.
 1064 .
 1065 .P
 1066 \fBleaf_paths\fR is an alias of \fBpaths(scalars)\fR; \fBleaf_paths\fR is \fIdeprecated\fR and will be removed in the next major release\.
 1067 .
 1068 .IP "" 4
 1069 .
 1070 .nf
 1071 
 1072 jq \'[paths]\'
 1073    [1,[[],{"a":2}]]
 1074 => [[0],[1],[1,0],[1,1],[1,1,"a"]]
 1075 
 1076 jq \'[paths(scalars)]\'
 1077    [1,[[],{"a":2}]]
 1078 => [[0],[1,1,"a"]]
 1079 .
 1080 .fi
 1081 .
 1082 .IP "" 0
 1083 .
 1084 .SS "add"
 1085 The filter \fBadd\fR takes as input an array, and produces as output the elements of the array added together\. This might mean summed, concatenated or merged depending on the types of the elements of the input array \- the rules are the same as those for the \fB+\fR operator (described above)\.
 1086 .
 1087 .P
 1088 If the input is an empty array, \fBadd\fR returns \fBnull\fR\.
 1089 .
 1090 .IP "" 4
 1091 .
 1092 .nf
 1093 
 1094 jq \'add\'
 1095    ["a","b","c"]
 1096 => "abc"
 1097 
 1098 jq \'add\'
 1099    [1, 2, 3]
 1100 => 6
 1101 
 1102 jq \'add\'
 1103    []
 1104 => null
 1105 .
 1106 .fi
 1107 .
 1108 .IP "" 0
 1109 .
 1110 .SS "any, any(condition), any(generator; condition)"
 1111 The filter \fBany\fR takes as input an array of boolean values, and produces \fBtrue\fR as output if any of the elements of the array are \fBtrue\fR\.
 1112 .
 1113 .P
 1114 If the input is an empty array, \fBany\fR returns \fBfalse\fR\.
 1115 .
 1116 .P
 1117 The \fBany(condition)\fR form applies the given condition to the elements of the input array\.
 1118 .
 1119 .P
 1120 The \fBany(generator; condition)\fR form applies the given condition to all the outputs of the given generator\.
 1121 .
 1122 .IP "" 4
 1123 .
 1124 .nf
 1125 
 1126 jq \'any\'
 1127    [true, false]
 1128 => true
 1129 
 1130 jq \'any\'
 1131    [false, false]
 1132 => false
 1133 
 1134 jq \'any\'
 1135    []
 1136 => false
 1137 .
 1138 .fi
 1139 .
 1140 .IP "" 0
 1141 .
 1142 .SS "all, all(condition), all(generator; condition)"
 1143 The filter \fBall\fR takes as input an array of boolean values, and produces \fBtrue\fR as output if all of the elements of the array are \fBtrue\fR\.
 1144 .
 1145 .P
 1146 The \fBall(condition)\fR form applies the given condition to the elements of the input array\.
 1147 .
 1148 .P
 1149 The \fBall(generator; condition)\fR form applies the given condition to all the outputs of the given generator\.
 1150 .
 1151 .P
 1152 If the input is an empty array, \fBall\fR returns \fBtrue\fR\.
 1153 .
 1154 .IP "" 4
 1155 .
 1156 .nf
 1157 
 1158 jq \'all\'
 1159    [true, false]
 1160 => false
 1161 
 1162 jq \'all\'
 1163    [true, true]
 1164 => true
 1165 
 1166 jq \'all\'
 1167    []
 1168 => true
 1169 .
 1170 .fi
 1171 .
 1172 .IP "" 0
 1173 .
 1174 .SS "flatten, flatten(depth)"
 1175 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 levels of nesting to flatten\.
 1176 .
 1177 .P
 1178 \fBflatten(2)\fR is like \fBflatten\fR, but going only up to two levels deep\.
 1179 .
 1180 .IP "" 4
 1181 .
 1182 .nf
 1183 
 1184 jq \'flatten\'
 1185    [1, [2], [[3]]]
 1186 => [1, 2, 3]
 1187 
 1188 jq \'flatten(1)\'
 1189    [1, [2], [[3]]]
 1190 => [1, 2, [3]]
 1191 
 1192 jq \'flatten\'
 1193    [[]]
 1194 => []
 1195 
 1196 jq \'flatten\'
 1197    [{"foo": "bar"}, [{"foo": "baz"}]]
 1198 => [{"foo": "bar"}, {"foo": "baz"}]
 1199 .
 1200 .fi
 1201 .
 1202 .IP "" 0
 1203 .
 1204 .SS "range(upto), range(from;upto) range(from;upto;by)"
 1205 The \fBrange\fR function produces a range of numbers\. \fBrange(4;10)\fR produces 6 numbers, from 4 (inclusive) to 10 (exclusive)\. The numbers are produced as separate outputs\. Use \fB[range(4;10)]\fR to get a range as an array\.
 1206 .
 1207 .P
 1208 The one argument form generates numbers from 0 to the given number, with an increment of 1\.
 1209 .
 1210 .P
 1211 The two argument form generates numbers from \fBfrom\fR to \fBupto\fR with an increment of 1\.
 1212 .
 1213 .P
 1214 The three argument form generates numbers \fBfrom\fR to \fBupto\fR with an increment of \fBby\fR\.
 1215 .
 1216 .IP "" 4
 1217 .
 1218 .nf
 1219 
 1220 jq \'range(2;4)\'
 1221    null
 1222 => 2, 3
 1223 
 1224 jq \'[range(2;4)]\'
 1225    null
 1226 => [2,3]
 1227 
 1228 jq \'[range(4)]\'
 1229    null
 1230 => [0,1,2,3]
 1231 
 1232 jq \'[range(0;10;3)]\'
 1233    null
 1234 => [0,3,6,9]
 1235 
 1236 jq \'[range(0;10;\-1)]\'
 1237    null
 1238 => []
 1239 
 1240 jq \'[range(0;\-5;\-1)]\'
 1241    null
 1242 => [0,\-1,\-2,\-3,\-4]
 1243 .
 1244 .fi
 1245 .
 1246 .IP "" 0
 1247 .
 1248 .SS "floor"
 1249 The \fBfloor\fR function returns the floor of its numeric input\.
 1250 .
 1251 .IP "" 4
 1252 .
 1253 .nf
 1254 
 1255 jq \'floor\'
 1256    3\.14159
 1257 => 3
 1258 .
 1259 .fi
 1260 .
 1261 .IP "" 0
 1262 .
 1263 .SS "sqrt"
 1264 The \fBsqrt\fR function returns the square root of its numeric input\.
 1265 .
 1266 .IP "" 4
 1267 .
 1268 .nf
 1269 
 1270 jq \'sqrt\'
 1271    9
 1272 => 3
 1273 .
 1274 .fi
 1275 .
 1276 .IP "" 0
 1277 .
 1278 .SS "tonumber"
 1279 The \fBtonumber\fR function parses its input as a number\. It will convert correctly\-formatted strings to their numeric equivalent, leave numbers alone, and give an error on all other input\.
 1280 .
 1281 .IP "" 4
 1282 .
 1283 .nf
 1284 
 1285 jq \'\.[] | tonumber\'
 1286    [1, "1"]
 1287 => 1, 1
 1288 .
 1289 .fi
 1290 .
 1291 .IP "" 0
 1292 .
 1293 .SS "tostring"
 1294 The \fBtostring\fR function prints its input as a string\. Strings are left unchanged, and all other values are JSON\-encoded\.
 1295 .
 1296 .IP "" 4
 1297 .
 1298 .nf
 1299 
 1300 jq \'\.[] | tostring\'
 1301    [1, "1", [1]]
 1302 => "1", "1", "[1]"
 1303 .
 1304 .fi
 1305 .
 1306 .IP "" 0
 1307 .
 1308 .SS "type"
 1309 The \fBtype\fR function returns the type of its argument as a string, which is one of null, boolean, number, string, array or object\.
 1310 .
 1311 .IP "" 4
 1312 .
 1313 .nf
 1314 
 1315 jq \'map(type)\'
 1316    [0, false, [], {}, null, "hello"]
 1317 => ["number", "boolean", "array", "object", "null", "string"]
 1318 .
 1319 .fi
 1320 .
 1321 .IP "" 0
 1322 .
 1323 .SS "infinite, nan, isinfinite, isnan, isfinite, isnormal"
 1324 Some arithmetic operations can yield infinities and "not a number" (NaN) values\. The \fBisinfinite\fR builtin returns \fBtrue\fR if its input is infinite\. The \fBisnan\fR builtin returns \fBtrue\fR if its input is a NaN\. The \fBinfinite\fR builtin returns a positive infinite value\. The \fBnan\fR builtin returns a NaN\. The \fBisnormal\fR builtin returns true if its input is a normal number\.
 1325 .
 1326 .P
 1327 Note that division by zero raises an error\.
 1328 .
 1329 .P
 1330 Currently most arithmetic operations operating on infinities, NaNs, and sub\-normals do not raise errors\.
 1331 .
 1332 .IP "" 4
 1333 .
 1334 .nf
 1335 
 1336 jq \'\.[] | (infinite * \.) < 0\'
 1337    [\-1, 1]
 1338 => true, false
 1339 
 1340 jq \'infinite, nan | type\'
 1341    null
 1342 => "number", "number"
 1343 .
 1344 .fi
 1345 .
 1346 .IP "" 0
 1347 .
 1348 .SS "sort, sort_by(path_expression)"
 1349 The \fBsort\fR functions sorts its input, which must be an array\. Values are sorted in the following order:
 1350 .
 1351 .IP "\(bu" 4
 1352 \fBnull\fR
 1353 .
 1354 .IP "\(bu" 4
 1355 \fBfalse\fR
 1356 .
 1357 .IP "\(bu" 4
 1358 \fBtrue\fR
 1359 .
 1360 .IP "\(bu" 4
 1361 numbers
 1362 .
 1363 .IP "\(bu" 4
 1364 strings, in alphabetical order (by unicode codepoint value)
 1365 .
 1366 .IP "\(bu" 4
 1367 arrays, in lexical order
 1368 .
 1369 .IP "\(bu" 4
 1370 objects
 1371 .
 1372 .IP "" 0
 1373 .
 1374 .P
 1375 The ordering for objects is a little complex: first they\'re compared by comparing their sets of keys (as arrays in sorted order), and if their keys are equal then the values are compared key by key\.
 1376 .
 1377 .P
 1378 \fBsort\fR may be used to sort by a particular field of an object, or by applying any jq filter\.
 1379 .
 1380 .P
 1381 \fBsort_by(foo)\fR compares two elements by comparing the result of \fBfoo\fR on each element\.
 1382 .
 1383 .IP "" 4
 1384 .
 1385 .nf
 1386 
 1387 jq \'sort\'
 1388    [8,3,null,6]
 1389 => [null,3,6,8]
 1390 
 1391 jq \'sort_by(\.foo)\'
 1392    [{"foo":4, "bar":10}, {"foo":3, "bar":100}, {"foo":2, "bar":1}]
 1393 => [{"foo":2, "bar":1}, {"foo":3, "bar":100}, {"foo":4, "bar":10}]
 1394 .
 1395 .fi
 1396 .
 1397 .IP "" 0
 1398 .
 1399 .SS "group_by(path_expression)"
 1400 \fBgroup_by(\.foo)\fR takes as input an array, groups the elements having the same \fB\.foo\fR field into separate arrays, and produces all of these arrays as elements of a larger array, sorted by the value of the \fB\.foo\fR field\.
 1401 .
 1402 .P
 1403 Any jq expression, not just a field access, may be used in place of \fB\.foo\fR\. The sorting order is the same as described in the \fBsort\fR function above\.
 1404 .
 1405 .IP "" 4
 1406 .
 1407 .nf
 1408 
 1409 jq \'group_by(\.foo)\'
 1410    [{"foo":1, "bar":10}, {"foo":3, "bar":100}, {"foo":1, "bar":1}]
 1411 => [[{"foo":1, "bar":10}, {"foo":1, "bar":1}], [{"foo":3, "bar":100}]]
 1412 .
 1413 .fi
 1414 .
 1415 .IP "" 0
 1416 .
 1417 .SS "min, max, min_by(path_exp), max_by(path_exp)"
 1418 Find the minimum or maximum element of the input array\.
 1419 .
 1420 .P
 1421 The \fBmin_by(path_exp)\fR and \fBmax_by(path_exp)\fR functions allow you to specify a particular field or property to examine, e\.g\. \fBmin_by(\.foo)\fR finds the object with the smallest \fBfoo\fR field\.
 1422 .
 1423 .IP "" 4
 1424 .
 1425 .nf
 1426 
 1427 jq \'min\'
 1428    [5,4,2,7]
 1429 => 2
 1430 
 1431 jq \'max_by(\.foo)\'
 1432    [{"foo":1, "bar":14}, {"foo":2, "bar":3}]
 1433 => {"foo":2, "bar":3}
 1434 .
 1435 .fi
 1436 .
 1437 .IP "" 0
 1438 .
 1439 .SS "unique, unique_by(path_exp)"
 1440 The \fBunique\fR function takes as input an array and produces an array of the same elements, in sorted order, with duplicates removed\.
 1441 .
 1442 .P
 1443 The \fBunique_by(path_exp)\fR function will keep only one element for each value obtained by applying the argument\. Think of it as making an array by taking one element out of every group produced by \fBgroup\fR\.
 1444 .
 1445 .IP "" 4
 1446 .
 1447 .nf
 1448 
 1449 jq \'unique\'
 1450    [1,2,5,3,5,3,1,3]
 1451 => [1,2,3,5]
 1452 
 1453 jq \'unique_by(\.foo)\'
 1454    [{"foo": 1, "bar": 2}, {"foo": 1, "bar": 3}, {"foo": 4, "bar": 5}]
 1455 => [{"foo": 1, "bar": 2}, {"foo": 4, "bar": 5}]
 1456 
 1457 jq \'unique_by(length)\'
 1458    ["chunky", "bacon", "kitten", "cicada", "asparagus"]
 1459 => ["bacon", "chunky", "asparagus"]
 1460 .
 1461 .fi
 1462 .
 1463 .IP "" 0
 1464 .
 1465 .SS "reverse"
 1466 This function reverses an array\.
 1467 .
 1468 .IP "" 4
 1469 .
 1470 .nf
 1471 
 1472 jq \'reverse\'
 1473    [1,2,3,4]
 1474 => [4,3,2,1]
 1475 .
 1476 .fi
 1477 .
 1478 .IP "" 0
 1479 .
 1480 .SS "contains(element)"
 1481 The filter \fBcontains(b)\fR will produce true if b is completely contained within the input\. A string B is contained in a string A if B is a substring of A\. An array B is contained in an array A if all elements in B are contained in any element in A\. An object B is contained in object A if all of the values in B are contained in the value in A with the same key\. All other types are assumed to be contained in each other if they are equal\.
 1482 .
 1483 .IP "" 4
 1484 .
 1485 .nf
 1486 
 1487 jq \'contains("bar")\'
 1488    "foobar"
 1489 => true
 1490 
 1491 jq \'contains(["baz", "bar"])\'
 1492    ["foobar", "foobaz", "blarp"]
 1493 => true
 1494 
 1495 jq \'contains(["bazzzzz", "bar"])\'
 1496    ["foobar", "foobaz", "blarp"]
 1497 => false
 1498 
 1499 jq \'contains({foo: 12, bar: [{barp: 12}]})\'
 1500    {"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]}
 1501 => true
 1502 
 1503 jq \'contains({foo: 12, bar: [{barp: 15}]})\'
 1504    {"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]}
 1505 => false
 1506 .
 1507 .fi
 1508 .
 1509 .IP "" 0
 1510 .
 1511 .SS "indices(s)"
 1512 Outputs an array containing the indices in \fB\.\fR where \fBs\fR occurs\. The input may be an array, in which case if \fBs\fR is an array then the indices output will be those where all elements in \fB\.\fR match those of \fBs\fR\.
 1513 .
 1514 .IP "" 4
 1515 .
 1516 .nf
 1517 
 1518 jq \'indices(", ")\'
 1519    "a,b, cd, efg, hijk"
 1520 => [3,7,12]
 1521 
 1522 jq \'indices(1)\'
 1523    [0,1,2,1,3,1,4]
 1524 => [1,3,5]
 1525 
 1526 jq \'indices([1,2])\'
 1527    [0,1,2,3,1,4,2,5,1,2,6,7]
 1528 => [1,8]
 1529 .
 1530 .fi
 1531 .
 1532 .IP "" 0
 1533 .
 1534 .SS "index(s), rindex(s)"
 1535 Outputs the index of the first (\fBindex\fR) or last (\fBrindex\fR) occurrence of \fBs\fR in the input\.
 1536 .
 1537 .IP "" 4
 1538 .
 1539 .nf
 1540 
 1541 jq \'index(", ")\'
 1542    "a,b, cd, efg, hijk"
 1543 => 3
 1544 
 1545 jq \'rindex(", ")\'
 1546    "a,b, cd, efg, hijk"
 1547 => 12
 1548 .
 1549 .fi
 1550 .
 1551 .IP "" 0
 1552 .
 1553 .SS "inside"
 1554 The filter \fBinside(b)\fR will produce true if the input is completely contained within b\. It is, essentially, an inversed version of \fBcontains\fR\.
 1555 .
 1556 .IP "" 4
 1557 .
 1558 .nf
 1559 
 1560 jq \'inside("foobar")\'
 1561    "bar"
 1562 => true
 1563 
 1564 jq \'inside(["foobar", "foobaz", "blarp"])\'
 1565    ["baz", "bar"]
 1566 => true
 1567 
 1568 jq \'inside(["foobar", "foobaz", "blarp"])\'
 1569    ["bazzzzz", "bar"]
 1570 => false
 1571 
 1572 jq \'inside({"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]})\'
 1573    {"foo": 12, "bar": [{"barp": 12}]}
 1574 => true
 1575 
 1576 jq \'inside({"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]})\'
 1577    {"foo": 12, "bar": [{"barp": 15}]}
 1578 => false
 1579 .
 1580 .fi
 1581 .
 1582 .IP "" 0
 1583 .
 1584 .SS "startswith(str)"
 1585 Outputs \fBtrue\fR if \. starts with the given string argument\.
 1586 .
 1587 .IP "" 4
 1588 .
 1589 .nf
 1590 
 1591 jq \'[\.[]|startswith("foo")]\'
 1592    ["fo", "foo", "barfoo", "foobar", "barfoob"]
 1593 => [false, true, false, true, false]
 1594 .
 1595 .fi
 1596 .
 1597 .IP "" 0
 1598 .
 1599 .SS "endswith(str)"
 1600 Outputs \fBtrue\fR if \. ends with the given string argument\.
 1601 .
 1602 .IP "" 4
 1603 .
 1604 .nf
 1605 
 1606 jq \'[\.[]|endswith("foo")]\'
 1607    ["foobar", "barfoo"]
 1608 => [false, true]
 1609 .
 1610 .fi
 1611 .
 1612 .IP "" 0
 1613 .
 1614 .SS "combinations, combinations(n)"
 1615 Outputs all combinations of the elements of the arrays in the input array\. If given an argument \fBn\fR, it outputs all combinations of \fBn\fR repetitions of the input array\.
 1616 .
 1617 .IP "" 4
 1618 .
 1619 .nf
 1620 
 1621 jq \'combinations\'
 1622    [[1,2], [3, 4]]
 1623 => [1, 3], [1, 4], [2, 3], [2, 4]
 1624 
 1625 jq \'combinations(2)\'
 1626    [0, 1]
 1627 => [0, 0], [0, 1], [1, 0], [1, 1]
 1628 .
 1629 .fi
 1630 .
 1631 .IP "" 0
 1632 .
 1633 .SS "ltrimstr(str)"
 1634 Outputs its input with the given prefix string removed, if it starts with it\.
 1635 .
 1636 .IP "" 4
 1637 .
 1638 .nf
 1639 
 1640 jq \'[\.[]|ltrimstr("foo")]\'
 1641    ["fo", "foo", "barfoo", "foobar", "afoo"]
 1642 => ["fo","","barfoo","bar","afoo"]
 1643 .
 1644 .fi
 1645 .
 1646 .IP "" 0
 1647 .
 1648 .SS "rtrimstr(str)"
 1649 Outputs its input with the given suffix string removed, if it ends with it\.
 1650 .
 1651 .IP "" 4
 1652 .
 1653 .nf
 1654 
 1655 jq \'[\.[]|rtrimstr("foo")]\'
 1656    ["fo", "foo", "barfoo", "foobar", "foob"]
 1657 => ["fo","","bar","foobar","foob"]
 1658 .
 1659 .fi
 1660 .
 1661 .IP "" 0
 1662 .
 1663 .SS "explode"
 1664 Converts an input string into an array of the string\'s codepoint numbers\.
 1665 .
 1666 .IP "" 4
 1667 .
 1668 .nf
 1669 
 1670 jq \'explode\'
 1671    "foobar"
 1672 => [102,111,111,98,97,114]
 1673 .
 1674 .fi
 1675 .
 1676 .IP "" 0
 1677 .
 1678 .SS "implode"
 1679 The inverse of explode\.
 1680 .
 1681 .IP "" 4
 1682 .
 1683 .nf
 1684 
 1685 jq \'implode\'
 1686    [65, 66, 67]
 1687 => "ABC"
 1688 .
 1689 .fi
 1690 .
 1691 .IP "" 0
 1692 .
 1693 .SS "split(str)"
 1694 Splits an input string on the separator argument\.
 1695 .
 1696 .IP "" 4
 1697 .
 1698 .nf
 1699 
 1700 jq \'split(", ")\'
 1701    "a, b,c,d, e, "
 1702 => ["a","b,c,d","e",""]
 1703 .
 1704 .fi
 1705 .
 1706 .IP "" 0
 1707 .
 1708 .SS "join(str)"
 1709 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")\fR over any input string returns said input string\.
 1710 .
 1711 .P
 1712 Numbers and booleans in the input are converted to strings\. Null values are treated as empty strings\. Arrays and objects in the input are not supported\.
 1713 .
 1714 .IP "" 4
 1715 .
 1716 .nf
 1717 
 1718 jq \'join(", ")\'
 1719    ["a","b,c,d","e"]
 1720 => "a, b,c,d, e"
 1721 
 1722 jq \'join(" ")\'
 1723    ["a",1,2\.3,true,null,false]
 1724 => "a 1 2\.3 true  false"
 1725 .
 1726 .fi
 1727 .
 1728 .IP "" 0
 1729 .
 1730 .SS "ascii_downcase, ascii_upcase"
 1731 Emit a copy of the input string with its alphabetic characters (a\-z and A\-Z) converted to the specified case\.
 1732 .
 1733 .SS "while(cond; update)"
 1734 The \fBwhile(cond; update)\fR function allows you to repeatedly apply an update to \fB\.\fR until \fBcond\fR is false\.
 1735 .
 1736 .P
 1737 Note that \fBwhile(cond; update)\fR is internally defined as a recursive jq function\. Recursive calls within \fBwhile\fR will not consume additional memory if \fBupdate\fR produces at most one output for each input\. See advanced topics below\.
 1738 .
 1739 .IP "" 4
 1740 .
 1741 .nf
 1742 
 1743 jq \'[while(\.<100; \.*2)]\'
 1744    1
 1745 => [1,2,4,8,16,32,64]
 1746 .
 1747 .fi
 1748 .
 1749 .IP "" 0
 1750 .
 1751 .SS "until(cond; next)"
 1752 The \fBuntil(cond; next)\fR function allows you to repeatedly apply the expression \fBnext\fR, initially to \fB\.\fR then to its own output, until \fBcond\fR is true\. For example, this can be used to implement a factorial function (see below)\.
 1753 .
 1754 .P
 1755 Note that \fBuntil(cond; next)\fR is internally defined as a recursive jq function\. Recursive calls within \fBuntil()\fR will not consume additional memory if \fBnext\fR produces at most one output for each input\. See advanced topics below\.
 1756 .
 1757 .IP "" 4
 1758 .
 1759 .nf
 1760 
 1761 jq \'[\.,1]|until(\.[0] < 1; [\.[0] \- 1, \.[1] * \.[0]])|\.[1]\'
 1762    4
 1763 => 24
 1764 .
 1765 .fi
 1766 .
 1767 .IP "" 0
 1768 .
 1769 .SS "recurse(f), recurse, recurse(f; condition), recurse_down"
 1770 The \fBrecurse(f)\fR function allows you to search through a recursive structure, and extract interesting data from all levels\. Suppose your input represents a filesystem:
 1771 .
 1772 .IP "" 4
 1773 .
 1774 .nf
 1775 
 1776 {"name": "/", "children": [
 1777   {"name": "/bin", "children": [
 1778     {"name": "/bin/ls", "children": []},
 1779     {"name": "/bin/sh", "children": []}]},
 1780   {"name": "/home", "children": [
 1781     {"name": "/home/stephen", "children": [
 1782       {"name": "/home/stephen/jq", "children": []}]}]}]}
 1783 .
 1784 .fi
 1785 .
 1786 .IP "" 0
 1787 .
 1788 .P
 1789 Now suppose you want to extract all of the filenames present\. You need to retrieve \fB\.name\fR, \fB\.children[]\.name\fR, \fB\.children[]\.children[]\.name\fR, and so on\. You can do this with:
 1790 .
 1791 .IP "" 4
 1792 .
 1793 .nf
 1794 
 1795 recurse(\.children[]) | \.name
 1796 .
 1797 .fi
 1798 .
 1799 .IP "" 0
 1800 .
 1801 .P
 1802 When called without an argument, \fBrecurse\fR is equivalent to \fBrecurse(\.[]?)\fR\.
 1803 .
 1804 .P
 1805 \fBrecurse(f)\fR is identical to \fBrecurse(f; \. != null)\fR and can be used without concerns about recursion depth\.
 1806 .
 1807 .P
 1808 \fBrecurse(f; condition)\fR is a generator which begins by emitting \. and then emits in turn \.|f, \.|f|f, \.|f|f|f, \.\.\. so long as the computed value satisfies the condition\. For example, to generate all the integers, at least in principle, one could write \fBrecurse(\.+1; true)\fR\.
 1809 .
 1810 .P
 1811 For legacy reasons, \fBrecurse_down\fR exists as an alias to calling \fBrecurse\fR without arguments\. This alias is considered \fIdeprecated\fR and will be removed in the next major release\.
 1812 .
 1813 .P
 1814 The recursive calls in \fBrecurse\fR will not consume additional memory whenever \fBf\fR produces at most a single output for each input\.
 1815 .
 1816 .IP "" 4
 1817 .
 1818 .nf
 1819 
 1820 jq \'recurse(\.foo[])\'
 1821    {"foo":[{"foo": []}, {"foo":[{"foo":[]}]}]}
 1822 => {"foo":[{"foo":[]},{"foo":[{"foo":[]}]}]}, {"foo":[]}, {"foo":[{"foo":[]}]}, {"foo":[]}
 1823 
 1824 jq \'recurse\'
 1825    {"a":0,"b":[1]}
 1826 => {"a":0,"b":[1]}, 0, [1], 1
 1827 
 1828 jq \'recurse(\. * \.; \. < 20)\'
 1829    2
 1830 => 2, 4, 16
 1831 .
 1832 .fi
 1833 .
 1834 .IP "" 0
 1835 .
 1836 .SS "walk(f)"
 1837 The \fBwalk(f)\fR function applies f recursively to every component of the input entity\. When an array is encountered, f is first applied to its elements and then to the array itself; when an object is encountered, f is first applied to all 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 highlights the usefulness of processing the elements of an array of arrays before processing the array itself\. The second example shows how all the keys of all the objects within the input can be considered for alteration\.
 1838 .
 1839 .IP "" 4
 1840 .
 1841 .nf
 1842 
 1843 jq \'walk(if type == "array" then sort else \. end)\'
 1844    [[4, 1, 7], [8, 5, 2], [3, 6, 9]]
 1845 => [[1,4,7],[2,5,8],[3,6,9]]
 1846 
 1847 jq \'walk( if type == "object" then with_entries( \.key |= sub( "^_+"; "") ) else \. end )\'
 1848    [ { "_a": { "__b": 2 } } ]
 1849 => [{"a":{"b":2}}]
 1850 .
 1851 .fi
 1852 .
 1853 .IP "" 0
 1854 .
 1855 .SS "$ENV, env"
 1856 \fB$ENV\fR is an object representing the environment variables as set when the jq program started\.
 1857 .
 1858 .P
 1859 \fBenv\fR outputs an object representing jq\'s current environment\.
 1860 .
 1861 .P
 1862 At the moment there is no builtin for setting environment variables\.
 1863 .
 1864 .IP "" 4
 1865 .
 1866 .nf
 1867 
 1868 jq \'$ENV\.PAGER\'
 1869    null
 1870 => "less"
 1871 
 1872 jq \'env\.PAGER\'
 1873    null
 1874 => "less"
 1875 .
 1876 .fi
 1877 .
 1878 .IP "" 0
 1879 .
 1880 .SS "transpose"
 1881 Transpose a possibly jagged matrix (an array of arrays)\. Rows are padded with nulls so the result is always rectangular\.
 1882 .
 1883 .IP "" 4
 1884 .
 1885 .nf
 1886 
 1887 jq \'transpose\'
 1888    [[1], [2,3]]
 1889 => [[1,2],[null,3]]
 1890 .
 1891 .fi
 1892 .
 1893 .IP "" 0
 1894 .
 1895 .SS "bsearch(x)"
 1896 bsearch(x) conducts a binary search for x in the input array\. If the input is sorted and contains x, then bsearch(x) will return its index in the array; otherwise, if the array is sorted, it will return (\-1 \- ix) where ix is an insertion point such that the array would still be sorted after the insertion of x at ix\. If the array is not sorted, bsearch(x) will return an integer that is probably of no interest\.
 1897 .
 1898 .IP "" 4
 1899 .
 1900 .nf
 1901 
 1902 jq \'bsearch(0)\'
 1903    [0,1]
 1904 => 0
 1905 
 1906 jq \'bsearch(0)\'
 1907    [1,2,3]
 1908 => \-1
 1909 
 1910 jq \'bsearch(4) as $ix | if $ix < 0 then \.[\-(1+$ix)] = 4 else \. end\'
 1911    [1,2,3]
 1912 => [1,2,3,4]
 1913 .
 1914 .fi
 1915 .
 1916 .IP "" 0
 1917 .
 1918 .SS "String interpolation \- \e(foo)"
 1919 Inside a string, you can put an expression inside parens after a backslash\. Whatever the expression returns will be interpolated into the string\.
 1920 .
 1921 .IP "" 4
 1922 .
 1923 .nf
 1924 
 1925 jq \'"The input was \e(\.), which is one less than \e(\.+1)"\'
 1926    42
 1927 => "The input was 42, which is one less than 43"
 1928 .
 1929 .fi
 1930 .
 1931 .IP "" 0
 1932 .
 1933 .SS "Convert to/from JSON"
 1934 The \fBtojson\fR and \fBfromjson\fR builtins dump values as JSON texts or parse JSON texts into values, respectively\. The tojson builtin differs from tostring in that tostring returns strings unmodified, while tojson encodes strings as JSON strings\.
 1935 .
 1936 .IP "" 4
 1937 .
 1938 .nf
 1939 
 1940 jq \'[\.[]|tostring]\'
 1941    [1, "foo", ["foo"]]
 1942 => ["1","foo","[\e"foo\e"]"]
 1943 
 1944 jq \'[\.[]|tojson]\'
 1945    [1, "foo", ["foo"]]
 1946 => ["1","\e"foo\e"","[\e"foo\e"]"]
 1947 
 1948 jq \'[\.[]|tojson|fromjson]\'
 1949    [1, "foo", ["foo"]]
 1950 => [1,"foo",["foo"]]
 1951 .
 1952 .fi
 1953 .
 1954 .IP "" 0
 1955 .
 1956 .SS "Format strings and escaping"
 1957 The \fB@foo\fR syntax is used to format and escape strings, which is useful for building URLs, documents in a language like HTML or XML, and so forth\. \fB@foo\fR can be used as a filter on its own, the possible escapings are:
 1958 .
 1959 .TP
 1960 \fB@text\fR:
 1961 .
 1962 .IP
 1963 Calls \fBtostring\fR, see that function for details\.
 1964 .
 1965 .TP
 1966 \fB@json\fR:
 1967 .
 1968 .IP
 1969 Serializes the input as JSON\.
 1970 .
 1971 .TP
 1972 \fB@html\fR:
 1973 .
 1974 .IP
 1975 Applies HTML/XML escaping, by mapping the characters \fB<>&\'"\fR to their entity equivalents \fB&lt;\fR, \fB&gt;\fR, \fB&amp;\fR, \fB&apos;\fR, \fB&quot;\fR\.
 1976 .
 1977 .TP
 1978 \fB@uri\fR:
 1979 .
 1980 .IP
 1981 Applies percent\-encoding, by mapping all reserved URI characters to a \fB%XX\fR sequence\.
 1982 .
 1983 .TP
 1984 \fB@csv\fR:
 1985 .
 1986 .IP
 1987 The input must be an array, and it is rendered as CSV with double quotes for strings, and quotes escaped by repetition\.
 1988 .
 1989 .TP
 1990 \fB@tsv\fR:
 1991 .
 1992 .IP
 1993 The input must be an array, and it is rendered as TSV (tab\-separated values)\. Each input array will be printed as a single line\. Fields are separated by a single tab (ascii \fB0x09\fR)\. Input characters line\-feed (ascii \fB0x0a\fR), carriage\-return (ascii \fB0x0d\fR), tab (ascii \fB0x09\fR) and backslash (ascii \fB0x5c\fR) will be output as escape sequences \fB\en\fR, \fB\er\fR, \fB\et\fR, \fB\e\e\fR respectively\.
 1994 .
 1995 .TP
 1996 \fB@sh\fR:
 1997 .
 1998 .IP
 1999 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\.
 2000 .
 2001 .TP
 2002 \fB@base64\fR:
 2003 .
 2004 .IP
 2005 The input is converted to base64 as specified by RFC 4648\.
 2006 .
 2007 .TP
 2008 \fB@base64d\fR:
 2009 .
 2010 .IP
 2011 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\.
 2012 .
 2013 .P
 2014 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 literal will \fInot\fR be escaped\. However, all interpolations made inside that string literal will be escaped\. For instance,
 2015 .
 2016 .IP "" 4
 2017 .
 2018 .nf
 2019 
 2020 @uri "https://www\.google\.com/search?q=\e(\.search)"
 2021 .
 2022 .fi
 2023 .
 2024 .IP "" 0
 2025 .
 2026 .P
 2027 will produce the following output for the input \fB{"search":"what is jq?"}\fR:
 2028 .
 2029 .IP "" 4
 2030 .
 2031 .nf
 2032 
 2033 "https://www\.google\.com/search?q=what%20is%20jq%3F"
 2034 .
 2035 .fi
 2036 .
 2037 .IP "" 0
 2038 .
 2039 .P
 2040 Note that the slashes, question mark, etc\. in the URL are not escaped, as they were part of the string literal\.
 2041 .
 2042 .IP "" 4
 2043 .
 2044 .nf
 2045 
 2046 jq \'@html\'
 2047    "This works if x < y"
 2048 => "This works if x &lt; y"
 2049 
 2050 jq \'@sh "echo \e(\.)"\'
 2051    "O\'Hara\'s Ale"
 2052 => "echo \'O\'\e\e\'\'Hara\'\e\e\'\'s Ale\'"
 2053 
 2054 jq \'@base64\'
 2055    "This is a message"
 2056 => "VGhpcyBpcyBhIG1lc3NhZ2U="
 2057 
 2058 jq \'@base64d\'
 2059    "VGhpcyBpcyBhIG1lc3NhZ2U="
 2060 => "This is a message"
 2061 .
 2062 .fi
 2063 .
 2064 .IP "" 0
 2065 .
 2066 .SS "Dates"
 2067 jq provides some basic date handling functionality, with some high\-level and low\-level builtins\. In all cases these builtins deal exclusively with time in UTC\.
 2068 .
 2069 .P
 2070 The \fBfromdateiso8601\fR builtin parses datetimes in the ISO 8601 format to a number of seconds since the Unix epoch (1970\-01\-01T00:00:00Z)\. The \fBtodateiso8601\fR builtin does the inverse\.
 2071 .
 2072 .P
 2073 The \fBfromdate\fR builtin parses datetime strings\. Currently \fBfromdate\fR only supports ISO 8601 datetime strings, but in the future it will attempt to parse datetime strings in more formats\.
 2074 .
 2075 .P
 2076 The \fBtodate\fR builtin is an alias for \fBtodateiso8601\fR\.
 2077 .
 2078 .P
 2079 The \fBnow\fR builtin outputs the current time, in seconds since the Unix epoch\.
 2080 .
 2081 .P
 2082 Low\-level jq interfaces to the C\-library time functions are also provided: \fBstrptime\fR, \fBstrftime\fR, \fBstrflocaltime\fR, \fBmktime\fR, \fBgmtime\fR, and \fBlocaltime\fR\. Refer to your host operating system\'s documentation for the format strings used by \fBstrptime\fR and \fBstrftime\fR\. Note: these are not necessarily stable interfaces in jq, particularly as to their localization functionality\.
 2083 .
 2084 .P
 2085 The \fBgmtime\fR builtin consumes a number of seconds since the Unix epoch and outputs a "broken down time" representation of Greenwhich Meridian time as an array of numbers representing (in this order): the year, the month (zero\-based), the day of the month (one\-based), 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 day of the week number may be wrong on some systems for dates before March 1st 1900, or after December 31 2099\.
 2086 .
 2087 .P
 2088 The \fBlocaltime\fR builtin works like the \fBgmtime\fR builtin, but using the local timezone setting\.
 2089 .
 2090 .P
 2091 The \fBmktime\fR builtin consumes "broken down time" representations of time output by \fBgmtime\fR and \fBstrptime\fR\.
 2092 .
 2093 .P
 2094 The \fBstrptime(fmt)\fR builtin parses input strings matching the \fBfmt\fR argument\. The output is in the "broken down time" representation consumed by \fBgmtime\fR and output by \fBmktime\fR\.
 2095 .
 2096 .P
 2097 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\.
 2098 .
 2099 .P
 2100 The format strings for \fBstrptime\fR and \fBstrftime\fR are described in typical C library documentation\. The format string for ISO 8601 datetime is \fB"%Y\-%m\-%dT%H:%M:%SZ"\fR\.
 2101 .
 2102 .P
 2103 jq may not support some or all of this date functionality on some systems\. In particular, the \fB%u\fR and \fB%j\fR specifiers for \fBstrptime(fmt)\fR are not supported on macOS\.
 2104 .
 2105 .IP "" 4
 2106 .
 2107 .nf
 2108 
 2109 jq \'fromdate\'
 2110    "2015\-03\-05T23:51:47Z"
 2111 => 1425599507
 2112 
 2113 jq \'strptime("%Y\-%m\-%dT%H:%M:%SZ")\'
 2114    "2015\-03\-05T23:51:47Z"
 2115 => [2015,2,5,23,51,47,4,63]
 2116 
 2117 jq \'strptime("%Y\-%m\-%dT%H:%M:%SZ")|mktime\'
 2118    "2015\-03\-05T23:51:47Z"
 2119 => 1425599507
 2120 .
 2121 .fi
 2122 .
 2123 .IP "" 0
 2124 .
 2125 .SS "SQL\-Style Operators"
 2126 jq provides a few SQL\-style operators\.
 2127 .
 2128 .TP
 2129 INDEX(stream; index_expression):
 2130 .
 2131 .IP
 2132 This builtin produces an object whose keys are computed by the given index expression applied to each value from the given stream\.
 2133 .
 2134 .TP
 2135 JOIN($idx; stream; idx_expr; join_expr):
 2136 .
 2137 .IP
 2138 This builtin joins the values from the given stream to the given index\. The index\'s keys are computed by applying the given index expression to each value from the given stream\. An array of the value in the stream and the corresponding value from the index is fed to the given join expression to produce each result\.
 2139 .
 2140 .TP
 2141 JOIN($idx; stream; idx_expr):
 2142 .
 2143 .IP
 2144 Same as \fBJOIN($idx; stream; idx_expr; \.)\fR\.
 2145 .
 2146 .TP
 2147 JOIN($idx; idx_expr):
 2148 .
 2149 .IP
 2150 This builtin joins the input \fB\.\fR to the given index, applying the given index expression to \fB\.\fR to compute the index key\. The join operation is as described above\.
 2151 .
 2152 .TP
 2153 IN(s):
 2154 .
 2155 .IP
 2156 This builtin outputs \fBtrue\fR if \fB\.\fR appears in the given stream, otherwise it outputs \fBfalse\fR\.
 2157 .
 2158 .TP
 2159 IN(source; s):
 2160 .
 2161 .IP
 2162 This builtin outputs \fBtrue\fR if any value in the source stream appears in the second stream, otherwise it outputs \fBfalse\fR\.
 2163 .
 2164 .SS "builtins"
 2165 Returns a list of all builtin functions in the format \fBname/arity\fR\. Since functions with the same name but different arities are considered separate functions, \fBall/0\fR, \fBall/1\fR, and \fBall/2\fR would all be present in the list\.
 2166 .
 2167 .SH "CONDITIONALS AND COMPARISONS"
 2168 .
 2169 .SS "==, !="
 2170 The expression \'a == b\' will produce \'true\' if the result of a and b are equal (that is, if they represent equivalent JSON documents) and \'false\' otherwise\. In particular, strings are never considered equal to numbers\. If you\'re coming from Javascript, jq\'s == is like Javascript\'s === \- considering values equal only when they have the same type as well as the same value\.
 2171 .
 2172 .P
 2173 != is "not equal", and \'a != b\' returns the opposite value of \'a == b\'
 2174 .
 2175 .IP "" 4
 2176 .
 2177 .nf
 2178 
 2179 jq \'\.[] == 1\'
 2180    [1, 1\.0, "1", "banana"]
 2181 => true, true, false, false
 2182 .
 2183 .fi
 2184 .
 2185 .IP "" 0
 2186 .
 2187 .SS "if\-then\-else"
 2188 \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\.
 2189 .
 2190 .P
 2191 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 explicit about the condition you want: you can\'t test whether, e\.g\. a string is empty using \fBif \.name then A else B end\fR, you\'ll need something more like \fBif (\.name | length) > 0 then A else B end\fR instead\.
 2192 .
 2193 .P
 2194 If the condition \fBA\fR produces multiple results, then \fBB\fR is evaluated once for each result that is not false or null, and \fBC\fR is evaluated once for each false or null\.
 2195 .
 2196 .P
 2197 More cases can be added to an if using \fBelif A then B\fR syntax\.
 2198 .
 2199 .IP "" 4
 2200 .
 2201 .nf
 2202 
 2203 jq \'if \. == 0 then
 2204 .
 2205 .fi
 2206 .
 2207 .IP "" 0
 2208 .
 2209 .P
 2210 "zero" elif \. == 1 then "one" else "many" end\' 2 => "many"
 2211 .
 2212 .SS ">, >=, <=, <"
 2213 The comparison operators \fB>\fR, \fB>=\fR, \fB<=\fR, \fB<\fR return whether their left argument is greater than, greater than or equal to, less than or equal to or less than their right argument (respectively)\.
 2214 .
 2215 .P
 2216 The ordering is the same as that described for \fBsort\fR, above\.
 2217 .
 2218 .IP "" 4
 2219 .
 2220 .nf
 2221 
 2222 jq \'\. < 5\'
 2223    2
 2224 => true
 2225 .
 2226 .fi
 2227 .
 2228 .IP "" 0
 2229 .
 2230 .SS "and/or/not"
 2231 jq supports the normal Boolean operators and/or/not\. They have the same standard of truth as if expressions \- false and null are considered "false values", and anything else is a "true value"\.
 2232 .
 2233 .P
 2234 If an operand of one of these operators produces multiple results, the operator itself will produce a result for each input\.
 2235 .
 2236 .P
 2237 \fBnot\fR is in fact a builtin function rather than an operator, so it is called as a filter to which things can be piped rather than with special syntax, as in \fB\.foo and \.bar | not\fR\.
 2238 .
 2239 .P
 2240 These three only produce the values "true" and "false", and so are only useful for genuine Boolean operations, rather than the common Perl/Python/Ruby idiom of "value_that_may_be_null or default"\. If you want to use this form of "or", picking between two values rather than evaluating a condition, see the "//" operator below\.
 2241 .
 2242 .IP "" 4
 2243 .
 2244 .nf
 2245 
 2246 jq \'42 and "a string"\'
 2247    null
 2248 => true
 2249 
 2250 jq \'(true, false) or false\'
 2251    null
 2252 => true, false
 2253 
 2254 jq \'(true, true) and (true, false)\'
 2255    null
 2256 => true, false, true, false
 2257 
 2258 jq \'[true, false | not]\'
 2259    null
 2260 => [false, true]
 2261 .
 2262 .fi
 2263 .
 2264 .IP "" 0
 2265 .
 2266 .SS "Alternative operator: //"
 2267 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\.
 2268 .
 2269 .P
 2270 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 Boolean operations)\.
 2271 .
 2272 .IP "" 4
 2273 .
 2274 .nf
 2275 
 2276 jq \'\.foo // 42\'
 2277    {"foo": 19}
 2278 => 19
 2279 
 2280 jq \'\.foo // 42\'
 2281    {}
 2282 => 42
 2283 .
 2284 .fi
 2285 .
 2286 .IP "" 0
 2287 .
 2288 .SS "try\-catch"
 2289 Errors can be caught by using \fBtry EXP catch EXP\fR\. The first expression is executed, and if it fails then the second is executed with the error message\. The output of the handler, if any, is output as if it had been the output of the expression to try\.
 2290 .
 2291 .P
 2292 The \fBtry EXP\fR form uses \fBempty\fR as the exception handler\.
 2293 .
 2294 .IP "" 4
 2295 .
 2296 .nf
 2297 
 2298 jq \'try \.a catch "\. is not an object"\'
 2299    true
 2300 => "\. is not an object"
 2301 
 2302 jq \'[\.[]|try \.a]\'
 2303    [{}, true, {"a":1}]
 2304 => [null, 1]
 2305 
 2306 jq \'try error("some exception") catch \.\'
 2307    true
 2308 => "some exception"
 2309 .
 2310 .fi
 2311 .
 2312 .IP "" 0
 2313 .
 2314 .SS "Breaking out of control structures"
 2315 A convenient use of try/catch is to break out of control structures like \fBreduce\fR, \fBforeach\fR, \fBwhile\fR, and so on\.
 2316 .
 2317 .P
 2318 For example:
 2319 .
 2320 .IP "" 4
 2321 .
 2322 .nf
 2323 
 2324 # Repeat an expression until it raises "break" as an
 2325 # error, then stop repeating without re\-raising the error\.
 2326 # But if the error caught is not "break" then re\-raise it\.
 2327 try repeat(exp) catch \.=="break" then empty else error;
 2328 .
 2329 .fi
 2330 .
 2331 .IP "" 0
 2332 .
 2333 .P
 2334 jq has a syntax for named lexical labels to "break" or "go (back) to":
 2335 .
 2336 .IP "" 4
 2337 .
 2338 .nf
 2339 
 2340 label $out | \.\.\. break $out \.\.\.
 2341 .
 2342 .fi
 2343 .
 2344 .IP "" 0
 2345 .
 2346 .P
 2347 The \fBbreak $label_name\fR expression will cause the program to to act as though the nearest (to the left) \fBlabel $label_name\fR produced \fBempty\fR\.
 2348 .
 2349 .P
 2350 The relationship between the \fBbreak\fR and corresponding \fBlabel\fR is lexical: the label has to be "visible" from the break\.
 2351 .
 2352 .P
 2353 To break out of a \fBreduce\fR, for example:
 2354 .
 2355 .IP "" 4
 2356 .
 2357 .nf
 2358 
 2359 label $out | reduce \.[] as $item (null; if \.==false then break $out else \.\.\. end)
 2360 .
 2361 .fi
 2362 .
 2363 .IP "" 0
 2364 .
 2365 .P
 2366 The following jq program produces a syntax error:
 2367 .
 2368 .IP "" 4
 2369 .
 2370 .nf
 2371 
 2372 break $out
 2373 .
 2374 .fi
 2375 .
 2376 .IP "" 0
 2377 .
 2378 .P
 2379 because no label \fB$out\fR is visible\.
 2380 .
 2381 .SS "Error Suppression / Optional Operator: ?"
 2382 The \fB?\fR operator, used as \fBEXP?\fR, is shorthand for \fBtry EXP\fR\.
 2383 .
 2384 .IP "" 4
 2385 .
 2386 .nf
 2387 
 2388 jq \'[\.[]|(\.a)?]\'
 2389    [{}, true, {"a":1}]
 2390 => [null, 1]
 2391 .
 2392 .fi
 2393 .
 2394 .IP "" 0
 2395 .
 2396 .SH "REGULAR EXPRESSIONS (PCRE)"
 2397 jq uses the Oniguruma regular expression library, as do php, ruby, TextMate, Sublime Text, etc, so the description here will focus on jq specifics\.
 2398 .
 2399 .P
 2400 The jq regex filters are defined so that they can be used using one of these patterns:
 2401 .
 2402 .IP "" 4
 2403 .
 2404 .nf
 2405 
 2406 STRING | FILTER( REGEX )
 2407 STRING | FILTER( REGEX; FLAGS )
 2408 STRING | FILTER( [REGEX] )
 2409 STRING | FILTER( [REGEX, FLAGS] )
 2410 .
 2411 .fi
 2412 .
 2413 .IP "" 0
 2414 .
 2415 .P
 2416 where: * STRING, REGEX and FLAGS are jq strings and subject to jq string interpolation; * REGEX, after string interpolation, should be a valid PCRE regex; * FILTER is one of \fBtest\fR, \fBmatch\fR, or \fBcapture\fR, as described below\.
 2417 .
 2418 .P
 2419 FLAGS is a string consisting of one of more of the supported flags:
 2420 .
 2421 .IP "\(bu" 4
 2422 \fBg\fR \- Global search (find all matches, not just the first)
 2423 .
 2424 .IP "\(bu" 4
 2425 \fBi\fR \- Case insensitive search
 2426 .
 2427 .IP "\(bu" 4
 2428 \fBm\fR \- Multi line mode (\'\.\' will match newlines)
 2429 .
 2430 .IP "\(bu" 4
 2431 \fBn\fR \- Ignore empty matches
 2432 .
 2433 .IP "\(bu" 4
 2434 \fBp\fR \- Both s and m modes are enabled
 2435 .
 2436 .IP "\(bu" 4
 2437 \fBs\fR \- Single line mode (\'^\' \-> \'\eA\', \'$\' \-> \'\eZ\')
 2438 .
 2439 .IP "\(bu" 4
 2440 \fBl\fR \- Find longest possible matches
 2441 .
 2442 .IP "\(bu" 4
 2443 \fBx\fR \- Extended regex format (ignore whitespace and comments)
 2444 .
 2445 .IP "" 0
 2446 .
 2447 .P
 2448 To match whitespace in an x pattern use an escape such as \es, e\.g\.
 2449 .
 2450 .IP "\(bu" 4
 2451 test( "a\esb", "x" )\.
 2452 .
 2453 .IP "" 0
 2454 .
 2455 .P
 2456 Note that certain flags may also be specified within REGEX, e\.g\.
 2457 .
 2458 .IP "\(bu" 4
 2459 jq \-n \'("test", "TEst", "teST", "TEST") | test( "(?i)te(?\-i)st" )\'
 2460 .
 2461 .IP "" 0
 2462 .
 2463 .P
 2464 evaluates to: true, true, false, false\.
 2465 .
 2466 .SS "test(val), test(regex; flags)"
 2467 Like \fBmatch\fR, but does not return match objects, only \fBtrue\fR or \fBfalse\fR for whether or not the regex matches the input\.
 2468 .
 2469 .IP "" 4
 2470 .
 2471 .nf
 2472 
 2473 jq \'test("foo")\'
 2474    "foo"
 2475 => true
 2476 
 2477 jq \'\.[] | test("a b c # spaces are ignored"; "ix")\'
 2478    ["xabcd", "ABC"]
 2479 => true, true
 2480 .
 2481 .fi
 2482 .
 2483 .IP "" 0
 2484 .
 2485 .SS "match(val), match(regex; flags)"
 2486 \fBmatch\fR outputs an object for each match it finds\. Matches have the following fields:
 2487 .
 2488 .IP "\(bu" 4
 2489 \fBoffset\fR \- offset in UTF\-8 codepoints from the beginning of the input
 2490 .
 2491 .IP "\(bu" 4
 2492 \fBlength\fR \- length in UTF\-8 codepoints of the match
 2493 .
 2494 .IP "\(bu" 4
 2495 \fBstring\fR \- the string that it matched
 2496 .
 2497 .IP "\(bu" 4
 2498 \fBcaptures\fR \- an array of objects representing capturing groups\.
 2499 .
 2500 .IP "" 0
 2501 .
 2502 .P
 2503 Capturing group objects have the following fields:
 2504 .
 2505 .IP "\(bu" 4
 2506 \fBoffset\fR \- offset in UTF\-8 codepoints from the beginning of the input
 2507 .
 2508 .IP "\(bu" 4
 2509 \fBlength\fR \- length in UTF\-8 codepoints of this capturing group
 2510 .
 2511 .IP "\(bu" 4
 2512 \fBstring\fR \- the string that was captured
 2513 .
 2514 .IP "\(bu" 4
 2515 \fBname\fR \- the name of the capturing group (or \fBnull\fR if it was unnamed)
 2516 .
 2517 .IP "" 0
 2518 .
 2519 .P
 2520 Capturing groups that did not match anything return an offset of \-1
 2521 .
 2522 .IP "" 4
 2523 .
 2524 .nf
 2525 
 2526 jq \'match("(abc)+"; "g")\'
 2527    "abc abc"
 2528 => {"offset": 0, "length": 3, "string": "abc", "captures": [{"offset": 0, "length": 3, "string": "abc", "name": null}]}, {"offset": 4, "length": 3, "string": "abc", "captures": [{"offset": 4, "length": 3, "string": "abc", "name": null}]}
 2529 
 2530 jq \'match("foo")\'
 2531    "foo bar foo"
 2532 => {"offset": 0, "length": 3, "string": "foo", "captures": []}
 2533 
 2534 jq \'match(["foo", "ig"])\'
 2535    "foo bar FOO"
 2536 => {"offset": 0, "length": 3, "string": "foo", "captures": []}, {"offset": 8, "length": 3, "string": "FOO", "captures": []}
 2537 
 2538 jq \'match("foo (?<bar123>bar)? foo"; "ig")\'
 2539    "foo bar foo foo  foo"
 2540 => {"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"}]}
 2541 
 2542 jq \'[ match("\."; "g")] | length\'
 2543    "abc"
 2544 => 3
 2545 .
 2546 .fi
 2547 .
 2548 .IP "" 0
 2549 .
 2550 .SS "capture(val), capture(regex; flags)"
 2551 Collects the named captures in a JSON object, with the name of each capture as the key, and the matched string as the corresponding value\.
 2552 .
 2553 .IP "" 4
 2554 .
 2555 .nf
 2556 
 2557 jq \'capture("(?<a>[a\-z]+)\-(?<n>[0\-9]+)")\'
 2558    "xyzzy\-14"
 2559 => { "a": "xyzzy", "n": "14" }
 2560 .
 2561 .fi
 2562 .
 2563 .IP "" 0
 2564 .
 2565 .SS "scan(regex), scan(regex; flags)"
 2566 Emit a stream of the non\-overlapping substrings of the input that match the regex in accordance with the flags, if any have been specified\. If there is no match, the stream is empty\. To capture all the matches for each input string, use the idiom \fB[ expr ]\fR, e\.g\. \fB[ scan(regex) ]\fR\.
 2567 .
 2568 .SS "split(regex; flags)"
 2569 For backwards compatibility, \fBsplit\fR splits on a string, not a regex\.
 2570 .
 2571 .SS "splits(regex), splits(regex; flags)"
 2572 These provide the same results as their \fBsplit\fR counterparts, but as a stream instead of an array\.
 2573 .
 2574 .SS "sub(regex; tostring) sub(regex; string; flags)"
 2575 Emit the string obtained by replacing the first match of regex in the input string with \fBtostring\fR, after interpolation\. \fBtostring\fR should be a jq string, and may contain references to named captures\. The named captures are, in effect, presented as a JSON object (as constructed by \fBcapture\fR) to \fBtostring\fR, so a reference to a captured variable named "x" would take the form: "(\.x)"\.
 2576 .
 2577 .SS "gsub(regex; string), gsub(regex; string; flags)"
 2578 \fBgsub\fR is like \fBsub\fR but all the non\-overlapping occurrences of the regex are replaced by the string, after interpolation\.
 2579 .
 2580 .SH "ADVANCED FEATURES"
 2581 Variables are an absolute necessity in most programming languages, but they\'re relegated to an "advanced feature" in jq\.
 2582 .
 2583 .P
 2584 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 member, or whatever) in which to place the data\.
 2585 .
 2586 .P
 2587 It is also possible to define functions in jq, although this is is a feature whose biggest use is defining jq\'s standard library (many jq functions such as \fBmap\fR and \fBfind\fR are in fact written in jq)\.
 2588 .
 2589 .P
 2590 jq has reduction operators, which are very powerful but a bit tricky\. Again, these are mostly used internally, to define some useful bits of jq\'s standard library\.
 2591 .
 2592 .P
 2593 It may not be obvious at first, but jq is all about generators (yes, as often found in other languages)\. Some utilities are provided to help deal with generators\.
 2594 .
 2595 .P
 2596 Some minimal I/O support (besides reading JSON from standard input, and writing JSON to standard output) is available\.
 2597 .
 2598 .P
 2599 Finally, there is a module/library system\.
 2600 .
 2601 .SS "Variable / Symbolic Binding Operator: \.\.\. as $identifier | \.\.\."
 2602 In jq, all filters have an input and an output, so manual plumbing is not necessary to pass a value from one part of a program to the next\. Many expressions, for 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\.
 2603 .
 2604 .P
 2605 For instance, calculating the average value of an array of numbers requires a few 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 \fBlength\fR expression is given the array and produces its length\.
 2606 .
 2607 .P
 2608 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 variables using \fBexpression as $variable\fR\. All variable names start with \fB$\fR\. Here\'s a slightly uglier version of the array\-averaging example:
 2609 .
 2610 .IP "" 4
 2611 .
 2612 .nf
 2613 
 2614 length as $array_length | add / $array_length
 2615 .
 2616 .fi
 2617 .
 2618 .IP "" 0
 2619 .
 2620 .P
 2621 We\'ll need a more complicated problem to find a situation where using variables actually makes our lives easier\.
 2622 .
 2623 .P
 2624 Suppose we have an array of blog posts, with "author" and "title" fields, and another object which is used to map author usernames to real names\. Our input looks like:
 2625 .
 2626 .IP "" 4
 2627 .
 2628 .nf
 2629 
 2630 {"posts": [{"title": "Frist psot", "author": "anon"},
 2631            {"title": "A well\-written article", "author": "person1"}],
 2632  "realnames": {"anon": "Anonymous Coward",
 2633                "person1": "Person McPherson"}}
 2634 .
 2635 .fi
 2636 .
 2637 .IP "" 0
 2638 .
 2639 .P
 2640 We want to produce the posts with the author field containing a real name, as in:
 2641 .
 2642 .IP "" 4
 2643 .
 2644 .nf
 2645 
 2646 {"title": "Frist psot", "author": "Anonymous Coward"}
 2647 {"title": "A well\-written article", "author": "Person McPherson"}
 2648 .
 2649 .fi
 2650 .
 2651 .IP "" 0
 2652 .
 2653 .P
 2654 We use a variable, $names, to store the realnames object, so that we can refer to it later when looking up author usernames:
 2655 .
 2656 .IP "" 4
 2657 .
 2658 .nf
 2659 
 2660 \&\.realnames as $names | \.posts[] | {title, author: $names[\.author]}
 2661 .
 2662 .fi
 2663 .
 2664 .IP "" 0
 2665 .
 2666 .P
 2667 The expression \fBexp as $x | \.\.\.\fR means: for each value of expression \fBexp\fR, run the rest of the pipeline with the entire original input, and with \fB$x\fR set to that value\. Thus \fBas\fR functions as something of a foreach loop\.
 2668 .
 2669 .P
 2670 Just as \fB{foo}\fR is a handy way of writing \fB{foo: \.foo}\fR, so \fB{$foo}\fR is a handy way of writing \fB{foo:$foo}\fR\.
 2671 .
 2672 .P
 2673 Multiple variables may be declared using a single \fBas\fR expression by providing a pattern that matches the structure of the input (this is known as "destructuring"):
 2674 .
 2675 .IP "" 4
 2676 .
 2677 .nf
 2678 
 2679 \&\. as {realnames: $names, posts: [$first, $second]} | \.\.\.
 2680 .
 2681 .fi
 2682 .
 2683 .IP "" 0
 2684 .
 2685 .P
 2686 The variable declarations in array patterns (e\.g\., \fB\. as [$first, $second]\fR) bind to the elements of the array in from the element at index zero on up, in order\. When there is no value at the index for an array pattern element, \fBnull\fR is bound to that variable\.
 2687 .
 2688 .P
 2689 Variables are scoped over the rest of the expression that defines them, so
 2690 .
 2691 .IP "" 4
 2692 .
 2693 .nf
 2694 
 2695 \&\.realnames as $names | (\.posts[] | {title, author: $names[\.author]})
 2696 .
 2697 .fi
 2698 .
 2699 .IP "" 0
 2700 .
 2701 .P
 2702 will work, but
 2703 .
 2704 .IP "" 4
 2705 .
 2706 .nf
 2707 
 2708 (\.realnames as $names | \.posts[]) | {title, author: $names[\.author]}
 2709 .
 2710 .fi
 2711 .
 2712 .IP "" 0
 2713 .
 2714 .P
 2715 won\'t\.
 2716 .
 2717 .P
 2718 For programming language theorists, it\'s more accurate to say that jq variables are lexically\-scoped bindings\. In particular there\'s no way to change the value of a binding; one can only setup a new binding with the same name, but which will not be visible where the old one was\.
 2719 .
 2720 .IP "" 4
 2721 .
 2722 .nf
 2723 
 2724 jq \'\.bar as $x | \.foo | \. + $x\'
 2725    {"foo":10, "bar":200}
 2726 => 210
 2727 
 2728 jq \'\. as $i|[(\.*2|\. as $i| $i), $i]\'
 2729    5
 2730 => [10,5]
 2731 
 2732 jq \'\. as [$a, $b, {c: $c}] | $a + $b + $c\'
 2733    [2, 3, {"c": 4, "d": 5}]
 2734 => 9
 2735 
 2736 jq \'\.[] as [$a, $b] | {a: $a, b: $b}\'
 2737    [[0], [0, 1], [2, 1, 0]]
 2738 => {"a":0,"b":null}, {"a":0,"b":1}, {"a":2,"b":1}
 2739 .
 2740 .fi
 2741 .
 2742 .IP "" 0
 2743 .
 2744 .SS "Defining Functions"
 2745 You can give a filter a name using "def" syntax:
 2746 .
 2747 .IP "" 4
 2748 .
 2749 .nf
 2750 
 2751 def increment: \. + 1;
 2752 .
 2753 .fi
 2754 .
 2755 .IP "" 0
 2756 .
 2757 .P
 2758 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 arguments:
 2759 .
 2760 .IP "" 4
 2761 .
 2762 .nf
 2763 
 2764 def map(f): [\.[] | f];
 2765 .
 2766 .fi
 2767 .
 2768 .IP "" 0
 2769 .
 2770 .P
 2771 Arguments are passed as \fIfilters\fR (functions with no arguments), \fInot\fR as values\. The same argument may be referenced 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:
 2772 .
 2773 .IP "" 4
 2774 .
 2775 .nf
 2776 
 2777 def foo(f): f|f;
 2778 5|foo(\.*2)
 2779 .
 2780 .fi
 2781 .
 2782 .IP "" 0
 2783 .
 2784 .P
 2785 The result will be 20 because \fBf\fR is \fB\.*2\fR, and during the first invocation of \fBf\fR \fB\.\fR will be 5, and the second time it will be 10 (5 * 2), so the result will be 20\. Function arguments are filters, and filters expect an input when invoked\.
 2786 .
 2787 .P
 2788 If you want the value\-argument behaviour for defining simple functions, you can just use a variable:
 2789 .
 2790 .IP "" 4
 2791 .
 2792 .nf
 2793 
 2794 def addvalue(f): f as $f | map(\. + $f);
 2795 .
 2796 .fi
 2797 .
 2798 .IP "" 0
 2799 .
 2800 .P
 2801 Or use the short\-hand:
 2802 .
 2803 .IP "" 4
 2804 .
 2805 .nf
 2806 
 2807 def addvalue($f): \.\.\.;
 2808 .
 2809 .fi
 2810 .
 2811 .IP "" 0
 2812 .
 2813 .P
 2814 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\.
 2815 .
 2816 .P
 2817 Multiple definitions using the same function name are allowed\. Each re\-definition replaces the previous one for the same number of function arguments, but only for references from functions (or main program) subsequent to the re\-definition\. See also the section below on scoping\.
 2818 .
 2819 .IP "" 4
 2820 .
 2821 .nf
 2822 
 2823 jq \'def addvalue(f): \. + [f]; map(addvalue(\.[0]))\'
 2824    [[1,2],[10,20]]
 2825 => [[1,2,1], [10,20,10]]
 2826 
 2827 jq \'def addvalue(f): f as $x | map(\. + $x); addvalue(\.[0])\'
 2828    [[1,2],[10,20]]
 2829 => [[1,2,1,2], [10,20,1,2]]
 2830 .
 2831 .fi
 2832 .
 2833 .IP "" 0
 2834 .
 2835 .SS "Scoping"
 2836 There are two types of symbols in jq: value bindings (a\.k\.a\., "variables"), and functions\. Both are scoped lexically, with expressions being able to refer only 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 create recursive functions\.
 2837 .
 2838 .P
 2839 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 as $times_three | [\.+ $times_three]) | \.\.\.\fR: here the binding \fB$times_three\fR is \fInot\fR visible past the closing parenthesis\.
 2840 .
 2841 .SS "Reduce"
 2842 The \fBreduce\fR syntax in jq allows you to combine all of the results of an expression by accumulating them into a single answer\. As an example, we\'ll pass \fB[3,2,1]\fR to this expression:
 2843 .
 2844 .IP "" 4
 2845 .
 2846 .nf
 2847 
 2848 reduce \.[] as $item (0; \. + $item)
 2849 .
 2850 .fi
 2851 .
 2852 .IP "" 0
 2853 .
 2854 .P
 2855 For each result that \fB\.[]\fR produces, \fB\. + $item\fR is run to accumulate a running total, starting from 0\. In this example, \fB\.[]\fR produces the results 3, 2, and 1, so the effect is similar to running something like this:
 2856 .
 2857 .IP "" 4
 2858 .
 2859 .nf
 2860 
 2861 0 | (3 as $item | \. + $item) |
 2862     (2 as $item | \. + $item) |
 2863     (1 as $item | \. + $item)
 2864 
 2865 jq \'reduce \.[] as $item (0; \. + $item)\'
 2866    [10,2,5,3]
 2867 => 20
 2868 .
 2869 .fi
 2870 .
 2871 .IP "" 0
 2872 .
 2873 .SS "isempty(exp)"
 2874 Returns true if \fBexp\fR produces no outputs, false otherwise\.
 2875 .
 2876 .IP "" 4
 2877 .
 2878 .nf
 2879 
 2880 jq \'isempty(empty)\'
 2881    null
 2882 => true
 2883 .
 2884 .fi
 2885 .
 2886 .IP "" 0
 2887 .
 2888 .SS "limit(n; exp)"
 2889 The \fBlimit\fR function extracts up to \fBn\fR outputs from \fBexp\fR\.
 2890 .
 2891 .IP "" 4
 2892 .
 2893 .nf
 2894 
 2895 jq \'[limit(3;\.[])]\'
 2896    [0,1,2,3,4,5,6,7,8,9]
 2897 => [0,1,2]
 2898 .
 2899 .fi
 2900 .
 2901 .IP "" 0
 2902 .
 2903 .SS "first(expr), last(expr), nth(n; expr)"
 2904 The \fBfirst(expr)\fR and \fBlast(expr)\fR functions extract the first and last values from \fBexpr\fR, respectively\.
 2905 .
 2906 .P
 2907 The \fBnth(n; expr)\fR function extracts the nth value output by \fBexpr\fR\. This can be defined as \fBdef nth(n; expr): last(limit(n + 1; expr));\fR\. Note that \fBnth(n; expr)\fR doesn\'t support negative values of \fBn\fR\.
 2908 .
 2909 .IP "" 4
 2910 .
 2911 .nf
 2912 
 2913 jq \'[first(range(\.)), last(range(\.)), nth(\./2; range(\.))]\'
 2914    10
 2915 => [0,9,5]
 2916 .
 2917 .fi
 2918 .
 2919 .IP "" 0
 2920 .
 2921 .SS "first, last, nth(n)"
 2922 The \fBfirst\fR and \fBlast\fR functions extract the first and last values from any array at \fB\.\fR\.
 2923 .
 2924 .P
 2925 The \fBnth(n)\fR function extracts the nth value of any array at \fB\.\fR\.
 2926 .
 2927 .IP "" 4
 2928 .
 2929 .nf
 2930 
 2931 jq \'[range(\.)]|[first, last, nth(5)]\'
 2932    10
 2933 => [0,9,5]
 2934 .
 2935 .fi
 2936 .
 2937 .IP "" 0
 2938 .
 2939 .SS "foreach"
 2940 The \fBforeach\fR syntax is similar to \fBreduce\fR, but intended to allow the construction of \fBlimit\fR and reducers that produce intermediate results (see example)\.
 2941 .
 2942 .P
 2943 The form is \fBforeach EXP as $var (INIT; UPDATE; EXTRACT)\fR\. Like \fBreduce\fR, \fBINIT\fR is evaluated once to produce a state value, then each output of \fBEXP\fR is bound to \fB$var\fR, \fBUPDATE\fR is evaluated for each output of \fBEXP\fR with the current state and with \fB$var\fR visible\. Each value output by \fBUPDATE\fR replaces the previous state\. Finally, \fBEXTRACT\fR is evaluated for each new state to extract an output of \fBforeach\fR\.
 2944 .
 2945 .P
 2946 This is mostly useful only for constructing \fBreduce\fR\- and \fBlimit\fR\-like functions\. But it is much more general, as it allows for partial reductions (see the example below)\.
 2947 .
 2948 .IP "" 4
 2949 .
 2950 .nf
 2951 
 2952 jq \'[foreach \.[] as $item ([[],[]]; if $item == null then [[],\.[0]] else [(\.[0] + [$item]),[]] end; if $item == null then \.[1] else empty end)]\'
 2953    [1,2,3,4,null,"a","b",null]
 2954 => [[1,2,3,4],["a","b"]]
 2955 .
 2956 .fi
 2957 .
 2958 .IP "" 0
 2959 .
 2960 .SS "Recursion"
 2961 As described above, \fBrecurse\fR uses recursion, and any jq function can be recursive\. The \fBwhile\fR builtin is also implemented in terms of recursion\.
 2962 .
 2963 .P
 2964 Tail calls are optimized whenever the expression to the left of the recursive call outputs its last value\. In practice this means that the expression to the left of the recursive call should not produce more than one output for each input\.
 2965 .
 2966 .P
 2967 For example:
 2968 .
 2969 .IP "" 4
 2970 .
 2971 .nf
 2972 
 2973 def recurse(f): def r: \., (f | select(\. != null) | r); r;
 2974 
 2975 def while(cond; update):
 2976   def _while:
 2977     if cond then \., (update | _while) else empty end;
 2978   _while;
 2979 
 2980 def repeat(exp):
 2981   def _repeat:
 2982     exp, _repeat;
 2983   _repeat;
 2984 .
 2985 .fi
 2986 .
 2987 .IP "" 0
 2988 .
 2989 .SS "Generators and iterators"
 2990 Some jq operators and functions are actually generators in that they can produce zero, one, or more values for each input, just as one might expect in other programming languages that have generators\. For example, \fB\.[]\fR generates all the values in its input (which must be an array or an object), \fBrange(0; 10)\fR generates the integers between 0 and 10, and so on\.
 2991 .
 2992 .P
 2993 Even the comma operator is a generator, generating first the values generated by the expression to the left of the comma, then for each of those, the values generate by the expression on the right of the comma\.
 2994 .
 2995 .P
 2996 The \fBempty\fR builtin is the generator that produces zero outputs\. The \fBempty\fR builtin backtracks to the preceding generator expression\.
 2997 .
 2998 .P
 2999 All jq functions can be generators just by using builtin generators\. It is also possible to define new generators using only recursion and the comma operator\. If the recursive call(s) is(are) "in tail position" then the generator will be efficient\. In the example below the recursive call by \fB_range\fR to itself is in tail position\. The example shows off three advanced topics: tail recursion, generator construction, and sub\-functions\.
 3000 .
 3001 .IP "" 4
 3002 .
 3003 .nf
 3004 
 3005 jq \'def range(init; upto; by): def _range: if (by > 0 and \. < upto) or (by < 0 and \. > upto) then \., ((\.+by)|_range) else \. end; if by == 0 then init else init|_range end | select((by > 0 and \. < upto) or (by < 0 and \. > upto)); range(0; 10; 3)\'
 3006    null
 3007 => 0, 3, 6, 9
 3008 
 3009 jq \'def while(cond; update): def _while: if cond then \., (update | _while) else empty end; _while; [while(\.<100; \.*2)]\'
 3010    1
 3011 => [1,2,4,8,16,32,64]
 3012 .
 3013 .fi
 3014 .
 3015 .IP "" 0
 3016 .
 3017 .SH "MATH"
 3018 jq currently only has IEEE754 double\-precision (64\-bit) floating point number support\.
 3019 .
 3020 .P
 3021 Besides simple arithmetic operators such as \fB+\fR, jq also has most standard math functions from the C math library\. C math functions that take a single input 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 available as two\-argument jq functions that ignore \fB\.\fR\. C math functions that take three input arguments are available as three\-argument jq functions that ignore \fB\.\fR\.
 3022 .
 3023 .P
 3024 Availability of standard math functions depends on the availability of the corresponding math functions in your operating system and C math library\. Unavailable math functions will be defined but will raise an error\.
 3025 .
 3026 .P
 3027 One\-input C math functions: \fBacos\fR \fBacosh\fR \fBasin\fR \fBasinh\fR \fBatan\fR \fBatanh\fR \fBcbrt\fR \fBceil\fR \fBcos\fR \fBcosh\fR \fBerf\fR \fBerfc\fR \fBexp\fR \fBexp10\fR \fBexp2\fR \fBexpm1\fR \fBfabs\fR \fBfloor\fR \fBgamma\fR \fBj0\fR \fBj1\fR \fBlgamma\fR \fBlog\fR \fBlog10\fR \fBlog1p\fR \fBlog2\fR \fBlogb\fR \fBnearbyint\fR \fBpow10\fR \fBrint\fR \fBround\fR \fBsignificand\fR \fBsin\fR \fBsinh\fR \fBsqrt\fR \fBtan\fR \fBtanh\fR \fBtgamma\fR \fBtrunc\fR \fBy0\fR \fBy1\fR\.
 3028 .
 3029 .P
 3030 Two\-input C math functions: \fBatan2\fR \fBcopysign\fR \fBdrem\fR \fBfdim\fR \fBfmax\fR \fBfmin\fR \fBfmod\fR \fBfrexp\fR \fBhypot\fR \fBjn\fR \fBldexp\fR \fBmodf\fR \fBnextafter\fR \fBnexttoward\fR \fBpow\fR \fBremainder\fR \fBscalb\fR \fBscalbln\fR \fByn\fR\.
 3031 .
 3032 .P
 3033 Three\-input C math functions: \fBfma\fR\.
 3034 .
 3035 .P
 3036 See your system\'s manual for more information on each of these\.
 3037 .
 3038 .SH "I/O"
 3039 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 named on the command\-line) as jq itself\. These two builtins, and jq\'s own reading actions, can be interleaved with each other\.
 3040 .
 3041 .P
 3042 Two builtins provide minimal output capabilities, \fBdebug\fR, and \fBstderr\fR\. (Recall that a jq program\'s output values are always output as JSON texts on \fBstdout\fR\.) The \fBdebug\fR builtin can have application\-specific behavior, 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\.
 3043 .
 3044 .P
 3045 Most jq builtins are referentially transparent, and yield constant and repeatable value streams when applied to constant inputs\. This is not true of I/O builtins\.
 3046 .
 3047 .SS "input"
 3048 Outputs one new input\.
 3049 .
 3050 .SS "inputs"
 3051 Outputs all remaining inputs, one by one\.
 3052 .
 3053 .P
 3054 This is primarily useful for reductions over a program\'s inputs\.
 3055 .
 3056 .SS "debug"
 3057 Causes a debug message based on the input value to be produced\. The jq executable wraps the input value with \fB["DEBUG:", <input\-value>]\fR and prints that and a newline on stderr, compactly\. This may change in the future\.
 3058 .
 3059 .SS "stderr"
 3060 Prints its input in raw and compact mode to stderr with no additional decoration, not even a newline\.
 3061 .
 3062 .SS "input_filename"
 3063 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\.
 3064 .
 3065 .SS "input_line_number"
 3066 Returns the line number of the input currently being filtered\.
 3067 .
 3068 .SH "STREAMING"
 3069 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 than after the parse completes\. If you have a single JSON text that is 1GB in size, streaming it will allow you to process it much more quickly\.
 3070 .
 3071 .P
 3072 However, streaming isn\'t easy to deal with as the jq program will have \fB[<path>, <leaf\-value>]\fR (and a few other forms) as inputs\.
 3073 .
 3074 .P
 3075 Several builtins are provided to make handling streams easier\.
 3076 .
 3077 .P
 3078 The examples below use the streamed form of \fB[0,[1]]\fR, which is \fB[[0],0],[[1,0],1],[[1,0]],[[1]]\fR\.
 3079 .
 3080 .P
 3081 Streaming forms include \fB[<path>, <leaf\-value>]\fR (to indicate any scalar value, empty array, or empty object), and \fB[<path>]\fR (to indicate the end of an array or object)\. Future versions of jq run with \fB\-\-stream\fR and \fB\-seq\fR may output additional forms such as \fB["error message"]\fR when an input text fails to parse\.
 3082 .
 3083 .SS "truncate_stream(stream_expression)"
 3084 Consumes a number as input and truncates the corresponding number of path elements from the left of the outputs of the given streaming expression\.
 3085 .
 3086 .IP "" 4
 3087 .
 3088 .nf
 3089 
 3090 jq \'[1|truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]])]\'
 3091    1
 3092 => [[[0],2],[[0]]]
 3093 .
 3094 .fi
 3095 .
 3096 .IP "" 0
 3097 .
 3098 .SS "fromstream(stream_expression)"
 3099 Outputs values corresponding to the stream expression\'s outputs\.
 3100 .
 3101 .IP "" 4
 3102 .
 3103 .nf
 3104 
 3105 jq \'fromstream(1|truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]]))\'
 3106    null
 3107 => [2]
 3108 .
 3109 .fi
 3110 .
 3111 .IP "" 0
 3112 .
 3113 .SS "tostream"
 3114 The \fBtostream\fR builtin outputs the streamed form of its input\.
 3115 .
 3116 .IP "" 4
 3117 .
 3118 .nf
 3119 
 3120 jq \'\. as $dot|fromstream($dot|tostream)|\.==$dot\'
 3121    [0,[1,{"a":1},{"b":2}]]
 3122 => true
 3123 .
 3124 .fi
 3125 .
 3126 .IP "" 0
 3127 .
 3128 .SH "ASSIGNMENT"
 3129 Assignment works a little differently in jq than in most programming languages\. jq doesn\'t distinguish between references to and copies of something \- two objects or arrays are either equal or not equal, without any further notion of being "the same object" or "not the same object"\.
 3130 .
 3131 .P
 3132 If an object has two fields which are arrays, \fB\.foo\fR and \fB\.bar\fR, and you append something to \fB\.foo\fR, then \fB\.bar\fR will not get bigger, even if you\'ve previously set \fB\.bar = \.foo\fR\. If you\'re used to programming in languages like Python, Java, Ruby, Javascript, etc\. then you can think of it as though jq does a full deep copy of every object before it does the assignment (for performance it doesn\'t actually do that, but that\'s the general idea)\.
 3133 .
 3134 .P
 3135 This means that it\'s impossible to build circular values in jq (such as an array whose first element is itself)\. This is quite intentional, and ensures that anything a jq program can produce can be represented in JSON\.
 3136 .
 3137 .P
 3138 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\.
 3139 .
 3140 .P
 3141 Values in jq are always immutable\. Internally, assignment works by using a reduction to compute new, replacement values for \fB\.\fR that have had all the desired assignments applied to \fB\.\fR, then outputting the modified value\. This might 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\.
 3142 .
 3143 .P
 3144 Most users will want to use modification assignment operators, such as \fB|=\fR or \fB+=\fR, rather than \fB=\fR\.
 3145 .
 3146 .P
 3147 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 useful path expression in \fB\.\fR); use \fB$var | \.foo = 1\fR instead\.
 3148 .
 3149 .P
 3150 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\.
 3151 .
 3152 .SS "Update\-assignment: |="
 3153 This is the "update" operator \'|=\'\. It 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 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\.
 3154 .
 3155 .P
 3156 The left\-hand side can be any general path expression; see \fBpath()\fR\.
 3157 .
 3158 .P
 3159 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 useful path expression in \fB\.\fR); use \fB$var | \.foo |= \. + 1\fR instead\.
 3160 .
 3161 .P
 3162 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\.
 3163 .
 3164 .P
 3165 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 the last one was used)\.
 3166 .
 3167 .IP "" 4
 3168 .
 3169 .nf
 3170 
 3171 jq \'(\.\.|select(type=="boolean")) |= if \. then 1 else 0 end\'
 3172    [true,false,[5,true,[true,[false]],false]]
 3173 => [1,0,[5,1,[1,[0]],0]]
 3174 .
 3175 .fi
 3176 .
 3177 .IP "" 0
 3178 .
 3179 .SS "Arithmetic update\-assignment: +=, \-=, *=, /=, %=, //="
 3180 jq has a few operators of the form \fBa op= b\fR, which are all equivalent to \fBa |= \. op b\fR\. So, \fB+= 1\fR can be used to increment values, being the same as \fB|= \. + 1\fR\.
 3181 .
 3182 .IP "" 4
 3183 .
 3184 .nf
 3185 
 3186 jq \'\.foo += 1\'
 3187    {"foo": 42}
 3188 => {"foo": 43}
 3189 .
 3190 .fi
 3191 .
 3192 .IP "" 0
 3193 .
 3194 .SS "Plain assignment: ="
 3195 This is the plain assignment operator\. Unlike the others, the input to the right\-hand\-side (RHS) is the same as the input to the left\-hand\-side (LHS) rather than the value at the LHS path, and all values output by the RHS will be used (as shown below)\.
 3196 .
 3197 .P
 3198 If the RHS of \'=\' produces multiple values, then for each such value jq will set the paths on the left\-hand side to the value and then it will output 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 above) do not do this\.
 3199 .
 3200 .P
 3201 This example should show the difference between \'=\' and \'|=\':
 3202 .
 3203 .P
 3204 Provide input \'{"a": {"b": 10}, "b": 20}\' to the programs:
 3205 .
 3206 .P
 3207 \&\.a = \.b
 3208 .
 3209 .P
 3210 \&\.a |= \.b
 3211 .
 3212 .P
 3213 The former will set the "a" field of the input to the "b" field of the input, and produce the output {"a": 20, "b": 20}\. The latter will set the "a" field of the input to the "a" field\'s "b" field, producing {"a": 10, "b": 20}\.
 3214 .
 3215 .P
 3216 Another example of the difference between \'=\' and \'|=\':
 3217 .
 3218 .P
 3219 null|(\.a,\.b)=range(3)
 3220 .
 3221 .P
 3222 outputs \'{"a":0,"b":0}\', \'{"a":1,"b":1}\', and \'{"a":2,"b":2}\', while
 3223 .
 3224 .P
 3225 null|(\.a,\.b)|=range(3)
 3226 .
 3227 .P
 3228 outputs just \'{"a":0,"b":0}\'\.
 3229 .
 3230 .SS "Complex assignments"
 3231 Lots more things are allowed on the left\-hand side of a jq assignment than in most 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:
 3232 .
 3233 .IP "" 4
 3234 .
 3235 .nf
 3236 
 3237 \&\.posts[0]\.title = "JQ Manual"
 3238 .
 3239 .fi
 3240 .
 3241 .IP "" 0
 3242 .
 3243 .P
 3244 What may come as a surprise is that the expression on the left may produce multiple results, referring to different points in the input document:
 3245 .
 3246 .IP "" 4
 3247 .
 3248 .nf
 3249 
 3250 \&\.posts[]\.comments |= \. + ["this is great"]
 3251 .
 3252 .fi
 3253 .
 3254 .IP "" 0
 3255 .
 3256 .P
 3257 That example appends the string "this is great" to the "comments" array of each post in the input (where the input is an object with a field "posts" which is an array of posts)\.
 3258 .
 3259 .P
 3260 When jq encounters an assignment like \'a = b\', it records the "path" taken to select a part of the input document while executing a\. This path is then used to find which part of the input to change while executing the assignment\. Any filter may be used on the left\-hand side of an equals \- whichever paths it selects from the input will be where the assignment is performed\.
 3261 .
 3262 .P
 3263 This is a very powerful operation\. Suppose we wanted to add a comment to blog posts, using the same "blog" input above\. This time, we only want to comment on the posts written by "stedolan"\. We can find those posts using the "select" function described earlier:
 3264 .
 3265 .IP "" 4
 3266 .
 3267 .nf
 3268 
 3269 \&\.posts[] | select(\.author == "stedolan")
 3270 .
 3271 .fi
 3272 .
 3273 .IP "" 0
 3274 .
 3275 .P
 3276 The paths provided by this operation point to each of the posts that "stedolan" wrote, and we can comment on each of them in the same way that we did before:
 3277 .
 3278 .IP "" 4
 3279 .
 3280 .nf
 3281 
 3282 (\.posts[] | select(\.author == "stedolan") | \.comments) |=
 3283     \. + ["terrible\."]
 3284 .
 3285 .fi
 3286 .
 3287 .IP "" 0
 3288 .
 3289 .SH "MODULES"
 3290 jq has a library/module system\. Modules are files whose names end in \fB\.jq\fR\.
 3291 .
 3292 .P
 3293 Modules imported by a program are searched for in a default search path (see below)\. The \fBimport\fR and \fBinclude\fR directives allow the importer to alter this path\.
 3294 .
 3295 .P
 3296 Paths in the a search path are subject to various substitutions\.
 3297 .
 3298 .P
 3299 For paths starting with "~/", the user\'s home directory is substituted for "~"\.
 3300 .
 3301 .P
 3302 For paths starting with "$ORIGIN/", the path of the jq executable is substituted for "$ORIGIN"\.
 3303 .
 3304 .P
 3305 For paths starting with "\./" or paths that are "\.", the path of the including file is substituted for "\."\. For top\-level programs given on the command\-line, the current directory is used\.
 3306 .
 3307 .P
 3308 Import directives can optionally specify a search path to which the default is appended\.
 3309 .
 3310 .P
 3311 The default search path is the search path given to the \fB\-L\fR command\-line option, else \fB["~/\.jq", "$ORIGIN/\.\./lib/jq", "$ORIGIN/\.\./lib"]\fR\.
 3312 .
 3313 .P
 3314 Null and empty string path elements terminate search path processing\.
 3315 .
 3316 .P
 3317 A dependency with relative path "foo/bar" would be searched for in "foo/bar\.jq" and "foo/bar/bar\.jq" in the given search path\. This is intended to allow modules to be placed in a directory along with, for example, version control files, README files, and so on, but also to allow for single\-file modules\.
 3318 .
 3319 .P
 3320 Consecutive components with the same name are not allowed to avoid ambiguities (e\.g\., "foo/foo")\.
 3321 .
 3322 .P
 3323 For example, with \fB\-L$HOME/\.jq\fR a module \fBfoo\fR can be found in \fB$HOME/\.jq/foo\.jq\fR and \fB$HOME/\.jq/foo/foo\.jq\fR\.
 3324 .
 3325 .P
 3326 If "$HOME/\.jq" is a file, it is sourced into the main program\.
 3327 .
 3328 .SS "import RelativePathString as NAME [<metadata>];"
 3329 Imports a module found at the given path relative to a directory in a search path\. A "\.jq" suffix will be added to the relative path string\. The module\'s symbols are prefixed with "NAME::"\.
 3330 .
 3331 .P
 3332 The optional metadata must be a constant jq expression\. It should be an object with keys like "homepage" and so on\. At this time jq only uses the "search" key/value of the metadata\. The metadata is also made available to users via the \fBmodulemeta\fR builtin\.
 3333 .
 3334 .P
 3335 The "search" key in the metadata, if present, should have a string or array value (array of strings); this is the search path to be prefixed to the top\-level search path\.
 3336 .
 3337 .SS "include RelativePathString [<metadata>];"
 3338 Imports a module found at the given path relative to a directory in a search path as if it were included in place\. A "\.jq" suffix will be added to the relative path string\. The module\'s symbols are imported into the caller\'s namespace as if the module\'s content had been included directly\.
 3339 .
 3340 .P
 3341 The optional metadata must be a constant jq expression\. It should be an object with keys like "homepage" and so on\. At this time jq only uses the "search" key/value of the metadata\. The metadata is also made available to users via the \fBmodulemeta\fR builtin\.
 3342 .
 3343 .SS "import RelativePathString as $NAME [<metadata>];"
 3344 Imports a JSON file found at the given path relative to a directory in a search path\. A "\.json" suffix will be added to the relative path string\. The file\'s data will be available as \fB$NAME::NAME\fR\.
 3345 .
 3346 .P
 3347 The optional metadata must be a constant jq expression\. It should be an object with keys like "homepage" and so on\. At this time jq only uses the "search" key/value of the metadata\. The metadata is also made available to users via the \fBmodulemeta\fR builtin\.
 3348 .
 3349 .P
 3350 The "search" key in the metadata, if present, should have a string or array value (array of strings); this is the search path to be prefixed to the top\-level search path\.
 3351 .
 3352 .SS "module <metadata>;"
 3353 This directive is entirely optional\. It\'s not required for proper operation\. It serves only the purpose of providing metadata that can be read with the \fBmodulemeta\fR builtin\.
 3354 .
 3355 .P
 3356 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 available to users via the \fBmodulemeta\fR builtin\.
 3357 .
 3358 .SS "modulemeta"
 3359 Takes a module name as input and outputs the module\'s metadata as an object, with the module\'s imports (including metadata) as an array value for the "deps" key\.
 3360 .
 3361 .P
 3362 Programs can use this to query a module\'s metadata, which they could then use to, for example, search for, download, and install missing dependencies\.
 3363 .
 3364 .SH "COLORS"
 3365 To configure alternative colors just set the \fBJQ_COLORS\fR environment variable to colon\-delimited list of partial terminal escape sequences like \fB"1;31"\fR, in this order:
 3366 .
 3367 .IP "\(bu" 4
 3368 color for \fBnull\fR
 3369 .
 3370 .IP "\(bu" 4
 3371 color for \fBfalse\fR
 3372 .
 3373 .IP "\(bu" 4
 3374 color for \fBtrue\fR
 3375 .
 3376 .IP "\(bu" 4
 3377 color for numbers
 3378 .
 3379 .IP "\(bu" 4
 3380 color for strings
 3381 .
 3382 .IP "\(bu" 4
 3383 color for arrays
 3384 .
 3385 .IP "\(bu" 4
 3386 color for objects
 3387 .
 3388 .IP "" 0
 3389 .
 3390 .P
 3391 The default color scheme is the same as setting \fB"JQ_COLORS=1;30:0;39:0;39:0;39:0;32:1;39:1;39"\fR\.
 3392 .
 3393 .P
 3394 This is not a manual for VT100/ANSI escapes\. However, each of these color specifications should consist of two numbers separated by a semi\-colon, where the first number is one of these:
 3395 .
 3396 .IP "\(bu" 4
 3397 1 (bright)
 3398 .
 3399 .IP "\(bu" 4
 3400 2 (dim)
 3401 .
 3402 .IP "\(bu" 4
 3403 4 (underscore)
 3404 .
 3405 .IP "\(bu" 4
 3406 5 (blink)
 3407 .
 3408 .IP "\(bu" 4
 3409 7 (reverse)
 3410 .
 3411 .IP "\(bu" 4
 3412 8 (hidden)
 3413 .
 3414 .IP "" 0
 3415 .
 3416 .P
 3417 and the second is one of these:
 3418 .
 3419 .IP "\(bu" 4
 3420 30 (black)
 3421 .
 3422 .IP "\(bu" 4
 3423 31 (red)
 3424 .
 3425 .IP "\(bu" 4
 3426 32 (green)
 3427 .
 3428 .IP "\(bu" 4
 3429 33 (yellow)
 3430 .
 3431 .IP "\(bu" 4
 3432 34 (blue)
 3433 .
 3434 .IP "\(bu" 4
 3435 35 (magenta)
 3436 .
 3437 .IP "\(bu" 4
 3438 36 (cyan)
 3439 .
 3440 .IP "\(bu" 4
 3441 37 (white)
 3442 .
 3443 .IP "" 0
 3444 .
 3445 .SH "BUGS"
 3446 Presumably\. Report them or discuss them at:
 3447 .
 3448 .IP "" 4
 3449 .
 3450 .nf
 3451 
 3452 https://github\.com/stedolan/jq/issues
 3453 .
 3454 .fi
 3455 .
 3456 .IP "" 0
 3457 .
 3458 .SH "AUTHOR"
 3459 Stephen Dolan \fB<mu@netsoc\.tcd\.ie>\fR