mirror of
https://github.com/stedolan/jq.git
synced 2024-05-11 05:55:39 +00:00
8435 lines
353 KiB
HTML
8435 lines
353 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<script>
|
|
if ((window.location.host == "jqlang.github.io") && (window.location.protocol != "https:"))
|
|
window.location.protocol = "https";
|
|
</script>
|
|
<meta charset="utf-8">
|
|
<title>jq Manual (development version)</title>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
|
|
<link rel="canonical" href="https://jqlang.github.io/jq/manual/" />
|
|
<link href="https://maxcdn.bootstrapcdn.com/bootswatch/3.3.5/spacelab/bootstrap.min.css" rel="stylesheet" integrity="sha256-j7Dtnd7ZjexEiPNbscbopFn9+Cs0b3TLipKsWAPHZIM= sha512-RFhfi6P8zWMAJrEGU+CPjuxPh3r/UUBGqQ+/o6WKPIVZmQqeOipGotH2ihRULuQ8wsMBoK15TSZqc/7VYWyuIw==" crossorigin="anonymous">
|
|
<link rel="stylesheet" href="/jq/css/base.css" type="text/css">
|
|
<!--[if lt IE 9]>
|
|
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
|
|
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
|
|
<![endif]-->
|
|
</head>
|
|
|
|
<body id="manual" data-spy="scroll" data-target="#navcolumn" data-offset="100">
|
|
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
|
|
<div class="container">
|
|
<div class="navbar-header">
|
|
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#nav-collapse">
|
|
<span class="sr-only">Toggle navigation</span>
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
</button>
|
|
<a class="navbar-brand" href="/jq/">jq</a>
|
|
</div>
|
|
|
|
<div class="navbar-collapse collapse" id="nav-collapse">
|
|
<ul class="nav navbar-nav">
|
|
|
|
<li >
|
|
<a href="/jq/tutorial/">Tutorial</a>
|
|
</li>
|
|
|
|
<li >
|
|
<a href="/jq/download/">Download</a>
|
|
</li>
|
|
|
|
<li class="active" >
|
|
<a href="/jq/manual/">Manual</a>
|
|
</li>
|
|
|
|
<li><a href="https://github.com/jqlang/jq/issues">Issues</a></li>
|
|
<li><a href="https://github.com/jqlang/jq">Source</a></li>
|
|
<li><a href="https://jqplay.org">Try online!</a></li>
|
|
<li><a href="https://raw.githubusercontent.com/jqlang/jq/master/NEWS">News</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="container">
|
|
<div class="row">
|
|
<div class="affix" id="navcolumn">
|
|
<h4>Contents</h4>
|
|
<ul class="nav nav-pills nav-stacked">
|
|
|
|
<li>
|
|
<a href="#Invokingjq">Invoking jq</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Basicfilters">Basic filters</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#TypesandValues">Types and Values</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Builtinoperatorsandfunctions">Builtin operators and functions</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#ConditionalsandComparisons">Conditionals and Comparisons</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Regularexpressions">Regular expressions</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Advancedfeatures">Advanced features</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Math">Math</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#IO">I/O</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Streaming">Streaming</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Assignment">Assignment</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Modules">Modules</a>
|
|
</li>
|
|
|
|
<li>
|
|
<a href="#Colors">Colors</a>
|
|
</li>
|
|
|
|
</ul>
|
|
<form class="form-group" onsubmit="go_to_section(); return false;">
|
|
<input type="text"
|
|
class="form-control"
|
|
placeholder="Search"
|
|
autocomplete="off"
|
|
id="searchbox">
|
|
</form>
|
|
</div>
|
|
|
|
<div id="manualcontent">
|
|
<h1>jq Manual (development version)</h1>
|
|
<p><em>For released versions, see <a href="/jq/manual/v1.6">jq 1.6</a>,
|
|
<a href="/jq/manual/v1.5">jq 1.5</a>, <a href="/jq/manual/v1.4">jq 1.4</a>
|
|
or <a href="/jq/manual/v1.3">jq 1.3</a>.</em></p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>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 <code>add / length</code> - feeding the input array both to the <code>add</code>
|
|
filter and the <code>length</code> filter and then performing the division.</p>
|
|
<p>But that's getting ahead of ourselves. :) Let's start with something
|
|
simpler:</p>
|
|
|
|
<section id="Invokingjq">
|
|
<h2>Invoking jq</h2>
|
|
<p>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 output, as a
|
|
sequence of newline-separated JSON data.</p>
|
|
<p>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, <code>jq
|
|
"foo"</code> will fail on most Unix shells because that will be the same
|
|
as <code>jq foo</code>, which will generally fail because <code>foo is not
|
|
defined</code>. 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 <code>-f program-file</code> option), but then
|
|
double-quotes in the jq program need backslash escaping. When using
|
|
the Powershell (<code>powershell.exe</code>) or the Powershell Core
|
|
(<code>pwsh</code>/<code>pwsh.exe</code>), use single-quote characters around the jq
|
|
program and backslash-escaped double-quotes (<code>\"</code>) inside the jq
|
|
program.</p>
|
|
<ul>
|
|
<li>Unix shells: <code>jq '.["foo"]'</code></li>
|
|
<li>Powershell: <code>jq '.[\"foo\"]'</code></li>
|
|
<li>Windows command shell: <code>jq ".[\"foo\"]"</code></li>
|
|
</ul>
|
|
<p>You can affect how jq reads and writes its input and output
|
|
using some command-line options:</p>
|
|
<ul>
|
|
<li><code>--null-input</code> / <code>-n</code>:</li>
|
|
</ul>
|
|
<p>Don't read any input at all. Instead, the filter is run once
|
|
using <code>null</code> as the input. This is useful when using jq as a
|
|
simple calculator or to construct JSON data from scratch.</p>
|
|
<ul>
|
|
<li><code>--raw-input</code> / <code>-R</code>:</li>
|
|
</ul>
|
|
<p>Don't parse the input as JSON. Instead, each line of text is
|
|
passed to the filter as a string. If combined with <code>--slurp</code>,
|
|
then the entire input is passed to the filter as a single long
|
|
string.</p>
|
|
<ul>
|
|
<li><code>--slurp</code> / <code>-s</code>:</li>
|
|
</ul>
|
|
<p>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.</p>
|
|
<ul>
|
|
<li><code>--compact-output</code> / <code>-c</code>:</li>
|
|
</ul>
|
|
<p>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.</p>
|
|
<ul>
|
|
<li><code>--raw-output</code> / <code>-r</code>:</li>
|
|
</ul>
|
|
<p>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.</p>
|
|
<ul>
|
|
<li><code>--join-output</code> / <code>-j</code>:</li>
|
|
</ul>
|
|
<p>Like <code>-r</code> but jq won't print a newline after each output.</p>
|
|
<ul>
|
|
<li><code>--nul-output</code> / <code>-0</code>:</li>
|
|
</ul>
|
|
<p>Like <code>-r</code> but jq will print NUL instead of newline after each output.
|
|
This can be useful when the values being output can contain newlines.</p>
|
|
<ul>
|
|
<li><code>--ascii-output</code> / <code>-a</code>:</li>
|
|
</ul>
|
|
<p>jq usually outputs non-ASCII Unicode codepoints as UTF-8, even
|
|
if the input specified them as escape sequences (like
|
|
"\u03bc"). Using this option, you can force jq to produce pure
|
|
ASCII output with every non-ASCII character replaced with the
|
|
equivalent escape sequence.</p>
|
|
<ul>
|
|
<li><code>--sort-keys</code> / <code>-S</code>:</li>
|
|
</ul>
|
|
<p>Output the fields of each object with the keys in sorted order.</p>
|
|
<ul>
|
|
<li><code>--color-output</code> / <code>-C</code> and <code>--monochrome-output</code> / <code>-M</code>:</li>
|
|
</ul>
|
|
<p>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 <code>-C</code>, and disable color with <code>-M</code>.
|
|
When the <code>NO_COLOR</code> environment variable is not empty, jq disables
|
|
colored output by default, but you can enable it by <code>-C</code>.</p>
|
|
<p>Colors can be configured with the <code>JQ_COLORS</code> environment
|
|
variable (see below).</p>
|
|
<ul>
|
|
<li><code>--tab</code>:</li>
|
|
</ul>
|
|
<p>Use a tab for each indentation level instead of two spaces.</p>
|
|
<ul>
|
|
<li><code>--indent n</code>:</li>
|
|
</ul>
|
|
<p>Use the given number of spaces (no more than 7) for indentation.</p>
|
|
<ul>
|
|
<li><code>--unbuffered</code>:</li>
|
|
</ul>
|
|
<p>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).</p>
|
|
<ul>
|
|
<li><code>--stream</code>:</li>
|
|
</ul>
|
|
<p>Parse the input in streaming fashion, outputting arrays of path
|
|
and leaf values (scalars and empty arrays or empty objects).
|
|
For example, <code>"a"</code> becomes <code>[[],"a"]</code>, and <code>[[],"a",["b"]]</code>
|
|
becomes <code>[[0],[]]</code>, <code>[[1],"a"]</code>, and <code>[[2,0],"b"]</code>.</p>
|
|
<p>This is useful for processing very large inputs. Use this in
|
|
conjunction with filtering and the <code>reduce</code> and <code>foreach</code> syntax
|
|
to reduce large inputs incrementally.</p>
|
|
<ul>
|
|
<li><code>--stream-errors</code>:</li>
|
|
</ul>
|
|
<p>Like <code>--stream</code>, but invalid JSON inputs yield array values
|
|
where the first element is the error and the second is a path.
|
|
For example, <code>["a",n]</code> produces <code>["Invalid literal at line 1,
|
|
column 7",[1]]</code>.</p>
|
|
<p>Implies <code>--stream</code>. Invalid JSON inputs produce no error values
|
|
when <code>--stream</code> without <code>--stream-errors</code>.</p>
|
|
<ul>
|
|
<li><code>--seq</code>:</li>
|
|
</ul>
|
|
<p>Use the <code>application/json-seq</code> 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 <code>--seq</code>
|
|
option.</p>
|
|
<ul>
|
|
<li><code>-f filename</code> / <code>--from-file filename</code>:</li>
|
|
</ul>
|
|
<p>Read filter from the file rather than from a command line, like
|
|
awk's -f option. You can also use '#' to make comments.</p>
|
|
<ul>
|
|
<li><code>-L directory</code>:</li>
|
|
</ul>
|
|
<p>Prepend <code>directory</code> to the search list for modules. If this
|
|
option is used then no builtin search list is used. See the
|
|
section on modules below.</p>
|
|
<ul>
|
|
<li><code>--arg name value</code>:</li>
|
|
</ul>
|
|
<p>This option passes a value to the jq program as a predefined
|
|
variable. If you run jq with <code>--arg foo bar</code>, then <code>$foo</code> is
|
|
available in the program and has the value <code>"bar"</code>. Note that
|
|
<code>value</code> will be treated as a string, so <code>--arg foo 123</code> will
|
|
bind <code>$foo</code> to <code>"123"</code>.</p>
|
|
<p>Named arguments are also available to the jq program as
|
|
<code>$ARGS.named</code>.</p>
|
|
<ul>
|
|
<li><code>--argjson name JSON-text</code>:</li>
|
|
</ul>
|
|
<p>This option passes a JSON-encoded value to the jq program as a
|
|
predefined variable. If you run jq with <code>--argjson foo 123</code>, then
|
|
<code>$foo</code> is available in the program and has the value <code>123</code>.</p>
|
|
<ul>
|
|
<li><code>--slurpfile variable-name filename</code>:</li>
|
|
</ul>
|
|
<p>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 <code>--slurpfile foo bar</code>, then <code>$foo</code> is available
|
|
in the program and has an array whose elements correspond to the
|
|
texts in the file named <code>bar</code>.</p>
|
|
<ul>
|
|
<li><code>--rawfile variable-name filename</code>:</li>
|
|
</ul>
|
|
<p>This option reads in the named file and binds its contents to the given
|
|
global variable. If you run jq with <code>--rawfile foo bar</code>, then <code>$foo</code> is
|
|
available in the program and has a string whose contents are to the texts
|
|
in the file named <code>bar</code>.</p>
|
|
<ul>
|
|
<li><code>--args</code>:</li>
|
|
</ul>
|
|
<p>Remaining arguments are positional string arguments. These are
|
|
available to the jq program as <code>$ARGS.positional[]</code>.</p>
|
|
<ul>
|
|
<li><code>--jsonargs</code>:</li>
|
|
</ul>
|
|
<p>Remaining arguments are positional JSON text arguments. These
|
|
are available to the jq program as <code>$ARGS.positional[]</code>.</p>
|
|
<ul>
|
|
<li><code>--exit-status</code> / <code>-e</code>:</li>
|
|
</ul>
|
|
<p>Sets the exit status of jq to 0 if the last output value was
|
|
neither <code>false</code> nor <code>null</code>, 1 if the last output value was
|
|
either <code>false</code> or <code>null</code>, 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.</p>
|
|
<p>Another way to set the exit status is with the <code>halt_error</code>
|
|
builtin function.</p>
|
|
<ul>
|
|
<li><code>--binary</code> / <code>-b</code>:</li>
|
|
</ul>
|
|
<p>Windows users using WSL, MSYS2, or Cygwin, should use this option
|
|
when using a native jq.exe, otherwise jq will turn newlines (LFs)
|
|
into carriage-return-then-newline (CRLF).</p>
|
|
<ul>
|
|
<li><code>--version</code> / <code>-V</code>:</li>
|
|
</ul>
|
|
<p>Output the jq version and exit with zero.</p>
|
|
<ul>
|
|
<li><code>--help</code> / <code>-h</code>:</li>
|
|
</ul>
|
|
<p>Output the jq help and exit with zero.</p>
|
|
<ul>
|
|
<li><code>--</code>:</li>
|
|
</ul>
|
|
<p>Terminates argument processing. Remaining arguments are
|
|
positional, either strings, JSON texts, or input filenames,
|
|
according to whether <code>--args</code> or <code>--jsonargs</code> were given.</p>
|
|
<ul>
|
|
<li><code>--run-tests [filename]</code>:</li>
|
|
</ul>
|
|
<p>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 <code>%%FAIL</code>, then a line containing the program to compile,
|
|
then a line containing an error message to compare to the
|
|
actual.</p>
|
|
<p>Be warned that this option can change backwards-incompatibly.</p>
|
|
|
|
</section>
|
|
|
|
<section id="Basicfilters">
|
|
<h2>Basic filters</h2>
|
|
|
|
|
|
<section id="Identity:.">
|
|
<h3>
|
|
Identity: <code>.</code>
|
|
|
|
</h3>
|
|
<p>The absolute simplest filter is <code>.</code> . This filter takes its
|
|
input and produces the same value as output. That is, this
|
|
is the identity operator.</p>
|
|
<p>Since jq by default pretty-prints all output, a trivial
|
|
program consisting of nothing but <code>.</code> can be used to format
|
|
JSON output from, say, <code>curl</code>.</p>
|
|
<p>Although the identity filter never modifies the value of its
|
|
input, jq processing can sometimes make it appear as though
|
|
it does. For example, using the current implementation of
|
|
jq, we would see that the expression:</p>
|
|
<pre><code>1E1234567890 | .
|
|
</code></pre>
|
|
<p>produces <code>1.7976931348623157e+308</code> on at least one platform.
|
|
This is because, in the process of parsing the number, this
|
|
particular version of jq has converted it to an IEEE754
|
|
double-precision representation, losing precision.</p>
|
|
<p>The way in which jq handles numbers has changed over time
|
|
and further changes are likely within the parameters set by
|
|
the relevant JSON standards. The following remarks are
|
|
therefore offered with the understanding that they are
|
|
intended to be descriptive of the current version of jq and
|
|
should not be interpreted as being prescriptive:</p>
|
|
<p>(1) Any arithmetic operation on a number that has not
|
|
already been converted to an IEEE754 double precision
|
|
representation will trigger a conversion to the IEEE754
|
|
representation.</p>
|
|
<p>(2) jq will attempt to maintain the original decimal
|
|
precision of number literals, but in expressions such
|
|
<code>1E1234567890</code>, precision will be lost if the exponent is
|
|
too large.</p>
|
|
<p>(3) In jq programs, a leading minus sign will trigger the
|
|
conversion of the number to an IEEE754 representation.</p>
|
|
<p>(4) Comparisons are carried out using the untruncated
|
|
big decimal representation of numbers if available, as
|
|
illustrated in one of the following examples.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example1">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example1" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.'</td></tr>
|
|
<tr><th>Input</th><td>"Hello, world!"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"Hello, world!"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.'</td></tr>
|
|
<tr><th>Input</th><td>0.12345678901234567890123456789</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>0.12345678901234567890123456789</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[., tojson]'</td></tr>
|
|
<tr><th>Input</th><td>12345678909876543212345</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[12345678909876543212345,"12345678909876543212345"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '. < 0.12345678901234567890123456788'</td></tr>
|
|
<tr><th>Input</th><td>0.12345678901234567890123456789</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'map([., . == 1]) | tojson'</td></tr>
|
|
<tr><th>Input</th><td>[1, 1.000, 1.0, 100e-2]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"[[1,true],[1.000,true],[1.0,true],[1.00,true]]"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '. as $big | [$big, $big + 1] | map(. > 10000000000000000000000000000000)'</td></tr>
|
|
<tr><th>Input</th><td>10000000000000000000000000000001</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[true, false]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="ObjectIdentifier-Index:.foo,.foo.bar">
|
|
<h3>
|
|
Object Identifier-Index: <code>.foo</code>, <code>.foo.bar</code>
|
|
|
|
</h3>
|
|
<p>The simplest <em>useful</em> filter has the form <code>.foo</code>. When given a
|
|
JSON object (aka dictionary or hash) as input, <code>.foo</code> produces
|
|
the value at the key "foo" if the key is present, or null otherwise.</p>
|
|
<p>A filter of the form <code>.foo.bar</code> is equivalent to <code>.foo | .bar</code>.</p>
|
|
<p>The <code>.foo</code> syntax only works for simple, identifier-like keys, that
|
|
is, keys that are all made of alphanumeric characters and
|
|
underscore, and which do not start with a digit.</p>
|
|
<p>If the key contains special characters or starts with a digit,
|
|
you need to surround it with double quotes like this:
|
|
<code>."foo$"</code>, or else <code>.["foo$"]</code>.</p>
|
|
<p>For example <code>.["foo::bar"]</code> and <code>.["foo.bar"]</code> work while
|
|
<code>.foo::bar</code> does not.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example2">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example2" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.foo'</td></tr>
|
|
<tr><th>Input</th><td>{"foo": 42, "bar": "less interesting data"}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>42</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.foo'</td></tr>
|
|
<tr><th>Input</th><td>{"notfoo": true, "alsonotfoo": false}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>null</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.["foo"]'</td></tr>
|
|
<tr><th>Input</th><td>{"foo": 42}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>42</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="OptionalObjectIdentifier-Index:.foo?">
|
|
<h3>
|
|
Optional Object Identifier-Index: <code>.foo?</code>
|
|
|
|
</h3>
|
|
<p>Just like <code>.foo</code>, but does not output an error when <code>.</code> is not an
|
|
object.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example3">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example3" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.foo?'</td></tr>
|
|
<tr><th>Input</th><td>{"foo": 42, "bar": "less interesting data"}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>42</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.foo?'</td></tr>
|
|
<tr><th>Input</th><td>{"notfoo": true, "alsonotfoo": false}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>null</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.["foo"]?'</td></tr>
|
|
<tr><th>Input</th><td>{"foo": 42}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>42</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[.foo?]'</td></tr>
|
|
<tr><th>Input</th><td>[1,2]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="ObjectIndex:.[<string>]">
|
|
<h3>
|
|
Object Index: <code>.[<string>]</code>
|
|
|
|
</h3>
|
|
<p>You can also look up fields of an object using syntax like
|
|
<code>.["foo"]</code> (<code>.foo</code> above is a shorthand version of this, but
|
|
only for identifier-like strings).</p>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="ArrayIndex:.[<number>]">
|
|
<h3>
|
|
Array Index: <code>.[<number>]</code>
|
|
|
|
</h3>
|
|
<p>When the index value is an integer, <code>.[<number>]</code> can index
|
|
arrays. Arrays are zero-based, so <code>.[2]</code> returns the third
|
|
element.</p>
|
|
<p>Negative indices are allowed, with -1 referring to the last
|
|
element, -2 referring to the next to last element, and so on.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example4">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example4" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[0]'</td></tr>
|
|
<tr><th>Input</th><td>[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"name":"JSON", "good":true}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[2]'</td></tr>
|
|
<tr><th>Input</th><td>[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>null</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[-2]'</td></tr>
|
|
<tr><th>Input</th><td>[1,2,3]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>2</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Array/StringSlice:.[<number>:<number>]">
|
|
<h3>
|
|
Array/String Slice: <code>.[<number>:<number>]</code>
|
|
|
|
</h3>
|
|
<p>The <code>.[<number>:<number>]</code> syntax can be used to return a
|
|
subarray of an array or substring of a string. The array
|
|
returned by <code>.[10:15]</code> 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).
|
|
Indices are zero-based.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example5">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example5" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[2:4]'</td></tr>
|
|
<tr><th>Input</th><td>["a","b","c","d","e"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["c", "d"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[2:4]'</td></tr>
|
|
<tr><th>Input</th><td>"abcdefghi"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"cd"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[:3]'</td></tr>
|
|
<tr><th>Input</th><td>["a","b","c","d","e"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["a", "b", "c"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[-2:]'</td></tr>
|
|
<tr><th>Input</th><td>["a","b","c","d","e"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["d", "e"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Array/ObjectValueIterator:.[]">
|
|
<h3>
|
|
Array/Object Value Iterator: <code>.[]</code>
|
|
|
|
</h3>
|
|
<p>If you use the <code>.[index]</code> syntax, but omit the index
|
|
entirely, it will return <em>all</em> of the elements of an
|
|
array. Running <code>.[]</code> with the input <code>[1,2,3]</code> will produce the
|
|
numbers as three separate results, rather than as a single
|
|
array. A filter of the form <code>.foo[]</code> is equivalent to
|
|
<code>.foo | .[]</code>.</p>
|
|
<p>You can also use this on an object, and it will return all
|
|
the values of the object.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example6">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example6" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[]'</td></tr>
|
|
<tr><th>Input</th><td>[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"name":"JSON", "good":true}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"name":"XML", "good":false}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[]'</td></tr>
|
|
<tr><th>Input</th><td>[]</td></tr>
|
|
|
|
<tr>
|
|
<th>Output</th>
|
|
<td><i>none</i></td>
|
|
</tr>
|
|
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.foo[]'</td></tr>
|
|
<tr><th>Input</th><td>{"foo":[1,2,3]}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>2</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>3</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[]'</td></tr>
|
|
<tr><th>Input</th><td>{"a": 1, "b": 1}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id=".[]?">
|
|
<h3>
|
|
<code>.[]?</code>
|
|
|
|
</h3>
|
|
<p>Like <code>.[]</code>, but no errors will be output if . is not an array
|
|
or object. A filter of the form <code>.foo[]?</code> is equivalent to
|
|
<code>.foo | .[]?</code>.</p>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="Comma:,">
|
|
<h3>
|
|
Comma: <code>,</code>
|
|
|
|
</h3>
|
|
<p>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 <code>.foo,
|
|
.bar</code>, produces both the "foo" fields and "bar" fields as
|
|
separate outputs.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example7">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example7" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.foo, .bar'</td></tr>
|
|
<tr><th>Input</th><td>{"foo": 42, "bar": "something else", "baz": true}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>42</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>"something else"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.user, .projects[]'</td></tr>
|
|
<tr><th>Input</th><td>{"user":"stedolan", "projects": ["jq", "wikiflow"]}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"stedolan"</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>"jq"</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>"wikiflow"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[4,2]'</td></tr>
|
|
<tr><th>Input</th><td>["a","b","c","d","e"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"e"</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>"c"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Pipe:|">
|
|
<h3>
|
|
Pipe: <code>|</code>
|
|
|
|
</h3>
|
|
<p>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.</p>
|
|
<p>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 <code>.[] | .foo</code> retrieves the "foo" field of each
|
|
element of the input array.</p>
|
|
<p>Note that <code>.a.b.c</code> is the same as <code>.a | .b | .c</code>.</p>
|
|
<p>Note too that <code>.</code> is the input value at the particular stage
|
|
in a "pipeline", specifically: where the <code>.</code> expression appears.
|
|
Thus <code>.a | . | .b</code> is the same as <code>.a.b</code>, as the <code>.</code> in the
|
|
middle refers to whatever value <code>.a</code> produced.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example8">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example8" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] | .name'</td></tr>
|
|
<tr><th>Input</th><td>[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"JSON"</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>"XML"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Parenthesis">
|
|
<h3>
|
|
Parenthesis
|
|
|
|
</h3>
|
|
<p>Parenthesis work as a grouping operator just as in any typical
|
|
programming language.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example9">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example9" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '(. + 2) * 5'</td></tr>
|
|
<tr><th>Input</th><td>1</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>15</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="TypesandValues">
|
|
<h2>Types and Values</h2>
|
|
<p>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".</p>
|
|
<p>Booleans, null, strings and numbers are written the same way as
|
|
in JSON. Just like everything else in jq, these simple
|
|
values take an input and produce an output - <code>42</code> is a valid jq
|
|
expression that takes an input, ignores it, and returns 42
|
|
instead.</p>
|
|
<p>Numbers in jq are internally represented by their IEEE754 double
|
|
precision approximation. Any arithmetic operation with numbers,
|
|
whether they are literals or results of previous filters, will
|
|
produce a double precision floating point result.</p>
|
|
<p>However, when parsing a literal jq will store the original literal
|
|
string. If no mutation is applied to this value then it will make
|
|
to the output in its original form, even if conversion to double
|
|
would result in a loss.</p>
|
|
|
|
<section id="Arrayconstruction:[]">
|
|
<h3>
|
|
Array construction: <code>[]</code>
|
|
|
|
</h3>
|
|
<p>As in JSON, <code>[]</code> is used to construct arrays, as in
|
|
<code>[1,2,3]</code>. 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 <code>[.foo, .bar, .baz]</code>) or to "collect" all the
|
|
results of a filter into an array (as in <code>[.items[].name]</code>)</p>
|
|
<p>Once you understand the "," operator, you can look at jq's array
|
|
syntax in a different light: the expression <code>[1,2,3]</code> is not using a
|
|
built-in syntax for comma-separated arrays, but is instead applying
|
|
the <code>[]</code> operator (collect results) to the expression 1,2,3 (which
|
|
produces three different results).</p>
|
|
<p>If you have a filter <code>X</code> that produces four results,
|
|
then the expression <code>[X]</code> will produce a single result, an
|
|
array of four elements.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example10">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example10" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[.user, .projects[]]'</td></tr>
|
|
<tr><th>Input</th><td>{"user":"stedolan", "projects": ["jq", "wikiflow"]}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["stedolan", "jq", "wikiflow"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[ .[] | . * 2]'</td></tr>
|
|
<tr><th>Input</th><td>[1, 2, 3]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[2, 4, 6]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="ObjectConstruction:{}">
|
|
<h3>
|
|
Object Construction: <code>{}</code>
|
|
|
|
</h3>
|
|
<p>Like JSON, <code>{}</code> is for constructing objects (aka
|
|
dictionaries or hashes), as in: <code>{"a": 42, "b": 17}</code>.</p>
|
|
<p>If the keys are "identifier-like", then the quotes can be left
|
|
off, as in <code>{a:42, b:17}</code>. Variable references as key
|
|
expressions use the value of the variable as the key. Key
|
|
expressions other than constant literals, identifiers, or
|
|
variable references, need to be parenthesized, e.g.,
|
|
<code>{("a"+"b"):59}</code>.</p>
|
|
<p>The value can be any expression (although you may need to wrap
|
|
it in parentheses if, for example, it contains colons), which
|
|
gets applied to the {} expression's input (remember, all
|
|
filters have an input and an output).</p>
|
|
<pre><code>{foo: .bar}
|
|
</code></pre>
|
|
<p>will produce the JSON object <code>{"foo": 42}</code> if given the JSON
|
|
object <code>{"bar":42, "baz":43}</code> 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</p>
|
|
<pre><code>{user: .user, title: .title}
|
|
</code></pre>
|
|
<p>Because that is so common, there's a shortcut syntax for it:
|
|
<code>{user, title}</code>.</p>
|
|
<p>If one of the expressions produces multiple results,
|
|
multiple dictionaries will be produced. If the input's</p>
|
|
<pre><code>{"user":"stedolan","titles":["JQ Primer", "More JQ"]}
|
|
</code></pre>
|
|
<p>then the expression</p>
|
|
<pre><code>{user, title: .titles[]}
|
|
</code></pre>
|
|
<p>will produce two outputs:</p>
|
|
<pre><code>{"user":"stedolan", "title": "JQ Primer"}
|
|
{"user":"stedolan", "title": "More JQ"}
|
|
</code></pre>
|
|
<p>Putting parentheses around the key means it will be evaluated as an
|
|
expression. With the same input as above,</p>
|
|
<pre><code>{(.user): .titles}
|
|
</code></pre>
|
|
<p>produces</p>
|
|
<pre><code>{"stedolan": ["JQ Primer", "More JQ"]}
|
|
</code></pre>
|
|
<p>Variable references as keys use the value of the variable as
|
|
the key. Without a value then the variable's name becomes the
|
|
key and its value becomes the value,</p>
|
|
<pre><code>"f o o" as $foo | "b a r" as $bar | {$foo, $bar:$foo}
|
|
</code></pre>
|
|
<p>produces</p>
|
|
<pre><code>{"foo":"f o o","b a r":"f o o"}
|
|
</code></pre>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example11">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example11" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '{user, title: .titles[]}'</td></tr>
|
|
<tr><th>Input</th><td>{"user":"stedolan","titles":["JQ Primer", "More JQ"]}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"user":"stedolan", "title": "JQ Primer"}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"user":"stedolan", "title": "More JQ"}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '{(.user): .titles}'</td></tr>
|
|
<tr><th>Input</th><td>{"user":"stedolan","titles":["JQ Primer", "More JQ"]}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"stedolan": ["JQ Primer", "More JQ"]}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="RecursiveDescent:..">
|
|
<h3>
|
|
Recursive Descent: <code>..</code>
|
|
|
|
</h3>
|
|
<p>Recursively descends <code>.</code>, producing every value. This is the
|
|
same as the zero-argument <code>recurse</code> builtin (see below). This
|
|
is intended to resemble the XPath <code>//</code> operator. Note that
|
|
<code>..a</code> does not work; use <code>.. | .a</code> instead. In the example
|
|
below we use <code>.. | .a?</code> to find all the values of object keys
|
|
"a" in any object found "below" <code>.</code>.</p>
|
|
<p>This is particularly useful in conjunction with <code>path(EXP)</code>
|
|
(also see below) and the <code>?</code> operator.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example12">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example12" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.. | .a?'</td></tr>
|
|
<tr><th>Input</th><td>[[{"a":1}]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="Builtinoperatorsandfunctions">
|
|
<h2>Builtin operators and functions</h2>
|
|
<p>Some jq operators (for instance, <code>+</code>) 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.</p>
|
|
<p>Please note that all numbers are converted to IEEE754 double precision
|
|
floating point representation. Arithmetic and logical operators are working
|
|
with these converted doubles. Results of all such operations are also limited
|
|
to the double precision.</p>
|
|
<p>The only exception to this behaviour of number is a snapshot of original number
|
|
literal. When a number which originally was provided as a literal is never
|
|
mutated until the end of the program then it is printed to the output in its
|
|
original literal form. This also includes cases when the original literal
|
|
would be truncated when converted to the IEEE754 double precision floating point
|
|
number.</p>
|
|
|
|
<section id="Addition:+">
|
|
<h3>
|
|
Addition: <code>+</code>
|
|
|
|
</h3>
|
|
<p>The operator <code>+</code> takes two filters, applies them both
|
|
to the same input, and adds the results together. What
|
|
"adding" means depends on the types involved:</p>
|
|
<ul>
|
|
<li>
|
|
<p><strong>Numbers</strong> are added by normal arithmetic.</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>Arrays</strong> are added by being concatenated into a larger array.</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>Strings</strong> are added by being joined into a larger string.</p>
|
|
</li>
|
|
<li>
|
|
<p><strong>Objects</strong> 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 <code>+</code> wins. (For
|
|
recursive merge use the <code>*</code> operator.)</p>
|
|
</li>
|
|
</ul>
|
|
<p><code>null</code> can be added to any value, and returns the other
|
|
value unchanged.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example13">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example13" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.a + 1'</td></tr>
|
|
<tr><th>Input</th><td>{"a": 7}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>8</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.a + .b'</td></tr>
|
|
<tr><th>Input</th><td>{"a": [1,2], "b": [3,4]}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1,2,3,4]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.a + null'</td></tr>
|
|
<tr><th>Input</th><td>{"a": 1}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.a + 1'</td></tr>
|
|
<tr><th>Input</th><td>{}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '{a: 1} + {b: 2} + {c: 3} + {a: 42}'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a": 42, "b": 2, "c": 3}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Subtraction:-">
|
|
<h3>
|
|
Subtraction: <code>-</code>
|
|
|
|
</h3>
|
|
<p>As well as normal arithmetic subtraction on numbers, the <code>-</code>
|
|
operator can be used on arrays to remove all occurrences of
|
|
the second array's elements from the first array.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example14">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example14" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '4 - .a'</td></tr>
|
|
<tr><th>Input</th><td>{"a":3}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '. - ["xml", "yaml"]'</td></tr>
|
|
<tr><th>Input</th><td>["xml", "yaml", "json"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["json"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Multiplication,division,modulo:*,/,%">
|
|
<h3>
|
|
Multiplication, division, modulo: <code>*</code>, <code>/</code>, <code>%</code>
|
|
|
|
</h3>
|
|
<p>These infix operators behave as expected when given two numbers.
|
|
Division by zero raises an error. <code>x % y</code> computes x modulo y.</p>
|
|
<p>Multiplying a string by a number produces the concatenation of
|
|
that string that many times. <code>"x" * 0</code> produces <code>""</code>.</p>
|
|
<p>Dividing a string by another splits the first using the second
|
|
as separators.</p>
|
|
<p>Multiplying two objects will merge them recursively: this works
|
|
like addition but if both objects contain a value for the
|
|
same key, and the values are objects, the two are merged with
|
|
the same strategy.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example15">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example15" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '10 / . * 3'</td></tr>
|
|
<tr><th>Input</th><td>5</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>6</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '. / ", "'</td></tr>
|
|
<tr><th>Input</th><td>"a, b,c,d, e"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["a","b,c,d","e"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '{"k": {"a": 1, "b": 2}} * {"k": {"a": 0,"c": 3}}'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"k": {"a": 0, "b": 2, "c": 3}}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] | (1 / .)?'</td></tr>
|
|
<tr><th>Input</th><td>[1,0,-1]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>-1</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="length">
|
|
<h3>
|
|
<code>length</code>
|
|
|
|
</h3>
|
|
<p>The builtin function <code>length</code> gets the length of various
|
|
different types of value:</p>
|
|
<ul>
|
|
<li>
|
|
<p>The length of a <strong>string</strong> 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).</p>
|
|
</li>
|
|
<li>
|
|
<p>The length of a <strong>number</strong> is its absolute value.</p>
|
|
</li>
|
|
<li>
|
|
<p>The length of an <strong>array</strong> is the number of elements.</p>
|
|
</li>
|
|
<li>
|
|
<p>The length of an <strong>object</strong> is the number of key-value pairs.</p>
|
|
</li>
|
|
<li>
|
|
<p>The length of <strong>null</strong> is zero.</p>
|
|
</li>
|
|
<li>
|
|
<p>It is an error to use <code>length</code> on a <strong>boolean</strong>.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example16">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example16" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] | length'</td></tr>
|
|
<tr><th>Input</th><td>[[1,2], "string", {"a":2}, null, -5]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>2</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>6</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>0</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>5</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="utf8bytelength">
|
|
<h3>
|
|
<code>utf8bytelength</code>
|
|
|
|
</h3>
|
|
<p>The builtin function <code>utf8bytelength</code> outputs the number of
|
|
bytes used to encode a string in UTF-8.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example17">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example17" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'utf8bytelength'</td></tr>
|
|
<tr><th>Input</th><td>"\u03bc"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>2</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="keys,keys_unsorted">
|
|
<h3>
|
|
<code>keys</code>, <code>keys_unsorted</code>
|
|
|
|
</h3>
|
|
<p>The builtin function <code>keys</code>, when given an object, returns
|
|
its keys in an array.</p>
|
|
<p>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.</p>
|
|
<p>When <code>keys</code> is given an array, it returns the valid indices
|
|
for that array: the integers from 0 to length-1.</p>
|
|
<p>The <code>keys_unsorted</code> function is just like <code>keys</code>, but if
|
|
the input is an object then the keys will not be sorted,
|
|
instead the keys will roughly be in insertion order.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example18">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example18" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'keys'</td></tr>
|
|
<tr><th>Input</th><td>{"abc": 1, "abcd": 2, "Foo": 3}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["Foo", "abc", "abcd"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'keys'</td></tr>
|
|
<tr><th>Input</th><td>[42,3,35]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[0,1,2]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="has(key)">
|
|
<h3>
|
|
<code>has(key)</code>
|
|
|
|
</h3>
|
|
<p>The builtin function <code>has</code> returns whether the input object
|
|
has the given key, or the input array has an element at the
|
|
given index.</p>
|
|
<p><code>has($key)</code> has the same effect as checking whether <code>$key</code>
|
|
is a member of the array returned by <code>keys</code>, although <code>has</code>
|
|
will be faster.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example19">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example19" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'map(has("foo"))'</td></tr>
|
|
<tr><th>Input</th><td>[{"foo": 42}, {}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[true, false]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'map(has(2))'</td></tr>
|
|
<tr><th>Input</th><td>[[0,1], ["a","b","c"]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[false, true]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="in">
|
|
<h3>
|
|
<code>in</code>
|
|
|
|
</h3>
|
|
<p>The builtin function <code>in</code> 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 <code>has</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example20">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example20" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] | in({"foo": 42})'</td></tr>
|
|
<tr><th>Input</th><td>["foo", "bar"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'map(in([0,1]))'</td></tr>
|
|
<tr><th>Input</th><td>[2, 0]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[false, true]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="map(f),map_values(f)">
|
|
<h3>
|
|
<code>map(f)</code>, <code>map_values(f)</code>
|
|
|
|
</h3>
|
|
<p>For any filter <code>f</code>, <code>map(f)</code> and <code>map_values(f)</code> apply <code>f</code>
|
|
to each of the values in the input array or object, that is,
|
|
to the values of <code>.[]</code>.</p>
|
|
<p>In the absence of errors, <code>map(f)</code> always outputs an array
|
|
whereas <code>map_values(f)</code> outputs an array if given an array,
|
|
or an object if given an object.</p>
|
|
<p>When the input to <code>map_values(f)</code> is an object, the output
|
|
object has the same keys as the input object except for
|
|
those keys whose values when piped to <code>f</code> produce no values
|
|
at all.</p>
|
|
<p>The key difference between <code>map(f)</code> and <code>map_values(f)</code> is
|
|
that the former simply forms an array from all the values of
|
|
<code>($x|f)</code> for each value, $x, in the input array or object,
|
|
but <code>map_values(f)</code> only uses <code>first($x|f)</code>.</p>
|
|
<p>Specifically, for object inputs, <code>map_value(f)</code> constructs
|
|
the output object by examining in turn the value of
|
|
<code>first(.[$k]|f)</code> for each key, $k, of the input. If this
|
|
expression produces no values, then the corresponding key
|
|
will be dropped; otherwise, the output object will have that
|
|
value at the key, $k.</p>
|
|
<p>Here are some examples to clarify the behavior of <code>map</code> and
|
|
<code>map_values</code> when applied to arrays. These examples assume the
|
|
input is <code>[1]</code> in all cases:</p>
|
|
<pre><code>map(.+1) #=> [2]
|
|
map(., .) #=> [1,1]
|
|
map(empty) #=> []
|
|
|
|
map_values(.+1) #=> [2]
|
|
map_values(., .) #=> [1]
|
|
map_values(empty) #=> []
|
|
</code></pre>
|
|
<p><code>map(f)</code> is equivalent to <code>[.[] | f]</code> and
|
|
<code>map_values(f)</code> is equivalent to <code>.[] |= f</code>.</p>
|
|
<p>In fact, these are their implementations.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example21">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example21" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'map(.+1)'</td></tr>
|
|
<tr><th>Input</th><td>[1,2,3]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[2,3,4]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'map_values(.+1)'</td></tr>
|
|
<tr><th>Input</th><td>{"a": 1, "b": 2, "c": 3}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a": 2, "b": 3, "c": 4}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'map(., .)'</td></tr>
|
|
<tr><th>Input</th><td>[1,2]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1,1,2,2]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'map_values(. // empty)'</td></tr>
|
|
<tr><th>Input</th><td>{"a": null, "b": true, "c": false}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"b":true}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="pick(pathexps)">
|
|
<h3>
|
|
<code>pick(pathexps)</code>
|
|
|
|
</h3>
|
|
<p>Emit the projection of the input object or array defined by the specified
|
|
sequence of path expressions, such that if p is any one of these specifications,
|
|
then <code>(. | p)</code> will evaluate to the same value as <code>(. | pick(pathexps) | p)</code>.
|
|
For arrays, negative indices and .[m:n] specifications should not be used.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example22">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example22" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'pick(.a, .b.c, .x)'</td></tr>
|
|
<tr><th>Input</th><td>{"a": 1, "b": {"c": 2, "d": 3}, "e": 4}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a":1,"b":{"c":2},"x":null}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[1,2,3,4] | pick(.[2], .[0], .[0])'</td></tr>
|
|
<tr><th>Input</th><td>[1,2,3,4]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1,null,3]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="path(path_expression)">
|
|
<h3>
|
|
<code>path(path_expression)</code>
|
|
|
|
</h3>
|
|
<p>Outputs array representations of the given path expression
|
|
in <code>.</code>. The outputs are arrays of strings (object keys)
|
|
and/or numbers (array indices).</p>
|
|
<p>Path expressions are jq expressions like <code>.a</code>, but also <code>.[]</code>.
|
|
There are two types of path expressions: ones that can match
|
|
exactly, and ones that cannot. For example, <code>.a.b.c</code> is an
|
|
exact match path expression, while <code>.a[].b</code> is not.</p>
|
|
<p><code>path(exact_path_expression)</code> will produce the array
|
|
representation of the path expression even if it does not
|
|
exist in <code>.</code>, if <code>.</code> is <code>null</code> or an array or an object.</p>
|
|
<p><code>path(pattern)</code> will produce array representations of the
|
|
paths matching <code>pattern</code> if the paths exist in <code>.</code>.</p>
|
|
<p>Note that the path expressions are not different from normal
|
|
expressions. The expression
|
|
<code>path(..|select(type=="boolean"))</code> outputs all the paths to
|
|
boolean values in <code>.</code>, and only those paths.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example23">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example23" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'path(.a[0].b)'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["a",0,"b"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[path(..)]'</td></tr>
|
|
<tr><th>Input</th><td>{"a":[{"b":1}]}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[[],["a"],["a",0],["a",0,"b"]]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="del(path_expression)">
|
|
<h3>
|
|
<code>del(path_expression)</code>
|
|
|
|
</h3>
|
|
<p>The builtin function <code>del</code> removes a key and its corresponding
|
|
value from an object.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example24">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example24" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'del(.foo)'</td></tr>
|
|
<tr><th>Input</th><td>{"foo": 42, "bar": 9001, "baz": 42}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"bar": 9001, "baz": 42}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'del(.[1, 2])'</td></tr>
|
|
<tr><th>Input</th><td>["foo", "bar", "baz"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["foo"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="getpath(PATHS)">
|
|
<h3>
|
|
<code>getpath(PATHS)</code>
|
|
|
|
</h3>
|
|
<p>The builtin function <code>getpath</code> outputs the values in <code>.</code> found
|
|
at each path in <code>PATHS</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example25">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example25" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'getpath(["a","b"])'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>null</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[getpath(["a","b"], ["a","c"])]'</td></tr>
|
|
<tr><th>Input</th><td>{"a":{"b":0, "c":1}}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[0, 1]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="setpath(PATHS;VALUE)">
|
|
<h3>
|
|
<code>setpath(PATHS; VALUE)</code>
|
|
|
|
</h3>
|
|
<p>The builtin function <code>setpath</code> sets the <code>PATHS</code> in <code>.</code> to <code>VALUE</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example26">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example26" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'setpath(["a","b"]; 1)'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a": {"b": 1}}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'setpath(["a","b"]; 1)'</td></tr>
|
|
<tr><th>Input</th><td>{"a":{"b":0}}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a": {"b": 1}}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'setpath([0,"a"]; 1)'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[{"a":1}]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="delpaths(PATHS)">
|
|
<h3>
|
|
<code>delpaths(PATHS)</code>
|
|
|
|
</h3>
|
|
<p>The builtin function <code>delpaths</code> sets the <code>PATHS</code> in <code>.</code>.
|
|
<code>PATHS</code> must be an array of paths, where each path is an array
|
|
of strings and numbers.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example27">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example27" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'delpaths([["a","b"]])'</td></tr>
|
|
<tr><th>Input</th><td>{"a":{"b":1},"x":{"y":2}}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a":{},"x":{"y":2}}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="to_entries,from_entries,with_entries(f)">
|
|
<h3>
|
|
<code>to_entries</code>, <code>from_entries</code>, <code>with_entries(f)</code>
|
|
|
|
</h3>
|
|
<p>These functions convert between an object and an array of
|
|
key-value pairs. If <code>to_entries</code> is passed an object, then
|
|
for each <code>k: v</code> entry in the input, the output array
|
|
includes <code>{"key": k, "value": v}</code>.</p>
|
|
<p><code>from_entries</code> does the opposite conversion, and <code>with_entries(f)</code>
|
|
is a shorthand for <code>to_entries | map(f) | from_entries</code>, useful for
|
|
doing some operation to all keys and values of an object.
|
|
<code>from_entries</code> accepts <code>"key"</code>, <code>"Key"</code>, <code>"name"</code>, <code>"Name"</code>,
|
|
<code>"value"</code>, and <code>"Value"</code> as keys.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example28">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example28" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'to_entries'</td></tr>
|
|
<tr><th>Input</th><td>{"a": 1, "b": 2}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[{"key":"a", "value":1}, {"key":"b", "value":2}]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'from_entries'</td></tr>
|
|
<tr><th>Input</th><td>[{"key":"a", "value":1}, {"key":"b", "value":2}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a": 1, "b": 2}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'with_entries(.key |= "KEY_" + .)'</td></tr>
|
|
<tr><th>Input</th><td>{"a": 1, "b": 2}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"KEY_a": 1, "KEY_b": 2}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="select(boolean_expression)">
|
|
<h3>
|
|
<code>select(boolean_expression)</code>
|
|
|
|
</h3>
|
|
<p>The function <code>select(f)</code> produces its input unchanged if
|
|
<code>f</code> returns true for that input, and produces no output
|
|
otherwise.</p>
|
|
<p>It's useful for filtering lists: <code>[1,2,3] | map(select(. >= 2))</code>
|
|
will give you <code>[2,3]</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example29">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example29" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'map(select(. >= 2))'</td></tr>
|
|
<tr><th>Input</th><td>[1,5,3,0,7]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[5,3,7]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] | select(.id == "second")'</td></tr>
|
|
<tr><th>Input</th><td>[{"id": "first", "val": 1}, {"id": "second", "val": 2}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"id": "second", "val": 2}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="arrays,objects,iterables,booleans,numbers,normals,finites,strings,nulls,values,scalars">
|
|
<h3>
|
|
<code>arrays</code>, <code>objects</code>, <code>iterables</code>, <code>booleans</code>, <code>numbers</code>, <code>normals</code>, <code>finites</code>, <code>strings</code>, <code>nulls</code>, <code>values</code>, <code>scalars</code>
|
|
|
|
</h3>
|
|
<p>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.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example30">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example30" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[]|numbers'</td></tr>
|
|
<tr><th>Input</th><td>[[],{},1,"foo",null,true,false]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="empty">
|
|
<h3>
|
|
<code>empty</code>
|
|
|
|
</h3>
|
|
<p><code>empty</code> returns no results. None at all. Not even <code>null</code>.</p>
|
|
<p>It's useful on occasion. You'll know if you need it :)</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example31">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example31" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '1, empty, 2'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>2</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[1,2,empty,3]'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1,2,3]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="error,error(message)">
|
|
<h3>
|
|
<code>error</code>, <code>error(message)</code>
|
|
|
|
</h3>
|
|
<p>Produces an error with the input value, or with the message
|
|
given as the argument. Errors can be caught with try/catch;
|
|
see below.</p>
|
|
<p>When the error value is <code>null</code>, it produces nothing and works
|
|
just like <code>empty</code>. So <code>[null | error]</code> and <code>[error(null)]</code> both
|
|
emit <code>[]</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example32">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example32" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'try error catch .'</td></tr>
|
|
<tr><th>Input</th><td>"error message"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"error message"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'try error("invalid value: \(.)") catch .'</td></tr>
|
|
<tr><th>Input</th><td>42</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"invalid value: 42"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="halt">
|
|
<h3>
|
|
<code>halt</code>
|
|
|
|
</h3>
|
|
<p>Stops the jq program with no further outputs. jq will exit
|
|
with exit status <code>0</code>.</p>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="halt_error,halt_error(exit_code)">
|
|
<h3>
|
|
<code>halt_error</code>, <code>halt_error(exit_code)</code>
|
|
|
|
</h3>
|
|
<p>Stops the jq program with no further outputs. The input will
|
|
be printed on <code>stderr</code> as raw output (i.e., strings will not
|
|
have double quotes) with no decoration, not even a newline.</p>
|
|
<p>The given <code>exit_code</code> (defaulting to <code>5</code>) will be jq's exit
|
|
status.</p>
|
|
<p>For example, <code>"Error: something went wrong\n"|halt_error(1)</code>.</p>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="$__loc__">
|
|
<h3>
|
|
<code>$__loc__</code>
|
|
|
|
</h3>
|
|
<p>Produces an object with a "file" key and a "line" key, with
|
|
the filename and line number where <code>$__loc__</code> occurs, as
|
|
values.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example33">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example33" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'try error("\($__loc__)") catch .'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"{\"file\":\"<top-level>\",\"line\":1}"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="paths,paths(node_filter)">
|
|
<h3>
|
|
<code>paths</code>, <code>paths(node_filter)</code>
|
|
|
|
</h3>
|
|
<p><code>paths</code> outputs the paths to all the elements in its input
|
|
(except it does not output the empty list, representing .
|
|
itself).</p>
|
|
<p><code>paths(f)</code> outputs the paths to any values for which <code>f</code> is <code>true</code>.
|
|
That is, <code>paths(type == "number")</code> outputs the paths to all numeric
|
|
values.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example34">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example34" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[paths]'</td></tr>
|
|
<tr><th>Input</th><td>[1,[[],{"a":2}]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[[0],[1],[1,0],[1,1],[1,1,"a"]]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[paths(type == "number")]'</td></tr>
|
|
<tr><th>Input</th><td>[1,[[],{"a":2}]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[[0],[1,1,"a"]]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="add">
|
|
<h3>
|
|
<code>add</code>
|
|
|
|
</h3>
|
|
<p>The filter <code>add</code> 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 <code>+</code> operator (described above).</p>
|
|
<p>If the input is an empty array, <code>add</code> returns <code>null</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example35">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example35" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'add'</td></tr>
|
|
<tr><th>Input</th><td>["a","b","c"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"abc"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'add'</td></tr>
|
|
<tr><th>Input</th><td>[1, 2, 3]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>6</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'add'</td></tr>
|
|
<tr><th>Input</th><td>[]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>null</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="any,any(condition),any(generator;condition)">
|
|
<h3>
|
|
<code>any</code>, <code>any(condition)</code>, <code>any(generator; condition)</code>
|
|
|
|
</h3>
|
|
<p>The filter <code>any</code> takes as input an array of boolean values,
|
|
and produces <code>true</code> as output if any of the elements of
|
|
the array are <code>true</code>.</p>
|
|
<p>If the input is an empty array, <code>any</code> returns <code>false</code>.</p>
|
|
<p>The <code>any(condition)</code> form applies the given condition to the
|
|
elements of the input array.</p>
|
|
<p>The <code>any(generator; condition)</code> form applies the given
|
|
condition to all the outputs of the given generator.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example36">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example36" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'any'</td></tr>
|
|
<tr><th>Input</th><td>[true, false]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'any'</td></tr>
|
|
<tr><th>Input</th><td>[false, false]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'any'</td></tr>
|
|
<tr><th>Input</th><td>[]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="all,all(condition),all(generator;condition)">
|
|
<h3>
|
|
<code>all</code>, <code>all(condition)</code>, <code>all(generator; condition)</code>
|
|
|
|
</h3>
|
|
<p>The filter <code>all</code> takes as input an array of boolean values,
|
|
and produces <code>true</code> as output if all of the elements of
|
|
the array are <code>true</code>.</p>
|
|
<p>The <code>all(condition)</code> form applies the given condition to the
|
|
elements of the input array.</p>
|
|
<p>The <code>all(generator; condition)</code> form applies the given
|
|
condition to all the outputs of the given generator.</p>
|
|
<p>If the input is an empty array, <code>all</code> returns <code>true</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example37">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example37" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'all'</td></tr>
|
|
<tr><th>Input</th><td>[true, false]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'all'</td></tr>
|
|
<tr><th>Input</th><td>[true, true]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'all'</td></tr>
|
|
<tr><th>Input</th><td>[]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="flatten,flatten(depth)">
|
|
<h3>
|
|
<code>flatten</code>, <code>flatten(depth)</code>
|
|
|
|
</h3>
|
|
<p>The filter <code>flatten</code> 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.</p>
|
|
<p><code>flatten(2)</code> is like <code>flatten</code>, but going only up to two
|
|
levels deep.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example38">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example38" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'flatten'</td></tr>
|
|
<tr><th>Input</th><td>[1, [2], [[3]]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1, 2, 3]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'flatten(1)'</td></tr>
|
|
<tr><th>Input</th><td>[1, [2], [[3]]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1, 2, [3]]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'flatten'</td></tr>
|
|
<tr><th>Input</th><td>[[]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'flatten'</td></tr>
|
|
<tr><th>Input</th><td>[{"foo": "bar"}, [{"foo": "baz"}]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[{"foo": "bar"}, {"foo": "baz"}]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="range(upto),range(from;upto),range(from;upto;by)">
|
|
<h3>
|
|
<code>range(upto)</code>, <code>range(from; upto)</code>, <code>range(from; upto; by)</code>
|
|
|
|
</h3>
|
|
<p>The <code>range</code> function produces a range of numbers. <code>range(4; 10)</code>
|
|
produces 6 numbers, from 4 (inclusive) to 10 (exclusive). The numbers
|
|
are produced as separate outputs. Use <code>[range(4; 10)]</code> to get a range as
|
|
an array.</p>
|
|
<p>The one argument form generates numbers from 0 to the given
|
|
number, with an increment of 1.</p>
|
|
<p>The two argument form generates numbers from <code>from</code> to <code>upto</code>
|
|
with an increment of 1.</p>
|
|
<p>The three argument form generates numbers <code>from</code> to <code>upto</code>
|
|
with an increment of <code>by</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example39">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example39" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'range(2; 4)'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>2</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>3</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[range(2; 4)]'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[2,3]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[range(4)]'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[0,1,2,3]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[range(0; 10; 3)]'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[0,3,6,9]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[range(0; 10; -1)]'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[range(0; -5; -1)]'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[0,-1,-2,-3,-4]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="floor">
|
|
<h3>
|
|
<code>floor</code>
|
|
|
|
</h3>
|
|
<p>The <code>floor</code> function returns the floor of its numeric input.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example40">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example40" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'floor'</td></tr>
|
|
<tr><th>Input</th><td>3.14159</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>3</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="sqrt">
|
|
<h3>
|
|
<code>sqrt</code>
|
|
|
|
</h3>
|
|
<p>The <code>sqrt</code> function returns the square root of its numeric input.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example41">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example41" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'sqrt'</td></tr>
|
|
<tr><th>Input</th><td>9</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>3</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="tonumber">
|
|
<h3>
|
|
<code>tonumber</code>
|
|
|
|
</h3>
|
|
<p>The <code>tonumber</code> 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.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example42">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example42" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] | tonumber'</td></tr>
|
|
<tr><th>Input</th><td>[1, "1"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="tostring">
|
|
<h3>
|
|
<code>tostring</code>
|
|
|
|
</h3>
|
|
<p>The <code>tostring</code> function prints its input as a
|
|
string. Strings are left unchanged, and all other values are
|
|
JSON-encoded.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example43">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example43" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] | tostring'</td></tr>
|
|
<tr><th>Input</th><td>[1, "1", [1]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"1"</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>"1"</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>"[1]"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="type">
|
|
<h3>
|
|
<code>type</code>
|
|
|
|
</h3>
|
|
<p>The <code>type</code> function returns the type of its argument as a
|
|
string, which is one of null, boolean, number, string, array
|
|
or object.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example44">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example44" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'map(type)'</td></tr>
|
|
<tr><th>Input</th><td>[0, false, [], {}, null, "hello"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["number", "boolean", "array", "object", "null", "string"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="infinite,nan,isinfinite,isnan,isfinite,isnormal">
|
|
<h3>
|
|
<code>infinite</code>, <code>nan</code>, <code>isinfinite</code>, <code>isnan</code>, <code>isfinite</code>, <code>isnormal</code>
|
|
|
|
</h3>
|
|
<p>Some arithmetic operations can yield infinities and "not a
|
|
number" (NaN) values. The <code>isinfinite</code> builtin returns <code>true</code>
|
|
if its input is infinite. The <code>isnan</code> builtin returns <code>true</code>
|
|
if its input is a NaN. The <code>infinite</code> builtin returns a
|
|
positive infinite value. The <code>nan</code> builtin returns a NaN.
|
|
The <code>isnormal</code> builtin returns true if its input is a normal
|
|
number.</p>
|
|
<p>Note that division by zero raises an error.</p>
|
|
<p>Currently most arithmetic operations operating on infinities,
|
|
NaNs, and sub-normals do not raise errors.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example45">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example45" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] | (infinite * .) < 0'</td></tr>
|
|
<tr><th>Input</th><td>[-1, 1]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'infinite, nan | type'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"number"</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>"number"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="sort,sort_by(path_expression)">
|
|
<h3>
|
|
<code>sort</code>, <code>sort_by(path_expression)</code>
|
|
|
|
</h3>
|
|
<p>The <code>sort</code> functions sorts its input, which must be an
|
|
array. Values are sorted in the following order:</p>
|
|
<ul>
|
|
<li><code>null</code></li>
|
|
<li><code>false</code></li>
|
|
<li><code>true</code></li>
|
|
<li>numbers</li>
|
|
<li>strings, in alphabetical order (by unicode codepoint value)</li>
|
|
<li>arrays, in lexical order</li>
|
|
<li>objects</li>
|
|
</ul>
|
|
<p>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.</p>
|
|
<p><code>sort_by</code> may be used to sort by a particular field of an
|
|
object, or by applying any jq filter. <code>sort_by(f)</code> compares
|
|
two elements by comparing the result of <code>f</code> on each element.
|
|
When <code>f</code> produces multiple values, it firstly compares the
|
|
first values, and the second values if the first values are
|
|
equal, and so on.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example46">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example46" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'sort'</td></tr>
|
|
<tr><th>Input</th><td>[8,3,null,6]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[null,3,6,8]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'sort_by(.foo)'</td></tr>
|
|
<tr><th>Input</th><td>[{"foo":4, "bar":10}, {"foo":3, "bar":10}, {"foo":2, "bar":1}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[{"foo":2, "bar":1}, {"foo":3, "bar":10}, {"foo":4, "bar":10}]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'sort_by(.foo, .bar)'</td></tr>
|
|
<tr><th>Input</th><td>[{"foo":4, "bar":10}, {"foo":3, "bar":20}, {"foo":2, "bar":1}, {"foo":3, "bar":10}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[{"foo":2, "bar":1}, {"foo":3, "bar":10}, {"foo":3, "bar":20}, {"foo":4, "bar":10}]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="group_by(path_expression)">
|
|
<h3>
|
|
<code>group_by(path_expression)</code>
|
|
|
|
</h3>
|
|
<p><code>group_by(.foo)</code> takes as input an array, groups the
|
|
elements having the same <code>.foo</code> field into separate arrays,
|
|
and produces all of these arrays as elements of a larger
|
|
array, sorted by the value of the <code>.foo</code> field.</p>
|
|
<p>Any jq expression, not just a field access, may be used in
|
|
place of <code>.foo</code>. The sorting order is the same as described
|
|
in the <code>sort</code> function above.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example47">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example47" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'group_by(.foo)'</td></tr>
|
|
<tr><th>Input</th><td>[{"foo":1, "bar":10}, {"foo":3, "bar":100}, {"foo":1, "bar":1}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[[{"foo":1, "bar":10}, {"foo":1, "bar":1}], [{"foo":3, "bar":100}]]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="min,max,min_by(path_exp),max_by(path_exp)">
|
|
<h3>
|
|
<code>min</code>, <code>max</code>, <code>min_by(path_exp)</code>, <code>max_by(path_exp)</code>
|
|
|
|
</h3>
|
|
<p>Find the minimum or maximum element of the input array.</p>
|
|
<p>The <code>min_by(path_exp)</code> and <code>max_by(path_exp)</code> functions allow
|
|
you to specify a particular field or property to examine, e.g.
|
|
<code>min_by(.foo)</code> finds the object with the smallest <code>foo</code> field.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example48">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example48" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'min'</td></tr>
|
|
<tr><th>Input</th><td>[5,4,2,7]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>2</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'max_by(.foo)'</td></tr>
|
|
<tr><th>Input</th><td>[{"foo":1, "bar":14}, {"foo":2, "bar":3}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"foo":2, "bar":3}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="unique,unique_by(path_exp)">
|
|
<h3>
|
|
<code>unique</code>, <code>unique_by(path_exp)</code>
|
|
|
|
</h3>
|
|
<p>The <code>unique</code> function takes as input an array and produces
|
|
an array of the same elements, in sorted order, with
|
|
duplicates removed.</p>
|
|
<p>The <code>unique_by(path_exp)</code> 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 <code>group</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example49">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example49" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'unique'</td></tr>
|
|
<tr><th>Input</th><td>[1,2,5,3,5,3,1,3]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1,2,3,5]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'unique_by(.foo)'</td></tr>
|
|
<tr><th>Input</th><td>[{"foo": 1, "bar": 2}, {"foo": 1, "bar": 3}, {"foo": 4, "bar": 5}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[{"foo": 1, "bar": 2}, {"foo": 4, "bar": 5}]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'unique_by(length)'</td></tr>
|
|
<tr><th>Input</th><td>["chunky", "bacon", "kitten", "cicada", "asparagus"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["bacon", "chunky", "asparagus"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="reverse">
|
|
<h3>
|
|
<code>reverse</code>
|
|
|
|
</h3>
|
|
<p>This function reverses an array.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example50">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example50" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'reverse'</td></tr>
|
|
<tr><th>Input</th><td>[1,2,3,4]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[4,3,2,1]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="contains(element)">
|
|
<h3>
|
|
<code>contains(element)</code>
|
|
|
|
</h3>
|
|
<p>The filter <code>contains(b)</code> 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.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example51">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example51" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'contains("bar")'</td></tr>
|
|
<tr><th>Input</th><td>"foobar"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'contains(["baz", "bar"])'</td></tr>
|
|
<tr><th>Input</th><td>["foobar", "foobaz", "blarp"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'contains(["bazzzzz", "bar"])'</td></tr>
|
|
<tr><th>Input</th><td>["foobar", "foobaz", "blarp"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'contains({foo: 12, bar: [{barp: 12}]})'</td></tr>
|
|
<tr><th>Input</th><td>{"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'contains({foo: 12, bar: [{barp: 15}]})'</td></tr>
|
|
<tr><th>Input</th><td>{"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="indices(s)">
|
|
<h3>
|
|
<code>indices(s)</code>
|
|
|
|
</h3>
|
|
<p>Outputs an array containing the indices in <code>.</code> where <code>s</code>
|
|
occurs. The input may be an array, in which case if <code>s</code> is an
|
|
array then the indices output will be those where all elements
|
|
in <code>.</code> match those of <code>s</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example52">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example52" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'indices(", ")'</td></tr>
|
|
<tr><th>Input</th><td>"a,b, cd, efg, hijk"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[3,7,12]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'indices(1)'</td></tr>
|
|
<tr><th>Input</th><td>[0,1,2,1,3,1,4]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1,3,5]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'indices([1,2])'</td></tr>
|
|
<tr><th>Input</th><td>[0,1,2,3,1,4,2,5,1,2,6,7]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1,8]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="index(s),rindex(s)">
|
|
<h3>
|
|
<code>index(s)</code>, <code>rindex(s)</code>
|
|
|
|
</h3>
|
|
<p>Outputs the index of the first (<code>index</code>) or last (<code>rindex</code>)
|
|
occurrence of <code>s</code> in the input.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example53">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example53" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'index(", ")'</td></tr>
|
|
<tr><th>Input</th><td>"a,b, cd, efg, hijk"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>3</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'index(1)'</td></tr>
|
|
<tr><th>Input</th><td>[0,1,2,1,3,1,4]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'index([1,2])'</td></tr>
|
|
<tr><th>Input</th><td>[0,1,2,3,1,4,2,5,1,2,6,7]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'rindex(", ")'</td></tr>
|
|
<tr><th>Input</th><td>"a,b, cd, efg, hijk"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>12</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'rindex(1)'</td></tr>
|
|
<tr><th>Input</th><td>[0,1,2,1,3,1,4]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>5</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'rindex([1,2])'</td></tr>
|
|
<tr><th>Input</th><td>[0,1,2,3,1,4,2,5,1,2,6,7]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>8</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="inside">
|
|
<h3>
|
|
<code>inside</code>
|
|
|
|
</h3>
|
|
<p>The filter <code>inside(b)</code> will produce true if the input is
|
|
completely contained within b. It is, essentially, an
|
|
inversed version of <code>contains</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example54">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example54" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'inside("foobar")'</td></tr>
|
|
<tr><th>Input</th><td>"bar"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'inside(["foobar", "foobaz", "blarp"])'</td></tr>
|
|
<tr><th>Input</th><td>["baz", "bar"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'inside(["foobar", "foobaz", "blarp"])'</td></tr>
|
|
<tr><th>Input</th><td>["bazzzzz", "bar"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'inside({"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]})'</td></tr>
|
|
<tr><th>Input</th><td>{"foo": 12, "bar": [{"barp": 12}]}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'inside({"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]})'</td></tr>
|
|
<tr><th>Input</th><td>{"foo": 12, "bar": [{"barp": 15}]}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="startswith(str)">
|
|
<h3>
|
|
<code>startswith(str)</code>
|
|
|
|
</h3>
|
|
<p>Outputs <code>true</code> if . starts with the given string argument.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example55">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example55" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[.[]|startswith("foo")]'</td></tr>
|
|
<tr><th>Input</th><td>["fo", "foo", "barfoo", "foobar", "barfoob"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[false, true, false, true, false]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="endswith(str)">
|
|
<h3>
|
|
<code>endswith(str)</code>
|
|
|
|
</h3>
|
|
<p>Outputs <code>true</code> if . ends with the given string argument.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example56">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example56" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[.[]|endswith("foo")]'</td></tr>
|
|
<tr><th>Input</th><td>["foobar", "barfoo"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[false, true]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="combinations,combinations(n)">
|
|
<h3>
|
|
<code>combinations</code>, <code>combinations(n)</code>
|
|
|
|
</h3>
|
|
<p>Outputs all combinations of the elements of the arrays in the
|
|
input array. If given an argument <code>n</code>, it outputs all combinations
|
|
of <code>n</code> repetitions of the input array.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example57">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example57" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'combinations'</td></tr>
|
|
<tr><th>Input</th><td>[[1,2], [3, 4]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1, 3]</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>[1, 4]</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>[2, 3]</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>[2, 4]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'combinations(2)'</td></tr>
|
|
<tr><th>Input</th><td>[0, 1]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[0, 0]</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>[0, 1]</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>[1, 0]</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>[1, 1]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="ltrimstr(str)">
|
|
<h3>
|
|
<code>ltrimstr(str)</code>
|
|
|
|
</h3>
|
|
<p>Outputs its input with the given prefix string removed, if it
|
|
starts with it.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example58">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example58" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[.[]|ltrimstr("foo")]'</td></tr>
|
|
<tr><th>Input</th><td>["fo", "foo", "barfoo", "foobar", "afoo"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["fo","","barfoo","bar","afoo"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="rtrimstr(str)">
|
|
<h3>
|
|
<code>rtrimstr(str)</code>
|
|
|
|
</h3>
|
|
<p>Outputs its input with the given suffix string removed, if it
|
|
ends with it.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example59">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example59" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[.[]|rtrimstr("foo")]'</td></tr>
|
|
<tr><th>Input</th><td>["fo", "foo", "barfoo", "foobar", "foob"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["fo","","bar","foobar","foob"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="explode">
|
|
<h3>
|
|
<code>explode</code>
|
|
|
|
</h3>
|
|
<p>Converts an input string into an array of the string's
|
|
codepoint numbers.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example60">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example60" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'explode'</td></tr>
|
|
<tr><th>Input</th><td>"foobar"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[102,111,111,98,97,114]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="implode">
|
|
<h3>
|
|
<code>implode</code>
|
|
|
|
</h3>
|
|
<p>The inverse of explode.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example61">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example61" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'implode'</td></tr>
|
|
<tr><th>Input</th><td>[65, 66, 67]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"ABC"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="split(str)">
|
|
<h3>
|
|
<code>split(str)</code>
|
|
|
|
</h3>
|
|
<p>Splits an input string on the separator argument.</p>
|
|
<p><code>split</code> can also split on regex matches when called with
|
|
two arguments (see the regular expressions section below).</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example62">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example62" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'split(", ")'</td></tr>
|
|
<tr><th>Input</th><td>"a, b,c,d, e, "</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["a","b,c,d","e",""]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="join(str)">
|
|
<h3>
|
|
<code>join(str)</code>
|
|
|
|
</h3>
|
|
<p>Joins the array of elements given as input, using the
|
|
argument as separator. It is the inverse of <code>split</code>: that is,
|
|
running <code>split("foo") | join("foo")</code> over any input string
|
|
returns said input string.</p>
|
|
<p>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.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example63">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example63" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'join(", ")'</td></tr>
|
|
<tr><th>Input</th><td>["a","b,c,d","e"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"a, b,c,d, e"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'join(" ")'</td></tr>
|
|
<tr><th>Input</th><td>["a",1,2.3,true,null,false]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"a 1 2.3 true false"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="ascii_downcase,ascii_upcase">
|
|
<h3>
|
|
<code>ascii_downcase</code>, <code>ascii_upcase</code>
|
|
|
|
</h3>
|
|
<p>Emit a copy of the input string with its alphabetic characters (a-z and A-Z)
|
|
converted to the specified case.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example64">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example64" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'ascii_upcase'</td></tr>
|
|
<tr><th>Input</th><td>"useful but not for é"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"USEFUL BUT NOT FOR é"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="while(cond;update)">
|
|
<h3>
|
|
<code>while(cond; update)</code>
|
|
|
|
</h3>
|
|
<p>The <code>while(cond; update)</code> function allows you to repeatedly
|
|
apply an update to <code>.</code> until <code>cond</code> is false.</p>
|
|
<p>Note that <code>while(cond; update)</code> is internally defined as a
|
|
recursive jq function. Recursive calls within <code>while</code> will
|
|
not consume additional memory if <code>update</code> produces at most one
|
|
output for each input. See advanced topics below.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example65">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example65" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[while(.<100; .*2)]'</td></tr>
|
|
<tr><th>Input</th><td>1</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1,2,4,8,16,32,64]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="repeat(exp)">
|
|
<h3>
|
|
<code>repeat(exp)</code>
|
|
|
|
</h3>
|
|
<p>The <code>repeat(exp)</code> function allows you to repeatedly
|
|
apply expression <code>exp</code> to <code>.</code> until an error is raised.</p>
|
|
<p>Note that <code>repeat(exp)</code> is internally defined as a
|
|
recursive jq function. Recursive calls within <code>repeat</code> will
|
|
not consume additional memory if <code>exp</code> produces at most one
|
|
output for each input. See advanced topics below.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example66">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example66" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[repeat(.*2, error)?]'</td></tr>
|
|
<tr><th>Input</th><td>1</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[2]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="until(cond;next)">
|
|
<h3>
|
|
<code>until(cond; next)</code>
|
|
|
|
</h3>
|
|
<p>The <code>until(cond; next)</code> function allows you to repeatedly
|
|
apply the expression <code>next</code>, initially to <code>.</code> then to its own
|
|
output, until <code>cond</code> is true. For example, this can be used
|
|
to implement a factorial function (see below).</p>
|
|
<p>Note that <code>until(cond; next)</code> is internally defined as a
|
|
recursive jq function. Recursive calls within <code>until()</code> will
|
|
not consume additional memory if <code>next</code> produces at most one
|
|
output for each input. See advanced topics below.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example67">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example67" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[.,1]|until(.[0] < 1; [.[0] - 1, .[1] * .[0]])|.[1]'</td></tr>
|
|
<tr><th>Input</th><td>4</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>24</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="recurse(f),recurse,recurse(f;condition)">
|
|
<h3>
|
|
<code>recurse(f)</code>, <code>recurse</code>, <code>recurse(f; condition)</code>
|
|
|
|
</h3>
|
|
<p>The <code>recurse(f)</code> function allows you to search through a
|
|
recursive structure, and extract interesting data from all
|
|
levels. Suppose your input represents a filesystem:</p>
|
|
<pre><code>{"name": "/", "children": [
|
|
{"name": "/bin", "children": [
|
|
{"name": "/bin/ls", "children": []},
|
|
{"name": "/bin/sh", "children": []}]},
|
|
{"name": "/home", "children": [
|
|
{"name": "/home/stephen", "children": [
|
|
{"name": "/home/stephen/jq", "children": []}]}]}]}
|
|
</code></pre>
|
|
<p>Now suppose you want to extract all of the filenames
|
|
present. You need to retrieve <code>.name</code>, <code>.children[].name</code>,
|
|
<code>.children[].children[].name</code>, and so on. You can do this
|
|
with:</p>
|
|
<pre><code>recurse(.children[]) | .name
|
|
</code></pre>
|
|
<p>When called without an argument, <code>recurse</code> is equivalent to
|
|
<code>recurse(.[]?)</code>.</p>
|
|
<p><code>recurse(f)</code> is identical to <code>recurse(f; true)</code> and can be
|
|
used without concerns about recursion depth.</p>
|
|
<p><code>recurse(f; condition)</code> 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 <code>recurse(.+1; true)</code>.</p>
|
|
<p>The recursive calls in <code>recurse</code> will not consume additional
|
|
memory whenever <code>f</code> produces at most a single output for each
|
|
input.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example68">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example68" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'recurse(.foo[])'</td></tr>
|
|
<tr><th>Input</th><td>{"foo":[{"foo": []}, {"foo":[{"foo":[]}]}]}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"foo":[{"foo":[]},{"foo":[{"foo":[]}]}]}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"foo":[]}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"foo":[{"foo":[]}]}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"foo":[]}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'recurse'</td></tr>
|
|
<tr><th>Input</th><td>{"a":0,"b":[1]}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a":0,"b":[1]}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>0</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>[1]</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'recurse(. * .; . < 20)'</td></tr>
|
|
<tr><th>Input</th><td>2</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>2</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>4</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>16</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="walk(f)">
|
|
<h3>
|
|
<code>walk(f)</code>
|
|
|
|
</h3>
|
|
<p>The <code>walk(f)</code> 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.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example69">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example69" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'walk(if type == "array" then sort else . end)'</td></tr>
|
|
<tr><th>Input</th><td>[[4, 1, 7], [8, 5, 2], [3, 6, 9]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[[1,4,7],[2,5,8],[3,6,9]]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'walk( if type == "object" then with_entries( .key |= sub( "^_+"; "") ) else . end )'</td></tr>
|
|
<tr><th>Input</th><td>[ { "_a": { "__b": 2 } } ]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[{"a":{"b":2}}]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="$ENV,env">
|
|
<h3>
|
|
<code>$ENV</code>, <code>env</code>
|
|
|
|
</h3>
|
|
<p><code>$ENV</code> is an object representing the environment variables as
|
|
set when the jq program started.</p>
|
|
<p><code>env</code> outputs an object representing jq's current environment.</p>
|
|
<p>At the moment there is no builtin for setting environment
|
|
variables.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example70">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example70" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '$ENV.PAGER'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"less"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'env.PAGER'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"less"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="transpose">
|
|
<h3>
|
|
<code>transpose</code>
|
|
|
|
</h3>
|
|
<p>Transpose a possibly jagged matrix (an array of arrays).
|
|
Rows are padded with nulls so the result is always rectangular.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example71">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example71" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'transpose'</td></tr>
|
|
<tr><th>Input</th><td>[[1], [2,3]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[[1,2],[null,3]]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="bsearch(x)">
|
|
<h3>
|
|
<code>bsearch(x)</code>
|
|
|
|
</h3>
|
|
<p><code>bsearch(x)</code> conducts a binary search for x in the input
|
|
array. If the input is sorted and contains x, then
|
|
<code>bsearch(x)</code> 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,
|
|
<code>bsearch(x)</code> will return an integer that is probably of no
|
|
interest.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example72">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example72" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'bsearch(0)'</td></tr>
|
|
<tr><th>Input</th><td>[0,1]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>0</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'bsearch(0)'</td></tr>
|
|
<tr><th>Input</th><td>[1,2,3]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>-1</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'bsearch(4) as $ix | if $ix < 0 then .[-(1+$ix)] = 4 else . end'</td></tr>
|
|
<tr><th>Input</th><td>[1,2,3]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1,2,3,4]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Stringinterpolation:\(exp)">
|
|
<h3>
|
|
String interpolation: <code>\(exp)</code>
|
|
|
|
</h3>
|
|
<p>Inside a string, you can put an expression inside parens
|
|
after a backslash. Whatever the expression returns will be
|
|
interpolated into the string.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example73">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example73" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '"The input was \(.), which is one less than \(.+1)"'</td></tr>
|
|
<tr><th>Input</th><td>42</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"The input was 42, which is one less than 43"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Convertto/fromJSON">
|
|
<h3>
|
|
Convert to/from JSON
|
|
|
|
</h3>
|
|
<p>The <code>tojson</code> and <code>fromjson</code> builtins dump values as JSON texts
|
|
or parse JSON texts into values, respectively. The <code>tojson</code>
|
|
builtin differs from <code>tostring</code> in that <code>tostring</code> returns strings
|
|
unmodified, while <code>tojson</code> encodes strings as JSON strings.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example74">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example74" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[.[]|tostring]'</td></tr>
|
|
<tr><th>Input</th><td>[1, "foo", ["foo"]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["1","foo","[\"foo\"]"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[.[]|tojson]'</td></tr>
|
|
<tr><th>Input</th><td>[1, "foo", ["foo"]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["1","\"foo\"","[\"foo\"]"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[.[]|tojson|fromjson]'</td></tr>
|
|
<tr><th>Input</th><td>[1, "foo", ["foo"]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1,"foo",["foo"]]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Formatstringsandescaping">
|
|
<h3>
|
|
Format strings and escaping
|
|
|
|
</h3>
|
|
<p>The <code>@foo</code> 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. <code>@foo</code> can be used as a
|
|
filter on its own, the possible escapings are:</p>
|
|
<ul>
|
|
<li><code>@text</code>:</li>
|
|
</ul>
|
|
<p>Calls <code>tostring</code>, see that function for details.</p>
|
|
<ul>
|
|
<li><code>@json</code>:</li>
|
|
</ul>
|
|
<p>Serializes the input as JSON.</p>
|
|
<ul>
|
|
<li><code>@html</code>:</li>
|
|
</ul>
|
|
<p>Applies HTML/XML escaping, by mapping the characters
|
|
<code><>&'"</code> to their entity equivalents <code>&lt;</code>, <code>&gt;</code>,
|
|
<code>&amp;</code>, <code>&apos;</code>, <code>&quot;</code>.</p>
|
|
<ul>
|
|
<li><code>@uri</code>:</li>
|
|
</ul>
|
|
<p>Applies percent-encoding, by mapping all reserved URI
|
|
characters to a <code>%XX</code> sequence.</p>
|
|
<ul>
|
|
<li><code>@csv</code>:</li>
|
|
</ul>
|
|
<p>The input must be an array, and it is rendered as CSV
|
|
with double quotes for strings, and quotes escaped by
|
|
repetition.</p>
|
|
<ul>
|
|
<li><code>@tsv</code>:</li>
|
|
</ul>
|
|
<p>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 <code>0x09</code>). Input characters line-feed (ascii <code>0x0a</code>),
|
|
carriage-return (ascii <code>0x0d</code>), tab (ascii <code>0x09</code>) and
|
|
backslash (ascii <code>0x5c</code>) will be output as escape sequences
|
|
<code>\n</code>, <code>\r</code>, <code>\t</code>, <code>\\</code> respectively.</p>
|
|
<ul>
|
|
<li><code>@sh</code>:</li>
|
|
</ul>
|
|
<p>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.</p>
|
|
<ul>
|
|
<li><code>@base64</code>:</li>
|
|
</ul>
|
|
<p>The input is converted to base64 as specified by RFC 4648.</p>
|
|
<ul>
|
|
<li><code>@base64d</code>:</li>
|
|
</ul>
|
|
<p>The inverse of <code>@base64</code>, input is decoded as specified by RFC 4648.
|
|
Note\: If the decoded string is not UTF-8, the results are undefined.</p>
|
|
<p>This syntax can be combined with string interpolation in a
|
|
useful way. You can follow a <code>@foo</code> token with a string
|
|
literal. The contents of the string literal will <em>not</em> be
|
|
escaped. However, all interpolations made inside that string
|
|
literal will be escaped. For instance,</p>
|
|
<pre><code>@uri "https://www.google.com/search?q=\(.search)"
|
|
</code></pre>
|
|
<p>will produce the following output for the input
|
|
<code>{"search":"what is jq?"}</code>:</p>
|
|
<pre><code>"https://www.google.com/search?q=what%20is%20jq%3F"
|
|
</code></pre>
|
|
<p>Note that the slashes, question mark, etc. in the URL are
|
|
not escaped, as they were part of the string literal.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example75">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example75" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '@html'</td></tr>
|
|
<tr><th>Input</th><td>"This works if x < y"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"This works if x &lt; y"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '@sh "echo \(.)"'</td></tr>
|
|
<tr><th>Input</th><td>"O'Hara's Ale"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"echo 'O'\\''Hara'\\''s Ale'"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '@base64'</td></tr>
|
|
<tr><th>Input</th><td>"This is a message"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"VGhpcyBpcyBhIG1lc3NhZ2U="</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '@base64d'</td></tr>
|
|
<tr><th>Input</th><td>"VGhpcyBpcyBhIG1lc3NhZ2U="</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"This is a message"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Dates">
|
|
<h3>
|
|
Dates
|
|
|
|
</h3>
|
|
<p>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.</p>
|
|
<p>The <code>fromdateiso8601</code> builtin parses datetimes in the ISO 8601
|
|
format to a number of seconds since the Unix epoch
|
|
(1970-01-01T00:00:00Z). The <code>todateiso8601</code> builtin does the
|
|
inverse.</p>
|
|
<p>The <code>fromdate</code> builtin parses datetime strings. Currently
|
|
<code>fromdate</code> only supports ISO 8601 datetime strings, but in the
|
|
future it will attempt to parse datetime strings in more
|
|
formats.</p>
|
|
<p>The <code>todate</code> builtin is an alias for <code>todateiso8601</code>.</p>
|
|
<p>The <code>now</code> builtin outputs the current time, in seconds since
|
|
the Unix epoch.</p>
|
|
<p>Low-level jq interfaces to the C-library time functions are
|
|
also provided: <code>strptime</code>, <code>strftime</code>, <code>strflocaltime</code>,
|
|
<code>mktime</code>, <code>gmtime</code>, and <code>localtime</code>. Refer to your host
|
|
operating system's documentation for the format strings used
|
|
by <code>strptime</code> and <code>strftime</code>. Note: these are not necessarily
|
|
stable interfaces in jq, particularly as to their localization
|
|
functionality.</p>
|
|
<p>The <code>gmtime</code> builtin consumes a number of seconds since the
|
|
Unix epoch and outputs a "broken down time" representation of
|
|
Greenwich Mean 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.</p>
|
|
<p>The <code>localtime</code> builtin works like the <code>gmtime</code> builtin, but
|
|
using the local timezone setting.</p>
|
|
<p>The <code>mktime</code> builtin consumes "broken down time"
|
|
representations of time output by <code>gmtime</code> and <code>strptime</code>.</p>
|
|
<p>The <code>strptime(fmt)</code> builtin parses input strings matching the
|
|
<code>fmt</code> argument. The output is in the "broken down time"
|
|
representation consumed by <code>gmtime</code> and output by <code>mktime</code>.</p>
|
|
<p>The <code>strftime(fmt)</code> builtin formats a time (GMT) with the
|
|
given format. The <code>strflocaltime</code> does the same, but using
|
|
the local timezone setting.</p>
|
|
<p>The format strings for <code>strptime</code> and <code>strftime</code> are described
|
|
in typical C library documentation. The format string for ISO
|
|
8601 datetime is <code>"%Y-%m-%dT%H:%M:%SZ"</code>.</p>
|
|
<p>jq may not support some or all of this date functionality on
|
|
some systems. In particular, the <code>%u</code> and <code>%j</code> specifiers for
|
|
<code>strptime(fmt)</code> are not supported on macOS.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example76">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example76" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'fromdate'</td></tr>
|
|
<tr><th>Input</th><td>"2015-03-05T23:51:47Z"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1425599507</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'strptime("%Y-%m-%dT%H:%M:%SZ")'</td></tr>
|
|
<tr><th>Input</th><td>"2015-03-05T23:51:47Z"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[2015,2,5,23,51,47,4,63]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'strptime("%Y-%m-%dT%H:%M:%SZ")|mktime'</td></tr>
|
|
<tr><th>Input</th><td>"2015-03-05T23:51:47Z"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1425599507</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="SQL-StyleOperators">
|
|
<h3>
|
|
SQL-Style Operators
|
|
|
|
</h3>
|
|
<p>jq provides a few SQL-style operators.</p>
|
|
<ul>
|
|
<li>INDEX(stream; index_expression):</li>
|
|
</ul>
|
|
<p>This builtin produces an object whose keys are computed by
|
|
the given index expression applied to each value from the
|
|
given stream.</p>
|
|
<ul>
|
|
<li>JOIN($idx; stream; idx_expr; join_expr):</li>
|
|
</ul>
|
|
<p>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.</p>
|
|
<ul>
|
|
<li>JOIN($idx; stream; idx_expr):</li>
|
|
</ul>
|
|
<p>Same as <code>JOIN($idx; stream; idx_expr; .)</code>.</p>
|
|
<ul>
|
|
<li>JOIN($idx; idx_expr):</li>
|
|
</ul>
|
|
<p>This builtin joins the input <code>.</code> to the given index, applying
|
|
the given index expression to <code>.</code> to compute the index key.
|
|
The join operation is as described above.</p>
|
|
<ul>
|
|
<li>IN(s):</li>
|
|
</ul>
|
|
<p>This builtin outputs <code>true</code> if <code>.</code> appears in the given
|
|
stream, otherwise it outputs <code>false</code>.</p>
|
|
<ul>
|
|
<li>IN(source; s):</li>
|
|
</ul>
|
|
<p>This builtin outputs <code>true</code> if any value in the source stream
|
|
appears in the second stream, otherwise it outputs <code>false</code>.</p>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="builtins">
|
|
<h3>
|
|
<code>builtins</code>
|
|
|
|
</h3>
|
|
<p>Returns a list of all builtin functions in the format <code>name/arity</code>.
|
|
Since functions with the same name but different arities are considered
|
|
separate functions, <code>all/0</code>, <code>all/1</code>, and <code>all/2</code> would all be present
|
|
in the list.</p>
|
|
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="ConditionalsandComparisons">
|
|
<h2>Conditionals and Comparisons</h2>
|
|
|
|
|
|
<section id="==,!=">
|
|
<h3>
|
|
<code>==</code>, <code>!=</code>
|
|
|
|
</h3>
|
|
<p>The expression 'a == b' will produce 'true' if the results of evaluating
|
|
a and b are equal (that is, if they represent equivalent JSON values) and
|
|
'false' otherwise. In particular, strings are never considered equal
|
|
to numbers. In checking for the equality of JSON objects, the ordering of keys
|
|
is irrelevant. If you're coming from JavaScript, please note that jq's <code>==</code> is like
|
|
JavaScript's <code>===</code>, the "strict equality" operator.</p>
|
|
<p>!= is "not equal", and 'a != b' returns the opposite value of 'a == b'</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example77">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example77" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '. == false'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '. == {"b": {"d": (4 + 1e-20), "c": 3}, "a":1}'</td></tr>
|
|
<tr><th>Input</th><td>{"a":1, "b": {"c": 3, "d": 4}}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] == 1'</td></tr>
|
|
<tr><th>Input</th><td>[1, 1.0, "1", "banana"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="if-then-else-end">
|
|
<h3>
|
|
if-then-else-end
|
|
|
|
</h3>
|
|
<p><code>if A then B else C end</code> will act the same as <code>B</code> if <code>A</code>
|
|
produces a value other than false or null, but act the same
|
|
as <code>C</code> otherwise.</p>
|
|
<p><code>if A then B end</code> is the same as <code>if A then B else . end</code>.
|
|
That is, the <code>else</code> branch is optional, and if absent is the
|
|
same as <code>.</code>. This also applies to <code>elif</code> with absent ending <code>else</code> branch.</p>
|
|
<p>Checking for false or null is a simpler notion of
|
|
"truthiness" than is found in JavaScript or Python, but it
|
|
means that you'll sometimes have to be more explicit about
|
|
the condition you want. You can't test whether, e.g. a
|
|
string is empty using <code>if .name then A else B end</code>; you'll
|
|
need something like <code>if .name == "" then A else B end</code> instead.</p>
|
|
<p>If the condition <code>A</code> produces multiple results, then <code>B</code> is evaluated
|
|
once for each result that is not false or null, and <code>C</code> is evaluated
|
|
once for each false or null.</p>
|
|
<p>More cases can be added to an if using <code>elif A then B</code> syntax.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example78">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example78" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'if . == 0 then
|
|
"zero"
|
|
elif . == 1 then
|
|
"one"
|
|
else
|
|
"many"
|
|
end'</td></tr>
|
|
<tr><th>Input</th><td>2</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"many"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id=">,>=,<=,<">
|
|
<h3>
|
|
<code>></code>, <code>>=</code>, <code><=</code>, <code><</code>
|
|
|
|
</h3>
|
|
<p>The comparison operators <code>></code>, <code>>=</code>, <code><=</code>, <code><</code> 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).</p>
|
|
<p>The ordering is the same as that described for <code>sort</code>, above.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example79">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example79" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '. < 5'</td></tr>
|
|
<tr><th>Input</th><td>2</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="and,or,not">
|
|
<h3>
|
|
<code>and</code>, <code>or</code>, <code>not</code>
|
|
|
|
</h3>
|
|
<p>jq supports the normal Boolean operators <code>and</code>, <code>or</code>, <code>not</code>.
|
|
They have the same standard of truth as if expressions -
|
|
<code>false</code> and <code>null</code> are considered "false values", and
|
|
anything else is a "true value".</p>
|
|
<p>If an operand of one of these operators produces multiple
|
|
results, the operator itself will produce a result for each input.</p>
|
|
<p><code>not</code> 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 <code>.foo and .bar |
|
|
not</code>.</p>
|
|
<p>These three only produce the values <code>true</code> and <code>false</code>, 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 <code>//</code> operator below.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example80">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example80" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '42 and "a string"'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '(true, false) or false'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '(true, true) and (true, false)'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[true, false | not]'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[false, true]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Alternativeoperator://">
|
|
<h3>
|
|
Alternative operator: <code>//</code>
|
|
|
|
</h3>
|
|
<p>A filter of the form <code>a // b</code> produces the same
|
|
results as <code>a</code>, if <code>a</code> produces results other than <code>false</code>
|
|
and <code>null</code>. Otherwise, <code>a // b</code> produces the same results as <code>b</code>.</p>
|
|
<p>This is useful for providing defaults: <code>.foo // 1</code> will
|
|
evaluate to <code>1</code> if there's no <code>.foo</code> element in the
|
|
input. It's similar to how <code>or</code> is sometimes used in Python
|
|
(jq's <code>or</code> operator is reserved for strictly Boolean
|
|
operations).</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example81">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example81" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.foo // 42'</td></tr>
|
|
<tr><th>Input</th><td>{"foo": 19}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>19</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.foo // 42'</td></tr>
|
|
<tr><th>Input</th><td>{}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>42</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="try-catch">
|
|
<h3>
|
|
try-catch
|
|
|
|
</h3>
|
|
<p>Errors can be caught by using <code>try EXP catch EXP</code>. 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.</p>
|
|
<p>The <code>try EXP</code> form uses <code>empty</code> as the exception handler.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example82">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example82" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'try .a catch ". is not an object"'</td></tr>
|
|
<tr><th>Input</th><td>true</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>". is not an object"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[.[]|try .a]'</td></tr>
|
|
<tr><th>Input</th><td>[{}, true, {"a":1}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[null, 1]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'try error("some exception") catch .'</td></tr>
|
|
<tr><th>Input</th><td>true</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"some exception"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Breakingoutofcontrolstructures">
|
|
<h3>
|
|
Breaking out of control structures
|
|
|
|
</h3>
|
|
<p>A convenient use of try/catch is to break out of control
|
|
structures like <code>reduce</code>, <code>foreach</code>, <code>while</code>, and so on.</p>
|
|
<p>For example:</p>
|
|
<pre><code># Repeat an expression until it raises "break" as an
|
|
# error, then stop repeating without re-raising the error.
|
|
# But if the error caught is not "break" then re-raise it.
|
|
try repeat(exp) catch if .=="break" then empty else error
|
|
</code></pre>
|
|
<p>jq has a syntax for named lexical labels to "break" or "go (back) to":</p>
|
|
<pre><code>label $out | ... break $out ...
|
|
</code></pre>
|
|
<p>The <code>break $label_name</code> expression will cause the program to
|
|
to act as though the nearest (to the left) <code>label $label_name</code>
|
|
produced <code>empty</code>.</p>
|
|
<p>The relationship between the <code>break</code> and corresponding <code>label</code>
|
|
is lexical: the label has to be "visible" from the break.</p>
|
|
<p>To break out of a <code>reduce</code>, for example:</p>
|
|
<pre><code>label $out | reduce .[] as $item (null; if .==false then break $out else ... end)
|
|
</code></pre>
|
|
<p>The following jq program produces a syntax error:</p>
|
|
<pre><code>break $out
|
|
</code></pre>
|
|
<p>because no label <code>$out</code> is visible.</p>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="ErrorSuppression/OptionalOperator:?">
|
|
<h3>
|
|
Error Suppression / Optional Operator: <code>?</code>
|
|
|
|
</h3>
|
|
<p>The <code>?</code> operator, used as <code>EXP?</code>, is shorthand for <code>try EXP</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example83">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example83" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[.[] | .a?]'</td></tr>
|
|
<tr><th>Input</th><td>[{}, true, {"a":1}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[null, 1]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[.[] | tonumber?]'</td></tr>
|
|
<tr><th>Input</th><td>["1", "invalid", "3", 4]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1, 3, 4]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="Regularexpressions">
|
|
<h2>Regular expressions</h2>
|
|
<p>jq uses the
|
|
<a href="https://github.com/kkos/oniguruma/blob/master/doc/RE">Oniguruma regular expression library</a>,
|
|
as do PHP, TextMate, Sublime Text, etc, so the
|
|
description here will focus on jq specifics.</p>
|
|
<p>Oniguruma supports several flavors of regular expression, so it is important to know
|
|
that jq uses the <a href="https://github.com/kkos/oniguruma/blob/master/doc/SYNTAX.md">"Perl NG" (Perl with named groups)</a> flavor.</p>
|
|
<p>The jq regex filters are defined so that they can be used using
|
|
one of these patterns:</p>
|
|
<pre><code>STRING | FILTER(REGEX)
|
|
STRING | FILTER(REGEX; FLAGS)
|
|
STRING | FILTER([REGEX])
|
|
STRING | FILTER([REGEX, FLAGS])
|
|
</code></pre>
|
|
<p>where:</p>
|
|
<ul>
|
|
<li>STRING, REGEX, and FLAGS are jq strings and subject to jq string interpolation;</li>
|
|
<li>REGEX, after string interpolation, should be a valid regular expression;</li>
|
|
<li>FILTER is one of <code>test</code>, <code>match</code>, or <code>capture</code>, as described below.</li>
|
|
</ul>
|
|
<p>Since REGEX must evaluate to a JSON string, some characters that are needed
|
|
to form a regular expression must be escaped. For example, the regular expression
|
|
<code>\s</code> signifying a whitespace character would be written as <code>"\\s"</code>.</p>
|
|
<p>FLAGS is a string consisting of one of more of the supported flags:</p>
|
|
<ul>
|
|
<li><code>g</code> - Global search (find all matches, not just the first)</li>
|
|
<li><code>i</code> - Case insensitive search</li>
|
|
<li><code>m</code> - Multi line mode (<code>.</code> will match newlines)</li>
|
|
<li><code>n</code> - Ignore empty matches</li>
|
|
<li><code>p</code> - Both s and m modes are enabled</li>
|
|
<li><code>s</code> - Single line mode (<code>^</code> -> <code>\A</code>, <code>$</code> -> <code>\Z</code>)</li>
|
|
<li><code>l</code> - Find longest possible matches</li>
|
|
<li><code>x</code> - Extended regex format (ignore whitespace and comments)</li>
|
|
</ul>
|
|
<p>To match a whitespace with the <code>x</code> flag, use <code>\s</code>, e.g.</p>
|
|
<pre><code>jq -n '"a b" | test("a\\sb"; "x")'
|
|
</code></pre>
|
|
<p>Note that certain flags may also be specified within REGEX, e.g.</p>
|
|
<pre><code>jq -n '("test", "TEst", "teST", "TEST") | test("(?i)te(?-i)st")'
|
|
</code></pre>
|
|
<p>evaluates to: <code>true</code>, <code>true</code>, <code>false</code>, <code>false</code>.</p>
|
|
|
|
<section id="test(val),test(regex;flags)">
|
|
<h3>
|
|
<code>test(val)</code>, <code>test(regex; flags)</code>
|
|
|
|
</h3>
|
|
<p>Like <code>match</code>, but does not return match objects, only <code>true</code> or <code>false</code>
|
|
for whether or not the regex matches the input.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example84">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example84" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'test("foo")'</td></tr>
|
|
<tr><th>Input</th><td>"foo"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] | test("a b c # spaces are ignored"; "ix")'</td></tr>
|
|
<tr><th>Input</th><td>["xabcd", "ABC"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="match(val),match(regex;flags)">
|
|
<h3>
|
|
<code>match(val)</code>, <code>match(regex; flags)</code>
|
|
|
|
</h3>
|
|
<p><strong>match</strong> outputs an object for each match it finds. Matches have
|
|
the following fields:</p>
|
|
<ul>
|
|
<li><code>offset</code> - offset in UTF-8 codepoints from the beginning of the input</li>
|
|
<li><code>length</code> - length in UTF-8 codepoints of the match</li>
|
|
<li><code>string</code> - the string that it matched</li>
|
|
<li><code>captures</code> - an array of objects representing capturing groups.</li>
|
|
</ul>
|
|
<p>Capturing group objects have the following fields:</p>
|
|
<ul>
|
|
<li><code>offset</code> - offset in UTF-8 codepoints from the beginning of the input</li>
|
|
<li><code>length</code> - length in UTF-8 codepoints of this capturing group</li>
|
|
<li><code>string</code> - the string that was captured</li>
|
|
<li><code>name</code> - the name of the capturing group (or <code>null</code> if it was unnamed)</li>
|
|
</ul>
|
|
<p>Capturing groups that did not match anything return an offset of -1</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example85">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example85" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'match("(abc)+"; "g")'</td></tr>
|
|
<tr><th>Input</th><td>"abc abc"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"offset": 0, "length": 3, "string": "abc", "captures": [{"offset": 0, "length": 3, "string": "abc", "name": null}]}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"offset": 4, "length": 3, "string": "abc", "captures": [{"offset": 4, "length": 3, "string": "abc", "name": null}]}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'match("foo")'</td></tr>
|
|
<tr><th>Input</th><td>"foo bar foo"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"offset": 0, "length": 3, "string": "foo", "captures": []}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'match(["foo", "ig"])'</td></tr>
|
|
<tr><th>Input</th><td>"foo bar FOO"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"offset": 0, "length": 3, "string": "foo", "captures": []}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"offset": 8, "length": 3, "string": "FOO", "captures": []}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'match("foo (?<bar123>bar)? foo"; "ig")'</td></tr>
|
|
<tr><th>Input</th><td>"foo bar foo foo foo"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"offset": 0, "length": 11, "string": "foo bar foo", "captures": [{"offset": 4, "length": 3, "string": "bar", "name": "bar123"}]}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"offset": 12, "length": 8, "string": "foo foo", "captures": [{"offset": -1, "length": 0, "string": null, "name": "bar123"}]}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[ match("."; "g")] | length'</td></tr>
|
|
<tr><th>Input</th><td>"abc"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>3</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="capture(val),capture(regex;flags)">
|
|
<h3>
|
|
<code>capture(val)</code>, <code>capture(regex; flags)</code>
|
|
|
|
</h3>
|
|
<p>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.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example86">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example86" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'capture("(?<a>[a-z]+)-(?<n>[0-9]+)")'</td></tr>
|
|
<tr><th>Input</th><td>"xyzzy-14"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{ "a": "xyzzy", "n": "14" }</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="scan(regex),scan(regex;flags)">
|
|
<h3>
|
|
<code>scan(regex)</code>, <code>scan(regex; flags)</code>
|
|
|
|
</h3>
|
|
<p>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
|
|
<code>[ expr ]</code>, e.g. <code>[ scan(regex) ]</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example87">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example87" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'scan("c")'</td></tr>
|
|
<tr><th>Input</th><td>"abcdefabc"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"c"</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>"c"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="split(regex;flags)">
|
|
<h3>
|
|
<code>split(regex; flags)</code>
|
|
|
|
</h3>
|
|
<p>Splits an input string on each regex match.</p>
|
|
<p>For backwards compatibility, when called with a single argument,
|
|
<code>split</code> splits on a string, not a regex.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example88">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example88" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'split(", *"; null)'</td></tr>
|
|
<tr><th>Input</th><td>"ab,cd, ef"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["ab","cd","ef"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="splits(regex),splits(regex;flags)">
|
|
<h3>
|
|
<code>splits(regex)</code>, <code>splits(regex; flags)</code>
|
|
|
|
</h3>
|
|
<p>These provide the same results as their <code>split</code> counterparts,
|
|
but as a stream instead of an array.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example89">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example89" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'splits(", *")'</td></tr>
|
|
<tr><th>Input</th><td>"ab,cd, ef, gh"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"ab"</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>"cd"</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>"ef"</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>"gh"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="sub(regex;tostring),sub(regex;tostring;flags)">
|
|
<h3>
|
|
<code>sub(regex; tostring)</code>, <code>sub(regex; tostring; flags)</code>
|
|
|
|
</h3>
|
|
<p>Emit the string obtained by replacing the first match of
|
|
regex in the input string with <code>tostring</code>, after
|
|
interpolation. <code>tostring</code> should be a jq string or a stream
|
|
of such strings, each of which may contain references to
|
|
named captures. The named captures are, in effect, presented
|
|
as a JSON object (as constructed by <code>capture</code>) to
|
|
<code>tostring</code>, so a reference to a captured variable named "x"
|
|
would take the form: <code>"\(.x)"</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example90">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example90" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'sub("[^a-z]*(?<x>[a-z]+)"; "Z\(.x)"; "g")'</td></tr>
|
|
<tr><th>Input</th><td>"123abc456def"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"ZabcZdef"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[sub("(?<a>.)"; "\(.a|ascii_upcase)", "\(.a|ascii_downcase)")]'</td></tr>
|
|
<tr><th>Input</th><td>"aB"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["AB","aB"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="gsub(regex;tostring),gsub(regex;tostring;flags)">
|
|
<h3>
|
|
<code>gsub(regex; tostring)</code>, <code>gsub(regex; tostring; flags)</code>
|
|
|
|
</h3>
|
|
<p><code>gsub</code> is like <code>sub</code> but all the non-overlapping occurrences of the regex are
|
|
replaced by <code>tostring</code>, after interpolation. If the second argument is a stream
|
|
of jq strings, then <code>gsub</code> will produce a corresponding stream of JSON strings.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example91">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example91" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'gsub("(?<x>.)[^a]*"; "+\(.x)-")'</td></tr>
|
|
<tr><th>Input</th><td>"Abcabc"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>"+A-+a-"</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[gsub("p"; "a", "b")]'</td></tr>
|
|
<tr><th>Input</th><td>"p"</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>["a","b"]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="Advancedfeatures">
|
|
<h2>Advanced features</h2>
|
|
<p>Variables are an absolute necessity in most programming languages, but
|
|
they're relegated to an "advanced feature" in jq.</p>
|
|
<p>In most languages, variables are the only means of passing around
|
|
data. If you calculate a value, and you want to use it more than once,
|
|
you'll need to store it in a variable. To pass a value to another part
|
|
of the program, you'll need that part of the program to define a
|
|
variable (as a function parameter, object member, or whatever) in
|
|
which to place the data.</p>
|
|
<p>It is also possible to define functions in jq, although this is
|
|
is a feature whose biggest use is defining jq's standard library
|
|
(many jq functions such as <code>map</code> and <code>select</code> are in fact written
|
|
in jq).</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>Some minimal I/O support (besides reading JSON from standard
|
|
input, and writing JSON to standard output) is available.</p>
|
|
<p>Finally, there is a module/library system.</p>
|
|
|
|
<section id="Variable/SymbolicBindingOperator:...as$identifier|...">
|
|
<h3>
|
|
Variable / Symbolic Binding Operator: <code>... as $identifier | ...</code>
|
|
|
|
</h3>
|
|
<p>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 <code>a + b</code>, pass their input
|
|
to two distinct subexpressions (here <code>a</code> and <code>b</code> are both passed the
|
|
same input), so variables aren't usually necessary in order to use a
|
|
value twice.</p>
|
|
<p>For instance, calculating the average value of an array of numbers
|
|
requires a 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 <code>add / length</code> - the <code>add</code> expression is given the array and
|
|
produces its sum, and the <code>length</code> expression is given the array and
|
|
produces its length.</p>
|
|
<p>So, there's generally a cleaner way to solve most problems in jq than
|
|
defining variables. Still, sometimes they do make things easier, so jq
|
|
lets you define variables using <code>expression as $variable</code>. All
|
|
variable names start with <code>$</code>. Here's a slightly uglier version of the
|
|
array-averaging example:</p>
|
|
<pre><code>length as $array_length | add / $array_length
|
|
</code></pre>
|
|
<p>We'll need a more complicated problem to find a situation where using
|
|
variables actually makes our lives easier.</p>
|
|
<p>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:</p>
|
|
<pre><code>{"posts": [{"title": "First post", "author": "anon"},
|
|
{"title": "A well-written article", "author": "person1"}],
|
|
"realnames": {"anon": "Anonymous Coward",
|
|
"person1": "Person McPherson"}}
|
|
</code></pre>
|
|
<p>We want to produce the posts with the author field containing a real
|
|
name, as in:</p>
|
|
<pre><code>{"title": "First post", "author": "Anonymous Coward"}
|
|
{"title": "A well-written article", "author": "Person McPherson"}
|
|
</code></pre>
|
|
<p>We use a variable, $names, to store the realnames object, so that we
|
|
can refer to it later when looking up author usernames:</p>
|
|
<pre><code>.realnames as $names | .posts[] | {title, author: $names[.author]}
|
|
</code></pre>
|
|
<p>The expression <code>exp as $x | ...</code> means: for each value of expression
|
|
<code>exp</code>, run the rest of the pipeline with the entire original input, and
|
|
with <code>$x</code> set to that value. Thus <code>as</code> functions as something of a
|
|
foreach loop.</p>
|
|
<p>Just as <code>{foo}</code> is a handy way of writing <code>{foo: .foo}</code>, so
|
|
<code>{$foo}</code> is a handy way of writing <code>{foo: $foo}</code>.</p>
|
|
<p>Multiple variables may be declared using a single <code>as</code> expression by
|
|
providing a pattern that matches the structure of the input
|
|
(this is known as "destructuring"):</p>
|
|
<pre><code>. as {realnames: $names, posts: [$first, $second]} | ...
|
|
</code></pre>
|
|
<p>The variable declarations in array patterns (e.g., <code>. as
|
|
[$first, $second]</code>) 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, <code>null</code> is
|
|
bound to that variable.</p>
|
|
<p>Variables are scoped over the rest of the expression that defines
|
|
them, so</p>
|
|
<pre><code>.realnames as $names | (.posts[] | {title, author: $names[.author]})
|
|
</code></pre>
|
|
<p>will work, but</p>
|
|
<pre><code>(.realnames as $names | .posts[]) | {title, author: $names[.author]}
|
|
</code></pre>
|
|
<p>won't.</p>
|
|
<p>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.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example92">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example92" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.bar as $x | .foo | . + $x'</td></tr>
|
|
<tr><th>Input</th><td>{"foo":10, "bar":200}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>210</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '. as $i|[(.*2|. as $i| $i), $i]'</td></tr>
|
|
<tr><th>Input</th><td>5</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[10,5]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '. as [$a, $b, {c: $c}] | $a + $b + $c'</td></tr>
|
|
<tr><th>Input</th><td>[2, 3, {"c": 4, "d": 5}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>9</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] as [$a, $b] | {a: $a, b: $b}'</td></tr>
|
|
<tr><th>Input</th><td>[[0], [0, 1], [2, 1, 0]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a":0,"b":null}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"a":0,"b":1}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"a":2,"b":1}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="DestructuringAlternativeOperator:?//">
|
|
<h3>
|
|
Destructuring Alternative Operator: <code>?//</code>
|
|
|
|
</h3>
|
|
<p>The destructuring alternative operator provides a concise mechanism
|
|
for destructuring an input that can take one of several forms.</p>
|
|
<p>Suppose we have an API that returns a list of resources and events
|
|
associated with them, and we want to get the user_id and timestamp of
|
|
the first event for each resource. The API (having been clumsily
|
|
converted from XML) will only wrap the events in an array if the resource
|
|
has multiple events:</p>
|
|
<pre><code>{"resources": [{"id": 1, "kind": "widget", "events": {"action": "create", "user_id": 1, "ts": 13}},
|
|
{"id": 2, "kind": "widget", "events": [{"action": "create", "user_id": 1, "ts": 14}, {"action": "destroy", "user_id": 1, "ts": 15}]}]}
|
|
</code></pre>
|
|
<p>We can use the destructuring alternative operator to handle this structural change simply:</p>
|
|
<pre><code>.resources[] as {$id, $kind, events: {$user_id, $ts}} ?// {$id, $kind, events: [{$user_id, $ts}]} | {$user_id, $kind, $id, $ts}
|
|
</code></pre>
|
|
<p>Or, if we aren't sure if the input is an array of values or an object:</p>
|
|
<pre><code>.[] as [$id, $kind, $user_id, $ts] ?// {$id, $kind, $user_id, $ts} | ...
|
|
</code></pre>
|
|
<p>Each alternative need not define all of the same variables, but all named
|
|
variables will be available to the subsequent expression. Variables not
|
|
matched in the alternative that succeeded will be <code>null</code>:</p>
|
|
<pre><code>.resources[] as {$id, $kind, events: {$user_id, $ts}} ?// {$id, $kind, events: [{$first_user_id, $first_ts}]} | {$user_id, $first_user_id, $kind, $id, $ts, $first_ts}
|
|
</code></pre>
|
|
<p>Additionally, if the subsequent expression returns an error, the
|
|
alternative operator will attempt to try the next binding. Errors
|
|
that occur during the final alternative are passed through.</p>
|
|
<pre><code>[[3]] | .[] as [$a] ?// [$b] | if $a != null then error("err: \($a)") else {$a,$b} end
|
|
</code></pre>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example93">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example93" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] as {$a, $b, c: {$d, $e}} ?// {$a, $b, c: [{$d, $e}]} | {$a, $b, $d, $e}'</td></tr>
|
|
<tr><th>Input</th><td>[{"a": 1, "b": 2, "c": {"d": 3, "e": 4}}, {"a": 1, "b": 2, "c": [{"d": 3, "e": 4}]}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a":1,"b":2,"d":3,"e":4}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"a":1,"b":2,"d":3,"e":4}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] as {$a, $b, c: {$d}} ?// {$a, $b, c: [{$e}]} | {$a, $b, $d, $e}'</td></tr>
|
|
<tr><th>Input</th><td>[{"a": 1, "b": 2, "c": {"d": 3, "e": 4}}, {"a": 1, "b": 2, "c": [{"d": 3, "e": 4}]}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a":1,"b":2,"d":3,"e":null}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"a":1,"b":2,"d":null,"e":4}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.[] as [$a] ?// [$b] | if $a != null then error("err: \($a)") else {$a,$b} end'</td></tr>
|
|
<tr><th>Input</th><td>[[3]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a":null,"b":3}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="DefiningFunctions">
|
|
<h3>
|
|
Defining Functions
|
|
|
|
</h3>
|
|
<p>You can give a filter a name using "def" syntax:</p>
|
|
<pre><code>def increment: . + 1;
|
|
</code></pre>
|
|
<p>From then on, <code>increment</code> 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:</p>
|
|
<pre><code>def map(f): [.[] | f];
|
|
</code></pre>
|
|
<p>Arguments are passed as <em>filters</em> (functions with no
|
|
arguments), <em>not</em> as values. The same argument may be
|
|
referenced multiple times with different inputs (here <code>f</code> 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:</p>
|
|
<pre><code>def foo(f): f|f;
|
|
5|foo(.*2)
|
|
</code></pre>
|
|
<p>The result will be 20 because <code>f</code> is <code>.*2</code>, and during the
|
|
first invocation of <code>f</code> <code>.</code> 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.</p>
|
|
<p>If you want the value-argument behaviour for defining simple
|
|
functions, you can just use a variable:</p>
|
|
<pre><code>def addvalue(f): f as $f | map(. + $f);
|
|
</code></pre>
|
|
<p>Or use the short-hand:</p>
|
|
<pre><code>def addvalue($f): ...;
|
|
</code></pre>
|
|
<p>With either definition, <code>addvalue(.foo)</code> will add the current
|
|
input's <code>.foo</code> field to each element of the array. Do note
|
|
that calling <code>addvalue(.[])</code> will cause the <code>map(. + $f)</code> part
|
|
to be evaluated once per value in the value of <code>.</code> at the call
|
|
site.</p>
|
|
<p>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.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example94">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example94" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'def addvalue(f): . + [f]; map(addvalue(.[0]))'</td></tr>
|
|
<tr><th>Input</th><td>[[1,2],[10,20]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[[1,2,1], [10,20,10]]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'def addvalue(f): f as $x | map(. + $x); addvalue(.[0])'</td></tr>
|
|
<tr><th>Input</th><td>[[1,2],[10,20]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[[1,2,1,2], [10,20,1,2]]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Scoping">
|
|
<h3>
|
|
Scoping
|
|
|
|
</h3>
|
|
<p>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.</p>
|
|
<p>For example, in the following expression there is a binding
|
|
which is visible "to the right" of it, <code>... | .*3 as
|
|
$times_three | [. + $times_three] | ...</code>, but not "to the
|
|
left". Consider this expression now, <code>... | (.*3 as
|
|
$times_three | [. + $times_three]) | ...</code>: here the binding
|
|
<code>$times_three</code> is <em>not</em> visible past the closing parenthesis.</p>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="isempty(exp)">
|
|
<h3>
|
|
<code>isempty(exp)</code>
|
|
|
|
</h3>
|
|
<p>Returns true if <code>exp</code> produces no outputs, false otherwise.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example95">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example95" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'isempty(empty)'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'isempty(.[])'</td></tr>
|
|
<tr><th>Input</th><td>[]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'isempty(.[])'</td></tr>
|
|
<tr><th>Input</th><td>[1,2,3]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>false</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="limit(n;exp)">
|
|
<h3>
|
|
<code>limit(n; exp)</code>
|
|
|
|
</h3>
|
|
<p>The <code>limit</code> function extracts up to <code>n</code> outputs from <code>exp</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example96">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example96" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[limit(3;.[])]'</td></tr>
|
|
<tr><th>Input</th><td>[0,1,2,3,4,5,6,7,8,9]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[0,1,2]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="first(expr),last(expr),nth(n;expr)">
|
|
<h3>
|
|
<code>first(expr)</code>, <code>last(expr)</code>, <code>nth(n; expr)</code>
|
|
|
|
</h3>
|
|
<p>The <code>first(expr)</code> and <code>last(expr)</code> functions extract the first
|
|
and last values from <code>expr</code>, respectively.</p>
|
|
<p>The <code>nth(n; expr)</code> function extracts the nth value output by <code>expr</code>.
|
|
Note that <code>nth(n; expr)</code> doesn't support negative values of <code>n</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example97">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example97" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[first(range(.)), last(range(.)), nth(./2; range(.))]'</td></tr>
|
|
<tr><th>Input</th><td>10</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[0,9,5]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="first,last,nth(n)">
|
|
<h3>
|
|
<code>first</code>, <code>last</code>, <code>nth(n)</code>
|
|
|
|
</h3>
|
|
<p>The <code>first</code> and <code>last</code> functions extract the first
|
|
and last values from any array at <code>.</code>.</p>
|
|
<p>The <code>nth(n)</code> function extracts the nth value of any array at <code>.</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example98">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example98" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '[range(.)]|[first, last, nth(5)]'</td></tr>
|
|
<tr><th>Input</th><td>10</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[0,9,5]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="reduce">
|
|
<h3>
|
|
<code>reduce</code>
|
|
|
|
</h3>
|
|
<p>The <code>reduce</code> syntax allows you to combine all of the results of
|
|
an expression by accumulating them into a single answer.
|
|
The form is <code>reduce EXP as $var (INIT; UPDATE)</code>.
|
|
As an example, we'll pass <code>[1,2,3]</code> to this expression:</p>
|
|
<pre><code>reduce .[] as $item (0; . + $item)
|
|
</code></pre>
|
|
<p>For each result that <code>.[]</code> produces, <code>. + $item</code> is run to
|
|
accumulate a running total, starting from 0 as the input value.
|
|
In this example, <code>.[]</code> produces the results <code>1</code>, <code>2</code>, and <code>3</code>,
|
|
so the effect is similar to running something like this:</p>
|
|
<pre><code>0 | 1 as $item | . + $item |
|
|
2 as $item | . + $item |
|
|
3 as $item | . + $item
|
|
</code></pre>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example99">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example99" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'reduce .[] as $item (0; . + $item)'</td></tr>
|
|
<tr><th>Input</th><td>[1,2,3,4,5]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>15</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'reduce .[] as [$i,$j] (0; . + $i * $j)'</td></tr>
|
|
<tr><th>Input</th><td>[[1,2],[3,4],[5,6]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>44</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'reduce .[] as {$x,$y} (null; .x += $x | .y += [$y])'</td></tr>
|
|
<tr><th>Input</th><td>[{"x":"a","y":1},{"x":"b","y":2},{"x":"c","y":3}]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"x":"abc","y":[1,2,3]}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="foreach">
|
|
<h3>
|
|
<code>foreach</code>
|
|
|
|
</h3>
|
|
<p>The <code>foreach</code> syntax is similar to <code>reduce</code>, but intended to
|
|
allow the construction of <code>limit</code> and reducers that produce
|
|
intermediate results.</p>
|
|
<p>The form is <code>foreach EXP as $var (INIT; UPDATE; EXTRACT)</code>.
|
|
As an example, we'll pass <code>[1,2,3]</code> to this expression:</p>
|
|
<pre><code>foreach .[] as $item (0; . + $item; [$item, . * 2])
|
|
</code></pre>
|
|
<p>Like the <code>reduce</code> syntax, <code>. + $item</code> is run for each result
|
|
that <code>.[]</code> produces, but <code>[$item, . * 2]</code> is run for each
|
|
intermediate values. In this example, since the intermediate
|
|
values are <code>1</code>, <code>3</code>, and <code>6</code>, the <code>foreach</code> expression produces
|
|
<code>[1,2]</code>, <code>[2,6]</code>, and <code>[3,12]</code>. So the effect is similar
|
|
to running something like this:</p>
|
|
<pre><code>0 | 1 as $item | . + $item | [$item, . * 2],
|
|
2 as $item | . + $item | [$item, . * 2],
|
|
3 as $item | . + $item | [$item, . * 2]
|
|
</code></pre>
|
|
<p>When <code>EXTRACT</code> is omitted, the identity filter is used.
|
|
That is, it outputs the intermediate values as they are.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example100">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example100" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'foreach .[] as $item (0; . + $item)'</td></tr>
|
|
<tr><th>Input</th><td>[1,2,3,4,5]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>1</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>3</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>6</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>10</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>15</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'foreach .[] as $item (0; . + $item; [$item, . * 2])'</td></tr>
|
|
<tr><th>Input</th><td>[1,2,3,4,5]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1,2]</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>[2,6]</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>[3,12]</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>[4,20]</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>[5,30]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'foreach .[] as $item (0; . + 1; {index: ., $item})'</td></tr>
|
|
<tr><th>Input</th><td>["foo", "bar", "baz"]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"index":1,"item":"foo"}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"index":2,"item":"bar"}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"index":3,"item":"baz"}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Recursion">
|
|
<h3>
|
|
Recursion
|
|
|
|
</h3>
|
|
<p>As described above, <code>recurse</code> uses recursion, and any jq
|
|
function can be recursive. The <code>while</code> builtin is also
|
|
implemented in terms of recursion.</p>
|
|
<p>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.</p>
|
|
<p>For example:</p>
|
|
<pre><code>def recurse(f): def r: ., (f | select(. != null) | r); r;
|
|
|
|
def while(cond; update):
|
|
def _while:
|
|
if cond then ., (update | _while) else empty end;
|
|
_while;
|
|
|
|
def repeat(exp):
|
|
def _repeat:
|
|
exp, _repeat;
|
|
_repeat;
|
|
</code></pre>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="Generatorsanditerators">
|
|
<h3>
|
|
Generators and iterators
|
|
|
|
</h3>
|
|
<p>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, <code>.[]</code>
|
|
generates all the values in its input (which must be an
|
|
array or an object), <code>range(0; 10)</code> generates the integers
|
|
between 0 and 10, and so on.</p>
|
|
<p>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.</p>
|
|
<p>The <code>empty</code> builtin is the generator that produces zero
|
|
outputs. The <code>empty</code> builtin backtracks to the preceding
|
|
generator expression.</p>
|
|
<p>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 <code>_range</code> to itself is in tail position.
|
|
The example shows off three advanced topics: tail recursion,
|
|
generator construction, and sub-functions.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example101">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example101" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">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)'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>0</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>3</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>6</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>9</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'def while(cond; update): def _while: if cond then ., (update | _while) else empty end; _while; [while(.<100; .*2)]'</td></tr>
|
|
<tr><th>Input</th><td>1</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1,2,4,8,16,32,64]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="Math">
|
|
<h2>Math</h2>
|
|
<p>jq currently only has IEEE754 double-precision (64-bit) floating
|
|
point number support.</p>
|
|
<p>Besides simple arithmetic operators such as <code>+</code>, jq also has most
|
|
standard math functions from the C math library. C math functions
|
|
that take a single input argument (e.g., <code>sin()</code>) are available as
|
|
zero-argument jq functions. C math functions that take two input
|
|
arguments (e.g., <code>pow()</code>) are available as two-argument jq
|
|
functions that ignore <code>.</code>. C math functions that take three input
|
|
arguments are available as three-argument jq functions that ignore
|
|
<code>.</code>.</p>
|
|
<p>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.</p>
|
|
<p>One-input C math functions: <code>acos</code> <code>acosh</code> <code>asin</code> <code>asinh</code> <code>atan</code>
|
|
<code>atanh</code> <code>cbrt</code> <code>ceil</code> <code>cos</code> <code>cosh</code> <code>erf</code> <code>erfc</code> <code>exp</code> <code>exp10</code>
|
|
<code>exp2</code> <code>expm1</code> <code>fabs</code> <code>floor</code> <code>gamma</code> <code>j0</code> <code>j1</code> <code>lgamma</code> <code>log</code>
|
|
<code>log10</code> <code>log1p</code> <code>log2</code> <code>logb</code> <code>nearbyint</code> <code>pow10</code> <code>rint</code> <code>round</code>
|
|
<code>significand</code> <code>sin</code> <code>sinh</code> <code>sqrt</code> <code>tan</code> <code>tanh</code> <code>tgamma</code> <code>trunc</code>
|
|
<code>y0</code> <code>y1</code>.</p>
|
|
<p>Two-input C math functions: <code>atan2</code> <code>copysign</code> <code>drem</code> <code>fdim</code>
|
|
<code>fmax</code> <code>fmin</code> <code>fmod</code> <code>frexp</code> <code>hypot</code> <code>jn</code> <code>ldexp</code> <code>modf</code>
|
|
<code>nextafter</code> <code>nexttoward</code> <code>pow</code> <code>remainder</code> <code>scalb</code> <code>scalbln</code> <code>yn</code>.</p>
|
|
<p>Three-input C math functions: <code>fma</code>.</p>
|
|
<p>See your system's manual for more information on each of these.</p>
|
|
|
|
</section>
|
|
|
|
<section id="IO">
|
|
<h2>I/O</h2>
|
|
<p>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, <code>input</code> and <code>inputs</code>, that read from the
|
|
same sources (e.g., <code>stdin</code>, files named on the command-line) as
|
|
jq itself. These two builtins, and jq's own reading actions, can
|
|
be interleaved with each other. They are commonly used in combination
|
|
with the null input option <code>-n</code> to prevent one input from being read
|
|
implicitly.</p>
|
|
<p>Two builtins provide minimal output capabilities, <code>debug</code>, and
|
|
<code>stderr</code>. (Recall that a jq program's output values are always
|
|
output as JSON texts on <code>stdout</code>.) The <code>debug</code> builtin can have
|
|
application-specific behavior, such as for executables that use
|
|
the libjq C API but aren't the jq executable itself. The <code>stderr</code>
|
|
builtin outputs its input in raw mode to stder with no additional
|
|
decoration, not even a newline.</p>
|
|
<p>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.</p>
|
|
|
|
<section id="input">
|
|
<h3>
|
|
<code>input</code>
|
|
|
|
</h3>
|
|
<p>Outputs one new input.</p>
|
|
<p>Note that when using <code>input</code> it is generally be necessary to
|
|
invoke jq with the <code>-n</code> command-line option, otherwise
|
|
the first entity will be lost.</p>
|
|
<pre><code>echo 1 2 3 4 | jq '[., input]' # [1,2] [3,4]
|
|
</code></pre>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="inputs">
|
|
<h3>
|
|
<code>inputs</code>
|
|
|
|
</h3>
|
|
<p>Outputs all remaining inputs, one by one.</p>
|
|
<p>This is primarily useful for reductions over a program's
|
|
inputs. Note that when using <code>inputs</code> it is generally necessary
|
|
to invoke jq with the <code>-n</code> command-line option, otherwise
|
|
the first entity will be lost.</p>
|
|
<pre><code>echo 1 2 3 | jq -n 'reduce inputs as $i (0; . + $i)' # 6
|
|
</code></pre>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="debug,debug(msgs)">
|
|
<h3>
|
|
<code>debug</code>, <code>debug(msgs)</code>
|
|
|
|
</h3>
|
|
<p>These two filters are like <code>.</code> but have as a side-effect the
|
|
production of one or more messages on stderr.</p>
|
|
<p>The message produced by the <code>debug</code> filter has the form</p>
|
|
<pre><code>["DEBUG:",<input-value>]
|
|
</code></pre>
|
|
<p>where <code><input-value></code> is a compact rendition of the input
|
|
value. This format may change in the future.</p>
|
|
<p>The <code>debug(msgs)</code> filter is defined as <code>(msgs | debug | empty), .</code>
|
|
thus allowing great flexibility in the content of the message,
|
|
while also allowing multi-line debugging statements to be created.</p>
|
|
<p>For example, the expression:</p>
|
|
<pre><code>1 as $x | 2 | debug("Entering function foo with $x == \($x)", .) | (.+1)
|
|
</code></pre>
|
|
<p>would produce the value 3 but with the following two lines
|
|
being written to stderr:</p>
|
|
<pre><code>["DEBUG:","Entering function foo with $x == 1"]
|
|
["DEBUG:",2]
|
|
</code></pre>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="stderr">
|
|
<h3>
|
|
<code>stderr</code>
|
|
|
|
</h3>
|
|
<p>Prints its input in raw and compact mode to stderr with no
|
|
additional decoration, not even a newline.</p>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="input_filename">
|
|
<h3>
|
|
<code>input_filename</code>
|
|
|
|
</h3>
|
|
<p>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.</p>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="input_line_number">
|
|
<h3>
|
|
<code>input_line_number</code>
|
|
|
|
</h3>
|
|
<p>Returns the line number of the input currently being filtered.</p>
|
|
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="Streaming">
|
|
<h2>Streaming</h2>
|
|
<p>With the <code>--stream</code> 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.</p>
|
|
<p>However, streaming isn't easy to deal with as the jq program will
|
|
have <code>[<path>, <leaf-value>]</code> (and a few other forms) as inputs.</p>
|
|
<p>Several builtins are provided to make handling streams easier.</p>
|
|
<p>The examples below use the streamed form of <code>[0,[1]]</code>, which is
|
|
<code>[[0],0],[[1,0],1],[[1,0]],[[1]]</code>.</p>
|
|
<p>Streaming forms include <code>[<path>, <leaf-value>]</code> (to indicate any
|
|
scalar value, empty array, or empty object), and <code>[<path>]</code> (to
|
|
indicate the end of an array or object). Future versions of jq
|
|
run with <code>--stream</code> and <code>-seq</code> may output additional forms such as
|
|
<code>["error message"]</code> when an input text fails to parse.</p>
|
|
|
|
<section id="truncate_stream(stream_expression)">
|
|
<h3>
|
|
<code>truncate_stream(stream_expression)</code>
|
|
|
|
</h3>
|
|
<p>Consumes a number as input and truncates the corresponding
|
|
number of path elements from the left of the outputs of the
|
|
given streaming expression.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example102">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example102" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]])'</td></tr>
|
|
<tr><th>Input</th><td>1</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[[0],2]</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>[[0]]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="fromstream(stream_expression)">
|
|
<h3>
|
|
<code>fromstream(stream_expression)</code>
|
|
|
|
</h3>
|
|
<p>Outputs values corresponding to the stream expression's
|
|
outputs.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example103">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example103" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq 'fromstream(1|truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]]))'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[2]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="tostream">
|
|
<h3>
|
|
<code>tostream</code>
|
|
|
|
</h3>
|
|
<p>The <code>tostream</code> builtin outputs the streamed form of its input.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example104">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example104" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '. as $dot|fromstream($dot|tostream)|.==$dot'</td></tr>
|
|
<tr><th>Input</th><td>[0,[1,{"a":1},{"b":2}]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>true</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="Assignment">
|
|
<h2>Assignment</h2>
|
|
<p>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".</p>
|
|
<p>If an object has two fields which are arrays, <code>.foo</code> and <code>.bar</code>,
|
|
and you append something to <code>.foo</code>, then <code>.bar</code> will not get
|
|
bigger, even if you've previously set <code>.bar = .foo</code>. 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).</p>
|
|
<p>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.</p>
|
|
<p>All the assignment operators in jq have path expressions on the
|
|
left-hand side (LHS). The right-hand side (RHS) provides values
|
|
to set to the paths named by the LHS path expressions.</p>
|
|
<p>Values in jq are always immutable. Internally, assignment works
|
|
by using a reduction to compute new, replacement values for <code>.</code> that
|
|
have had all the desired assignments applied to <code>.</code>, then
|
|
outputting the modified value. This might be made clear by this
|
|
example: <code>{a:{b:{c:1}}} | (.a.b|=3), .</code>. This will output
|
|
<code>{"a":{"b":3}}</code> and <code>{"a":{"b":{"c":1}}}</code> because the last
|
|
sub-expression, <code>.</code>, sees the original value, not the modified
|
|
value.</p>
|
|
<p>Most users will want to use modification assignment operators,
|
|
such as <code>|=</code> or <code>+=</code>, rather than <code>=</code>.</p>
|
|
<p>Note that the LHS of assignment operators refers to a value in
|
|
<code>.</code>. Thus <code>$var.foo = 1</code> won't work as expected (<code>$var.foo</code> is
|
|
not a valid or useful path expression in <code>.</code>); use <code>$var | .foo =
|
|
1</code> instead.</p>
|
|
<p>Note too that <code>.a,.b=0</code> does not set <code>.a</code> and <code>.b</code>, but
|
|
<code>(.a,.b)=0</code> sets both.</p>
|
|
|
|
<section id="Update-assignment:|=">
|
|
<h3>
|
|
Update-assignment: <code>|=</code>
|
|
|
|
</h3>
|
|
<p>This is the "update" operator <code>|=</code>. It takes a filter on the
|
|
right-hand side and works out the new value for the property
|
|
of <code>.</code> being assigned to by running the old value through this
|
|
expression. For instance, <code>(.foo, .bar) |= .+1</code> will build an
|
|
object with the <code>foo</code> field set to the input's <code>foo</code> plus 1,
|
|
and the <code>bar</code> field set to the input's <code>bar</code> plus 1.</p>
|
|
<p>The left-hand side can be any general path expression; see <code>path()</code>.</p>
|
|
<p>Note that the left-hand side of <code>|=</code> refers to a value in <code>.</code>.
|
|
Thus <code>$var.foo |= . + 1</code> won't work as expected (<code>$var.foo</code> is
|
|
not a valid or useful path expression in <code>.</code>); use <code>$var |
|
|
.foo |= . + 1</code> instead.</p>
|
|
<p>If the right-hand side outputs no values (i.e., <code>empty</code>), then
|
|
the left-hand side path will be deleted, as with <code>del(path)</code>.</p>
|
|
<p>If the right-hand side outputs multiple values, only the first
|
|
one will be used (COMPATIBILITY NOTE: in jq 1.5 and earlier
|
|
releases, it used to be that only the last one was used).</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example105">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example105" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '(..|select(type=="boolean")) |= if . then 1 else 0 end'</td></tr>
|
|
<tr><th>Input</th><td>[true,false,[5,true,[true,[false]],false]]</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>[1,0,[5,1,[1,[0]],0]]</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Arithmeticupdate-assignment:+=,-=,*=,/=,%=,//=">
|
|
<h3>
|
|
Arithmetic update-assignment: <code>+=</code>, <code>-=</code>, <code>*=</code>, <code>/=</code>, <code>%=</code>, <code>//=</code>
|
|
|
|
</h3>
|
|
<p>jq has a few operators of the form <code>a op= b</code>, which are all
|
|
equivalent to <code>a |= . op b</code>. So, <code>+= 1</code> can be used to
|
|
increment values, being the same as <code>|= . + 1</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example106">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Example
|
|
</a>
|
|
<div id="example106" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.foo += 1'</td></tr>
|
|
<tr><th>Input</th><td>{"foo": 42}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"foo": 43}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Plainassignment:=">
|
|
<h3>
|
|
Plain assignment: <code>=</code>
|
|
|
|
</h3>
|
|
<p>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).</p>
|
|
<p>If the RHS of <code>=</code> 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 <code>.</code>. For example,
|
|
<code>(.a,.b) = range(2)</code> outputs <code>{"a":0,"b":0}</code>, then
|
|
<code>{"a":1,"b":1}</code>. The "update" assignment forms (see above) do
|
|
not do this.</p>
|
|
<p>This example should show the difference between <code>=</code> and <code>|=</code>:</p>
|
|
<p>Provide input <code>{"a": {"b": 10}, "b": 20}</code> to the programs</p>
|
|
<pre><code>.a = .b
|
|
</code></pre>
|
|
<p>and</p>
|
|
<pre><code>.a |= .b
|
|
</code></pre>
|
|
<p>The former will set the <code>a</code> field of the input to the <code>b</code>
|
|
field of the input, and produce the output <code>{"a": 20, "b": 20}</code>.
|
|
The latter will set the <code>a</code> field of the input to the <code>a</code>
|
|
field's <code>b</code> field, producing <code>{"a": 10, "b": 20}</code>.</p>
|
|
|
|
|
|
<div>
|
|
|
|
<a data-toggle="collapse" href="#example107">
|
|
<i class="glyphicon glyphicon-chevron-right"></i>
|
|
Examples
|
|
</a>
|
|
<div id="example107" class="manual-example collapse">
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.a = .b'</td></tr>
|
|
<tr><th>Input</th><td>{"a": {"b": 10}, "b": 20}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a":20,"b":20}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '.a |= .b'</td></tr>
|
|
<tr><th>Input</th><td>{"a": {"b": 10}, "b": 20}</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a":10,"b":20}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '(.a, .b) = range(3)'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a":0,"b":0}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"a":1,"b":1}</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
|
|
<th></th>
|
|
|
|
<td>{"a":2,"b":2}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
<table>
|
|
<tr><th></th><td class="jqprogram">jq '(.a, .b) |= range(3)'</td></tr>
|
|
<tr><th>Input</th><td>null</td></tr>
|
|
|
|
|
|
<tr>
|
|
|
|
<th>Output</th>
|
|
|
|
<td>{"a":0,"b":0}</td>
|
|
</tr>
|
|
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
<section id="Complexassignments">
|
|
<h3>
|
|
Complex assignments
|
|
|
|
</h3>
|
|
<p>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:</p>
|
|
<pre><code>.posts[0].title = "JQ Manual"
|
|
</code></pre>
|
|
<p>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:</p>
|
|
<pre><code>.posts[].comments |= . + ["this is great"]
|
|
</code></pre>
|
|
<p>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).</p>
|
|
<p>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.</p>
|
|
<p>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:</p>
|
|
<pre><code>.posts[] | select(.author == "stedolan")
|
|
</code></pre>
|
|
<p>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:</p>
|
|
<pre><code>(.posts[] | select(.author == "stedolan") | .comments) |=
|
|
. + ["terrible."]
|
|
</code></pre>
|
|
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="Modules">
|
|
<h2>Modules</h2>
|
|
<p>jq has a library/module system. Modules are files whose names end
|
|
in <code>.jq</code>.</p>
|
|
<p>Modules imported by a program are searched for in a default search
|
|
path (see below). The <code>import</code> and <code>include</code> directives allow the
|
|
importer to alter this path.</p>
|
|
<p>Paths in the a search path are subject to various substitutions.</p>
|
|
<p>For paths starting with <code>~/</code>, the user's home directory is
|
|
substituted for <code>~</code>.</p>
|
|
<p>For paths starting with <code>$ORIGIN/</code>, the directory where the jq
|
|
executable is located is substituted for <code>$ORIGIN</code>.</p>
|
|
<p>For paths starting with <code>./</code> or paths that are <code>.</code>, the path of
|
|
the including file is substituted for <code>.</code>. For top-level programs
|
|
given on the command-line, the current directory is used.</p>
|
|
<p>Import directives can optionally specify a search path to which
|
|
the default is appended.</p>
|
|
<p>The default search path is the search path given to the <code>-L</code>
|
|
command-line option, else <code>["~/.jq", "$ORIGIN/../lib/jq",
|
|
"$ORIGIN/../lib"]</code>.</p>
|
|
<p>Null and empty string path elements terminate search path
|
|
processing.</p>
|
|
<p>A dependency with relative path <code>foo/bar</code> would be searched for in
|
|
<code>foo/bar.jq</code> and <code>foo/bar/bar.jq</code> 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.</p>
|
|
<p>Consecutive components with the same name are not allowed to avoid
|
|
ambiguities (e.g., <code>foo/foo</code>).</p>
|
|
<p>For example, with <code>-L$HOME/.jq</code> a module <code>foo</code> can be found in
|
|
<code>$HOME/.jq/foo.jq</code> and <code>$HOME/.jq/foo/foo.jq</code>.</p>
|
|
<p>If <code>$HOME/.jq</code> is a file, it is sourced into the main program.</p>
|
|
|
|
<section id="importRelativePathStringasNAME[<metadata>];">
|
|
<h3>
|
|
<code>import RelativePathString as NAME [<metadata>];</code>
|
|
|
|
</h3>
|
|
<p>Imports a module found at the given path relative to a
|
|
directory in a search path. A <code>.jq</code> suffix will be added to
|
|
the relative path string. The module's symbols are prefixed
|
|
with <code>NAME::</code>.</p>
|
|
<p>The optional metadata must be a constant jq expression. It
|
|
should be an object with keys like <code>homepage</code> and so on. At
|
|
this time jq only uses the <code>search</code> key/value of the metadata.
|
|
The metadata is also made available to users via the
|
|
<code>modulemeta</code> builtin.</p>
|
|
<p>The <code>search</code> 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.</p>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="includeRelativePathString[<metadata>];">
|
|
<h3>
|
|
<code>include RelativePathString [<metadata>];</code>
|
|
|
|
</h3>
|
|
<p>Imports a module found at the given path relative to a
|
|
directory in a search path as if it were included in place. A
|
|
<code>.jq</code> 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.</p>
|
|
<p>The optional metadata must be a constant jq expression. It
|
|
should be an object with keys like <code>homepage</code> and so on. At
|
|
this time jq only uses the <code>search</code> key/value of the metadata.
|
|
The metadata is also made available to users via the
|
|
<code>modulemeta</code> builtin.</p>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="importRelativePathStringas$NAME[<metadata>];">
|
|
<h3>
|
|
<code>import RelativePathString as $NAME [<metadata>];</code>
|
|
|
|
</h3>
|
|
<p>Imports a JSON file found at the given path relative to a
|
|
directory in a search path. A <code>.json</code> suffix will be added to
|
|
the relative path string. The file's data will be available
|
|
as <code>$NAME::NAME</code>.</p>
|
|
<p>The optional metadata must be a constant jq expression. It
|
|
should be an object with keys like <code>homepage</code> and so on. At
|
|
this time jq only uses the <code>search</code> key/value of the metadata.
|
|
The metadata is also made available to users via the
|
|
<code>modulemeta</code> builtin.</p>
|
|
<p>The <code>search</code> 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.</p>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="module<metadata>;">
|
|
<h3>
|
|
<code>module <metadata>;</code>
|
|
|
|
</h3>
|
|
<p>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 <code>modulemeta</code> builtin.</p>
|
|
<p>The metadata must be a constant jq expression. It should be
|
|
an object with keys like <code>homepage</code>. At this time jq doesn't
|
|
use this metadata, but it is made available to users via the
|
|
<code>modulemeta</code> builtin.</p>
|
|
|
|
|
|
</section>
|
|
|
|
<section id="modulemeta">
|
|
<h3>
|
|
<code>modulemeta</code>
|
|
|
|
</h3>
|
|
<p>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 <code>deps</code> key.</p>
|
|
<p>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.</p>
|
|
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="Colors">
|
|
<h2>Colors</h2>
|
|
<p>To configure alternative colors just set the <code>JQ_COLORS</code>
|
|
environment variable to colon-delimited list of partial terminal
|
|
escape sequences like <code>"1;31"</code>, in this order:</p>
|
|
<ul>
|
|
<li>color for <code>null</code></li>
|
|
<li>color for <code>false</code></li>
|
|
<li>color for <code>true</code></li>
|
|
<li>color for numbers</li>
|
|
<li>color for strings</li>
|
|
<li>color for arrays</li>
|
|
<li>color for objects</li>
|
|
<li>color for object keys</li>
|
|
</ul>
|
|
<p>The default color scheme is the same as setting
|
|
<code>JQ_COLORS="1;30:0;37:0;37:0;37:0;32:1;37:1;37:1;34"</code>.</p>
|
|
<p>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:</p>
|
|
<ul>
|
|
<li>1 (bright)</li>
|
|
<li>2 (dim)</li>
|
|
<li>4 (underscore)</li>
|
|
<li>5 (blink)</li>
|
|
<li>7 (reverse)</li>
|
|
<li>8 (hidden)</li>
|
|
</ul>
|
|
<p>and the second is one of these:</p>
|
|
<ul>
|
|
<li>30 (black)</li>
|
|
<li>31 (red)</li>
|
|
<li>32 (green)</li>
|
|
<li>33 (yellow)</li>
|
|
<li>34 (blue)</li>
|
|
<li>35 (magenta)</li>
|
|
<li>36 (cyan)</li>
|
|
<li>37 (white)</li>
|
|
</ul>
|
|
|
|
</section>
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<footer>
|
|
<div class="container">
|
|
<p>This website is made with <a href="http://getbootstrap.com">Bootstrap</a>, themed with <a href="https://bootswatch.com">Bootswatch</a>.</p>
|
|
<p>jq is licensed under the MIT license (code) and the <a href="https://creativecommons.org/licenses/by/3.0/">CC-BY-3.0</a> license (docs).</p>
|
|
</div>
|
|
</footer>
|
|
|
|
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
|
|
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js" integrity="sha256-Sk3nkD6mLTMOF0EOpNtsIry+s1CsaqQC1rVLTAy+0yc= sha512-K1qjQ+NcF2TYO/eI3M6v8EiNYZfA95pQumfvcVrTHtwQVDG+aHRqLi/ETn2uB+1JqwYqVG3LIvdm9lj6imS/pQ==" crossorigin="anonymous"></script>
|
|
<script src="https://twitter.github.io/typeahead.js/releases/0.11.1/typeahead.bundle.js"></script>
|
|
<script>
|
|
var section_map = {
|
|
|
|
|
|
"Invoking jq" : "Invokingjq"
|
|
,
|
|
|
|
|
|
"Identity: ." : "Identity:.",
|
|
|
|
"Object Identifier-Index: .foo, .foo.bar" : "ObjectIdentifier-Index:.foo,.foo.bar",
|
|
|
|
"Optional Object Identifier-Index: .foo?" : "OptionalObjectIdentifier-Index:.foo?",
|
|
|
|
"Object Index: .[\u003cstring\u003e]" : "ObjectIndex:.[\u003cstring\u003e]",
|
|
|
|
"Array Index: .[\u003cnumber\u003e]" : "ArrayIndex:.[\u003cnumber\u003e]",
|
|
|
|
"Array/String Slice: .[\u003cnumber\u003e:\u003cnumber\u003e]" : "Array/StringSlice:.[\u003cnumber\u003e:\u003cnumber\u003e]",
|
|
|
|
"Array/Object Value Iterator: .[]" : "Array/ObjectValueIterator:.[]",
|
|
|
|
".[]?" : ".[]?",
|
|
|
|
"Comma: ," : "Comma:,",
|
|
|
|
"Pipe: |" : "Pipe:|",
|
|
|
|
"Parenthesis" : "Parenthesis",
|
|
|
|
"Basic filters" : "Basicfilters"
|
|
,
|
|
|
|
|
|
"Array construction: []" : "Arrayconstruction:[]",
|
|
|
|
"Object Construction: {}" : "ObjectConstruction:{}",
|
|
|
|
"Recursive Descent: .." : "RecursiveDescent:..",
|
|
|
|
"Types and Values" : "TypesandValues"
|
|
,
|
|
|
|
|
|
"Addition: +" : "Addition:+",
|
|
|
|
"Subtraction: -" : "Subtraction:-",
|
|
|
|
"Multiplication, division, modulo: *, /, %" : "Multiplication,division,modulo:*,/,%",
|
|
|
|
"length" : "length",
|
|
|
|
"utf8bytelength" : "utf8bytelength",
|
|
|
|
"keys, keys_unsorted" : "keys,keys_unsorted",
|
|
|
|
"has(key)" : "has(key)",
|
|
|
|
"in" : "in",
|
|
|
|
"map(f), map_values(f)" : "map(f),map_values(f)",
|
|
|
|
"pick(pathexps)" : "pick(pathexps)",
|
|
|
|
"path(path_expression)" : "path(path_expression)",
|
|
|
|
"del(path_expression)" : "del(path_expression)",
|
|
|
|
"getpath(PATHS)" : "getpath(PATHS)",
|
|
|
|
"setpath(PATHS; VALUE)" : "setpath(PATHS;VALUE)",
|
|
|
|
"delpaths(PATHS)" : "delpaths(PATHS)",
|
|
|
|
"to_entries, from_entries, with_entries(f)" : "to_entries,from_entries,with_entries(f)",
|
|
|
|
"select(boolean_expression)" : "select(boolean_expression)",
|
|
|
|
"arrays, objects, iterables, booleans, numbers, normals, finites, strings, nulls, values, scalars" : "arrays,objects,iterables,booleans,numbers,normals,finites,strings,nulls,values,scalars",
|
|
|
|
"empty" : "empty",
|
|
|
|
"error, error(message)" : "error,error(message)",
|
|
|
|
"halt" : "halt",
|
|
|
|
"halt_error, halt_error(exit_code)" : "halt_error,halt_error(exit_code)",
|
|
|
|
"$__loc__" : "$__loc__",
|
|
|
|
"paths, paths(node_filter)" : "paths,paths(node_filter)",
|
|
|
|
"add" : "add",
|
|
|
|
"any, any(condition), any(generator; condition)" : "any,any(condition),any(generator;condition)",
|
|
|
|
"all, all(condition), all(generator; condition)" : "all,all(condition),all(generator;condition)",
|
|
|
|
"flatten, flatten(depth)" : "flatten,flatten(depth)",
|
|
|
|
"range(upto), range(from; upto), range(from; upto; by)" : "range(upto),range(from;upto),range(from;upto;by)",
|
|
|
|
"floor" : "floor",
|
|
|
|
"sqrt" : "sqrt",
|
|
|
|
"tonumber" : "tonumber",
|
|
|
|
"tostring" : "tostring",
|
|
|
|
"type" : "type",
|
|
|
|
"infinite, nan, isinfinite, isnan, isfinite, isnormal" : "infinite,nan,isinfinite,isnan,isfinite,isnormal",
|
|
|
|
"sort, sort_by(path_expression)" : "sort,sort_by(path_expression)",
|
|
|
|
"group_by(path_expression)" : "group_by(path_expression)",
|
|
|
|
"min, max, min_by(path_exp), max_by(path_exp)" : "min,max,min_by(path_exp),max_by(path_exp)",
|
|
|
|
"unique, unique_by(path_exp)" : "unique,unique_by(path_exp)",
|
|
|
|
"reverse" : "reverse",
|
|
|
|
"contains(element)" : "contains(element)",
|
|
|
|
"indices(s)" : "indices(s)",
|
|
|
|
"index(s), rindex(s)" : "index(s),rindex(s)",
|
|
|
|
"inside" : "inside",
|
|
|
|
"startswith(str)" : "startswith(str)",
|
|
|
|
"endswith(str)" : "endswith(str)",
|
|
|
|
"combinations, combinations(n)" : "combinations,combinations(n)",
|
|
|
|
"ltrimstr(str)" : "ltrimstr(str)",
|
|
|
|
"rtrimstr(str)" : "rtrimstr(str)",
|
|
|
|
"explode" : "explode",
|
|
|
|
"implode" : "implode",
|
|
|
|
"split(str)" : "split(str)",
|
|
|
|
"join(str)" : "join(str)",
|
|
|
|
"ascii_downcase, ascii_upcase" : "ascii_downcase,ascii_upcase",
|
|
|
|
"while(cond; update)" : "while(cond;update)",
|
|
|
|
"repeat(exp)" : "repeat(exp)",
|
|
|
|
"until(cond; next)" : "until(cond;next)",
|
|
|
|
"recurse(f), recurse, recurse(f; condition)" : "recurse(f),recurse,recurse(f;condition)",
|
|
|
|
"walk(f)" : "walk(f)",
|
|
|
|
"$ENV, env" : "$ENV,env",
|
|
|
|
"transpose" : "transpose",
|
|
|
|
"bsearch(x)" : "bsearch(x)",
|
|
|
|
"String interpolation: \\(exp)" : "Stringinterpolation:\\(exp)",
|
|
|
|
"Convert to/from JSON" : "Convertto/fromJSON",
|
|
|
|
"Format strings and escaping" : "Formatstringsandescaping",
|
|
|
|
"Dates" : "Dates",
|
|
|
|
"SQL-Style Operators" : "SQL-StyleOperators",
|
|
|
|
"builtins" : "builtins",
|
|
|
|
"Builtin operators and functions" : "Builtinoperatorsandfunctions"
|
|
,
|
|
|
|
|
|
"==, !=" : "==,!=",
|
|
|
|
"if-then-else-end" : "if-then-else-end",
|
|
|
|
"\u003e, \u003e=, \u003c=, \u003c" : "\u003e,\u003e=,\u003c=,\u003c",
|
|
|
|
"and, or, not" : "and,or,not",
|
|
|
|
"Alternative operator: //" : "Alternativeoperator://",
|
|
|
|
"try-catch" : "try-catch",
|
|
|
|
"Breaking out of control structures" : "Breakingoutofcontrolstructures",
|
|
|
|
"Error Suppression / Optional Operator: ?" : "ErrorSuppression/OptionalOperator:?",
|
|
|
|
"Conditionals and Comparisons" : "ConditionalsandComparisons"
|
|
,
|
|
|
|
|
|
"test(val), test(regex; flags)" : "test(val),test(regex;flags)",
|
|
|
|
"match(val), match(regex; flags)" : "match(val),match(regex;flags)",
|
|
|
|
"capture(val), capture(regex; flags)" : "capture(val),capture(regex;flags)",
|
|
|
|
"scan(regex), scan(regex; flags)" : "scan(regex),scan(regex;flags)",
|
|
|
|
"split(regex; flags)" : "split(regex;flags)",
|
|
|
|
"splits(regex), splits(regex; flags)" : "splits(regex),splits(regex;flags)",
|
|
|
|
"sub(regex; tostring), sub(regex; tostring; flags)" : "sub(regex;tostring),sub(regex;tostring;flags)",
|
|
|
|
"gsub(regex; tostring), gsub(regex; tostring; flags)" : "gsub(regex;tostring),gsub(regex;tostring;flags)",
|
|
|
|
"Regular expressions" : "Regularexpressions"
|
|
,
|
|
|
|
|
|
"Variable / Symbolic Binding Operator: ... as $identifier | ..." : "Variable/SymbolicBindingOperator:...as$identifier|...",
|
|
|
|
"Destructuring Alternative Operator: ?//" : "DestructuringAlternativeOperator:?//",
|
|
|
|
"Defining Functions" : "DefiningFunctions",
|
|
|
|
"Scoping" : "Scoping",
|
|
|
|
"isempty(exp)" : "isempty(exp)",
|
|
|
|
"limit(n; exp)" : "limit(n;exp)",
|
|
|
|
"first(expr), last(expr), nth(n; expr)" : "first(expr),last(expr),nth(n;expr)",
|
|
|
|
"first, last, nth(n)" : "first,last,nth(n)",
|
|
|
|
"reduce" : "reduce",
|
|
|
|
"foreach" : "foreach",
|
|
|
|
"Recursion" : "Recursion",
|
|
|
|
"Generators and iterators" : "Generatorsanditerators",
|
|
|
|
"Advanced features" : "Advancedfeatures"
|
|
,
|
|
|
|
|
|
"Math" : "Math"
|
|
,
|
|
|
|
|
|
"input" : "input",
|
|
|
|
"inputs" : "inputs",
|
|
|
|
"debug, debug(msgs)" : "debug,debug(msgs)",
|
|
|
|
"stderr" : "stderr",
|
|
|
|
"input_filename" : "input_filename",
|
|
|
|
"input_line_number" : "input_line_number",
|
|
|
|
"I/O" : "IO"
|
|
,
|
|
|
|
|
|
"truncate_stream(stream_expression)" : "truncate_stream(stream_expression)",
|
|
|
|
"fromstream(stream_expression)" : "fromstream(stream_expression)",
|
|
|
|
"tostream" : "tostream",
|
|
|
|
"Streaming" : "Streaming"
|
|
,
|
|
|
|
|
|
"Update-assignment: |=" : "Update-assignment:|=",
|
|
|
|
"Arithmetic update-assignment: +=, -=, *=, /=, %=, //=" : "Arithmeticupdate-assignment:+=,-=,*=,/=,%=,//=",
|
|
|
|
"Plain assignment: =" : "Plainassignment:=",
|
|
|
|
"Complex assignments" : "Complexassignments",
|
|
|
|
"Assignment" : "Assignment"
|
|
,
|
|
|
|
|
|
"import RelativePathString as NAME [\u003cmetadata\u003e];" : "importRelativePathStringasNAME[\u003cmetadata\u003e];",
|
|
|
|
"include RelativePathString [\u003cmetadata\u003e];" : "includeRelativePathString[\u003cmetadata\u003e];",
|
|
|
|
"import RelativePathString as $NAME [\u003cmetadata\u003e];" : "importRelativePathStringas$NAME[\u003cmetadata\u003e];",
|
|
|
|
"module \u003cmetadata\u003e;" : "module\u003cmetadata\u003e;",
|
|
|
|
"modulemeta" : "modulemeta",
|
|
|
|
"Modules" : "Modules"
|
|
,
|
|
|
|
|
|
"Colors" : "Colors"
|
|
|
|
|
|
};
|
|
</script>
|
|
<script src="/jq/js/manual-search.js"></script>
|
|
</body>
|
|
</html> |