mirror of
https://github.com/stedolan/jq.git
synced 2024-05-11 05:55:39 +00:00
8310 lines
462 KiB
HTML
8310 lines
462 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<title>jq 1.7 Manual</title>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<link rel="icon" href="/jq/icon.svg" type="image/svg+xml">
|
|
<link rel="apple-touch-icon" href="/jq/icon.png" type="image/png">
|
|
<link rel="canonical" href="https://jqlang.github.io/jq/manual/v1.7/">
|
|
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootswatch@5.3.1/dist/cosmo/bootstrap.min.css"
|
|
integrity="sha384-dulfW0vmzZ638jigSgZXvDxMmd70GCnIv6oa+riKq6Kk4E0MKf7qmBfwP02wltv5" crossorigin="anonymous">
|
|
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.10.5/font/bootstrap-icons.css"
|
|
integrity="sha384-Ay26V7L8bsJTsX9Sxclnvsn+hkdiwRnrjZJXqKmkIDobPgIIWBOVguEcQQLDuhfN" crossorigin="anonymous">
|
|
<link rel="stylesheet" href="/jq/css/style.css" type="text/css">
|
|
<script>
|
|
(function() {
|
|
function setTheme(mediaQuery) {
|
|
document.documentElement.setAttribute('data-bs-theme',
|
|
document.documentElement.style.colorScheme = mediaQuery.matches ? 'dark' : 'light');
|
|
}
|
|
const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
|
|
setTheme(mediaQuery); mediaQuery.addEventListener('change', setTheme);
|
|
})();
|
|
</script>
|
|
</head>
|
|
|
|
<body>
|
|
<div class="container visually-hidden-focusable">
|
|
<a class="d-inline-flex p-2" href="#main">Skip to main content</a>
|
|
<a class="d-inline-flex p-2 m-1" href="#contents">Skip to table of contents</a>
|
|
</div>
|
|
<header class="navbar navbar-expand-md sticky-top bg-body-tertiary d-print-none">
|
|
<nav class="container-lg" aria-label="Page navigation">
|
|
<button type="button" class="navbar-toggler" data-bs-toggle="offcanvas" data-bs-target="#navbar-collapse"
|
|
aria-controls="navbar-collapse" aria-expanded="false" aria-label="Toggle page navigation">
|
|
<span class="navbar-toggler-icon"></span>
|
|
</button>
|
|
<a class="navbar-brand" href="/jq/" aria-label="Top page"><img src="/jq/jq.svg" alt="jq logo" style="height:1.5rem"></a>
|
|
<div id="navbar-collapse" class="offcanvas offcanvas-start navbar-collapse w-auto" aria-labelledby="navbar-title">
|
|
<div class="offcanvas-header">
|
|
<h3 id="navbar-title" class="me-3">jq</h3>
|
|
<button type="button" class="d-md-none btn-close" data-bs-dismiss="offcanvas" aria-label="Close page navigation"></button>
|
|
</div>
|
|
<ul class="offcanvas-body navbar-nav me-auto text-nowrap">
|
|
<li class="nav-item d-md-none"><a class="nav-link" href="/jq/">Top page</a></li>
|
|
<li class="nav-item"><a class="nav-link" href="/jq/tutorial/">Tutorial</a></li>
|
|
<li class="nav-item"><a class="nav-link" href="/jq/download/">Download</a></li>
|
|
<li class="nav-item"><a class="nav-link" href="/jq/manual/">Manual</a></li>
|
|
<li class="nav-item"><a class="nav-link" href="https://github.com/jqlang/jq" target="_blank" rel="noopener">GitHub</a></li>
|
|
<li class="nav-item"><a class="nav-link" href="https://github.com/jqlang/jq/issues" target="_blank" rel="noopener">Issues</a></li>
|
|
<li class="nav-item"><a class="nav-link" href="https://jqplay.org" target="_blank" rel="noopener">Try online!</a></li>
|
|
<li class="nav-item"><a class="nav-link" href="https://raw.githubusercontent.com/jqlang/jq/master/NEWS.md" target="_blank" rel="noopener">News</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="container-searchbox form-control p-0 d-none d-md-flex d-print-none border" style="width:16rem">
|
|
<span class="bi bi-search my-auto ms-2 me-1" aria-hidden="true"></span>
|
|
<input type="text" id="searchbox" class="form-control border-0 px-1" placeholder="Search manual" role="combobox"
|
|
aria-label="Search manual" aria-keyshortcuts="/" aria-expanded="false" autocomplete="off" spellcheck="false">
|
|
<kbd class="mx-1 my-auto text-body bg-body rounded border" style="padding:.1rem .2rem" aria-hidden="true">/</kbd>
|
|
</div>
|
|
<a class="d-md-none bi bi-github fs-4 text-body" href="https://github.com/jqlang/jq" target="_blank" rel="noopener" aria-label="GitHub"></a>
|
|
</nav>
|
|
</header>
|
|
|
|
<div class="container-lg row align-items-start mx-auto p-3">
|
|
|
|
<button type="button" class="d-md-none w-auto position-fixed bottom-0 end-0 p-2 m-3 bg-body-secondary border-0 text-body d-print-none"
|
|
data-bs-toggle="offcanvas" data-bs-target="#contents" aria-controls="contents" aria-expanded="false" aria-label="Toggle table of contents">
|
|
<span class="bi bi-list" aria-hidden="true"></span>
|
|
</button>
|
|
<nav id="contents" class="col-md-3 sticky-md-top p-3 overflow-y-auto offcanvas-md offcanvas-end d-print-none" style="top:4.5rem; height:calc(100dvh - 5.5rem);" aria-label="Table of contents">
|
|
<div class="d-flex justify-content-between">
|
|
<h4>Contents</h4>
|
|
<button type="button" class="btn-close d-md-none" data-bs-dismiss="offcanvas" data-bs-target="#contents" aria-label="Close table of contents"></button>
|
|
</div>
|
|
<ul class="offcanvas-md-body nav nav-pills flex-column">
|
|
<li class="nav-item" data-bs-dismiss="offcanvas" data-bs-target="#contents">
|
|
<a class="nav-link" href="#invoking-jq">Invoking jq</a>
|
|
</li>
|
|
<li class="nav-item" data-bs-dismiss="offcanvas" data-bs-target="#contents">
|
|
<a class="nav-link" href="#basic-filters">Basic filters</a>
|
|
</li>
|
|
<li class="nav-item" data-bs-dismiss="offcanvas" data-bs-target="#contents">
|
|
<a class="nav-link" href="#types-and-values">Types and Values</a>
|
|
</li>
|
|
<li class="nav-item" data-bs-dismiss="offcanvas" data-bs-target="#contents">
|
|
<a class="nav-link" href="#builtin-operators-and-functions">Builtin operators and functions</a>
|
|
</li>
|
|
<li class="nav-item" data-bs-dismiss="offcanvas" data-bs-target="#contents">
|
|
<a class="nav-link" href="#conditionals-and-comparisons">Conditionals and Comparisons</a>
|
|
</li>
|
|
<li class="nav-item" data-bs-dismiss="offcanvas" data-bs-target="#contents">
|
|
<a class="nav-link" href="#regular-expressions">Regular expressions</a>
|
|
</li>
|
|
<li class="nav-item" data-bs-dismiss="offcanvas" data-bs-target="#contents">
|
|
<a class="nav-link" href="#advanced-features">Advanced features</a>
|
|
</li>
|
|
<li class="nav-item" data-bs-dismiss="offcanvas" data-bs-target="#contents">
|
|
<a class="nav-link" href="#math">Math</a>
|
|
</li>
|
|
<li class="nav-item" data-bs-dismiss="offcanvas" data-bs-target="#contents">
|
|
<a class="nav-link" href="#io">I/O</a>
|
|
</li>
|
|
<li class="nav-item" data-bs-dismiss="offcanvas" data-bs-target="#contents">
|
|
<a class="nav-link" href="#streaming">Streaming</a>
|
|
</li>
|
|
<li class="nav-item" data-bs-dismiss="offcanvas" data-bs-target="#contents">
|
|
<a class="nav-link" href="#assignment">Assignment</a>
|
|
</li>
|
|
<li class="nav-item" data-bs-dismiss="offcanvas" data-bs-target="#contents">
|
|
<a class="nav-link" href="#modules">Modules</a>
|
|
</li>
|
|
<li class="nav-item" data-bs-dismiss="offcanvas" data-bs-target="#contents">
|
|
<a class="nav-link" href="#colors">Colors</a>
|
|
</li>
|
|
</ul>
|
|
</nav>
|
|
<main id="main" class="col-md-9" data-bs-spy="scroll" data-bs-target="#contents" data-bs-threshold="0,1" data-bs-root-margin="-30% 0% -70%">
|
|
<h1>jq 1.7 Manual</h1>
|
|
<p><em>The manual for the development version of jq can be found
|
|
<a href="../">here</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="invoking-jq">
|
|
<h2>Invoking jq <a href="#invoking-jq" class="icon-link" aria-label="Link to this section: Invoking jq"><span class="bi bi-link-45deg" aria-hidden="true"></span></a></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>The simplest and most common filter (or jq program) is <code>.</code>,
|
|
which is the identity operator, copying the inputs of the jq
|
|
processor to the output stream. Because the default behavior of
|
|
the jq processor is to read JSON texts from the input stream,
|
|
and to pretty-print outputs, the <code>.</code> program's main use is to
|
|
validate and pretty-print the inputs. The jq programming
|
|
language is quite rich and allows for much more than just
|
|
validation and pretty-printing.</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 on Unix shells) 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>Note: jq allows user-defined functions, but every jq program
|
|
must have a top-level expression.</p>
|
|
<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>--raw-output0</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.
|
|
When the output value contains NUL, jq exits with non-zero code.</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>--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>--build-configuration</code>:</li>
|
|
</ul>
|
|
<p>Output the build configuration of jq and exit with zero.
|
|
This output has no supported format or structure and may change
|
|
without notice in future releases.</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="basic-filters">
|
|
<h2>Basic filters <a href="#basic-filters" class="icon-link" aria-label="Link to this section: Basic filters"><span class="bi bi-link-45deg" aria-hidden="true"></span></a></h2>
|
|
|
|
<section id="identity">
|
|
<h3>
|
|
Identity: <code>.</code>
|
|
<a href="#identity" class="icon-link" aria-label="Link to this section: Identity: `.`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example1" aria-expanded="false" aria-controls="example1">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example1" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"Hello, world!"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"Hello, world!"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.&j=%22Hello%2C%20world%21%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">0.12345678901234567890123456789</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">0.12345678901234567890123456789</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.&j=0.12345678901234567890123456789" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[., tojson]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">12345678909876543212345</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[12345678909876543212345,"12345678909876543212345"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.%2C%20tojson%5D&j=12345678909876543212345" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '. < 0.12345678901234567890123456788'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">0.12345678901234567890123456789</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%20%3C%200.12345678901234567890123456788&j=0.12345678901234567890123456789" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'map([., . == 1]) | tojson'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1, 1.000, 1.0, 100e-2]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"[[1,true],[1.000,true],[1.0,true],[1.00,true]]"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=map%28%5B.%2C%20.%20%3D%3D%201%5D%29%20%7C%20tojson&j=%5B1%2C%201.000%2C%201.0%2C%20100e-2%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '. as $big | [$big, $big + 1] | map(. > 10000000000000000000000000000000)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">10000000000000000000000000000001</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[true, false]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%20as%20%24big%20%7C%20%5B%24big%2C%20%24big%20%2B%201%5D%20%7C%20map%28.%20%3E%2010000000000000000000000000000000%29&j=10000000000000000000000000000001" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="object-identifier-index">
|
|
<h3>
|
|
Object Identifier-Index: <code>.foo</code>, <code>.foo.bar</code>
|
|
<a href="#object-identifier-index" class="icon-link" aria-label="Link to this section: Object Identifier-Index: `.foo`, `.foo.bar`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example2" aria-expanded="false" aria-controls="example2">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example2" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.foo'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo": 42, "bar": "less interesting data"}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">42</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.foo&j=%7B%22foo%22%3A%2042%2C%20%22bar%22%3A%20%22less%20interesting%20data%22%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.foo'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"notfoo": true, "alsonotfoo": false}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.foo&j=%7B%22notfoo%22%3A%20true%2C%20%22alsonotfoo%22%3A%20false%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.["foo"]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo": 42}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">42</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%22foo%22%5D&j=%7B%22foo%22%3A%2042%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="optional-object-identifier-index">
|
|
<h3>
|
|
Optional Object Identifier-Index: <code>.foo?</code>
|
|
<a href="#optional-object-identifier-index" class="icon-link" aria-label="Link to this section: Optional Object Identifier-Index: `.foo?`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>Just like <code>.foo</code>, but does not output an error when <code>.</code> is not an
|
|
object.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example3" aria-expanded="false" aria-controls="example3">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example3" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.foo?'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo": 42, "bar": "less interesting data"}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">42</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.foo%3F&j=%7B%22foo%22%3A%2042%2C%20%22bar%22%3A%20%22less%20interesting%20data%22%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.foo?'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"notfoo": true, "alsonotfoo": false}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.foo%3F&j=%7B%22notfoo%22%3A%20true%2C%20%22alsonotfoo%22%3A%20false%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.["foo"]?'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo": 42}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">42</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%22foo%22%5D%3F&j=%7B%22foo%22%3A%2042%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[.foo?]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,2]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.foo%3F%5D&j=%5B1%2C2%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="object-index">
|
|
<h3>
|
|
Object Index: <code>.[<string>]</code>
|
|
<a href="#object-index" class="icon-link" aria-label="Link to this section: Object Index: `.[<string>]`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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="array-index">
|
|
<h3>
|
|
Array Index: <code>.[<number>]</code>
|
|
<a href="#array-index" class="icon-link" aria-label="Link to this section: Array Index: `.[<number>]`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example4" aria-expanded="false" aria-controls="example4">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example4" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[0]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"name":"JSON", "good":true}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B0%5D&j=%5B%7B%22name%22%3A%22JSON%22%2C%20%22good%22%3Atrue%7D%2C%20%7B%22name%22%3A%22XML%22%2C%20%22good%22%3Afalse%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[2]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B2%5D&j=%5B%7B%22name%22%3A%22JSON%22%2C%20%22good%22%3Atrue%7D%2C%20%7B%22name%22%3A%22XML%22%2C%20%22good%22%3Afalse%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[-2]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,2,3]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">2</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B-2%5D&j=%5B1%2C2%2C3%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="array-string-slice">
|
|
<h3>
|
|
Array/String Slice: <code>.[<number>:<number>]</code>
|
|
<a href="#array-string-slice" class="icon-link" aria-label="Link to this section: Array/String Slice: `.[<number>:<number>]`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example5" aria-expanded="false" aria-controls="example5">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example5" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[2:4]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["a","b","c","d","e"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["c", "d"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B2%3A4%5D&j=%5B%22a%22%2C%22b%22%2C%22c%22%2C%22d%22%2C%22e%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[2:4]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"abcdefghi"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"cd"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B2%3A4%5D&j=%22abcdefghi%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[:3]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["a","b","c","d","e"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["a", "b", "c"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%3A3%5D&j=%5B%22a%22%2C%22b%22%2C%22c%22%2C%22d%22%2C%22e%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[-2:]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["a","b","c","d","e"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["d", "e"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B-2%3A%5D&j=%5B%22a%22%2C%22b%22%2C%22c%22%2C%22d%22%2C%22e%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="array-object-value-iterator">
|
|
<h3>
|
|
Array/Object Value Iterator: <code>.[]</code>
|
|
<a href="#array-object-value-iterator" class="icon-link" aria-label="Link to this section: Array/Object Value Iterator: `.[]`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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>
|
|
<p>Note that the iterator operator is a generator of values.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example6" aria-expanded="false" aria-controls="example6">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example6" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"name":"JSON", "good":true}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"name":"XML", "good":false}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D&j=%5B%7B%22name%22%3A%22JSON%22%2C%20%22good%22%3Atrue%7D%2C%20%7B%22name%22%3A%22XML%22%2C%20%22good%22%3Afalse%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="fst-italic">none</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D&j=%5B%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.foo[]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo":[1,2,3]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">2</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">3</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.foo%5B%5D&j=%7B%22foo%22%3A%5B1%2C2%2C3%5D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a": 1, "b": 1}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D&j=%7B%22a%22%3A%201%2C%20%22b%22%3A%201%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id=".[]?">
|
|
<h3>
|
|
<code>.[]?</code>
|
|
<a href="#.[]?" class="icon-link" aria-label="Link to this section: `.[]?`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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>
|
|
<a href="#comma" class="icon-link" aria-label="Link to this section: Comma: `,`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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>
|
|
<p>The <code>,</code> operator is one way to construct generators.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example7" aria-expanded="false" aria-controls="example7">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example7" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.foo, .bar'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo": 42, "bar": "something else", "baz": true}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">42</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">"something else"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.foo%2C%20.bar&j=%7B%22foo%22%3A%2042%2C%20%22bar%22%3A%20%22something%20else%22%2C%20%22baz%22%3A%20true%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.user, .projects[]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"user":"stedolan", "projects": ["jq", "wikiflow"]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"stedolan"</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">"jq"</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">"wikiflow"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.user%2C%20.projects%5B%5D&j=%7B%22user%22%3A%22stedolan%22%2C%20%22projects%22%3A%20%5B%22jq%22%2C%20%22wikiflow%22%5D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[4,2]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["a","b","c","d","e"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"e"</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">"c"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B4%2C2%5D&j=%5B%22a%22%2C%22b%22%2C%22c%22%2C%22d%22%2C%22e%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="pipe">
|
|
<h3>
|
|
Pipe: <code>|</code>
|
|
<a href="#pipe" class="icon-link" aria-label="Link to this section: Pipe: `|`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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
|
|
similar to 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. This is a cartesian product,
|
|
which can be surprising.</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example8" aria-expanded="false" aria-controls="example8">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example8" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] | .name'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"JSON"</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">"XML"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20%7C%20.name&j=%5B%7B%22name%22%3A%22JSON%22%2C%20%22good%22%3Atrue%7D%2C%20%7B%22name%22%3A%22XML%22%2C%20%22good%22%3Afalse%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="parenthesis">
|
|
<h3>
|
|
Parenthesis
|
|
<a href="#parenthesis" class="icon-link" aria-label="Link to this section: Parenthesis"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>Parenthesis work as a grouping operator just as in any typical
|
|
programming language.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example9" aria-expanded="false" aria-controls="example9">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example9" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '(. + 2) * 5'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">15</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%28.%20%2B%202%29%20%2A%205&j=1" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
</section>
|
|
<section id="types-and-values">
|
|
<h2>Types and Values <a href="#types-and-values" class="icon-link" aria-label="Link to this section: Types and Values"><span class="bi bi-link-45deg" aria-hidden="true"></span></a></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="array-construction">
|
|
<h3>
|
|
Array construction: <code>[]</code>
|
|
<a href="#array-construction" class="icon-link" aria-label="Link to this section: Array construction: `[]`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example10" aria-expanded="false" aria-controls="example10">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example10" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[.user, .projects[]]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"user":"stedolan", "projects": ["jq", "wikiflow"]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["stedolan", "jq", "wikiflow"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.user%2C%20.projects%5B%5D%5D&j=%7B%22user%22%3A%22stedolan%22%2C%20%22projects%22%3A%20%5B%22jq%22%2C%20%22wikiflow%22%5D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[ .[] | . * 2]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1, 2, 3]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[2, 4, 6]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B%20.%5B%5D%20%7C%20.%20%2A%202%5D&j=%5B1%2C%202%2C%203%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="object-construction">
|
|
<h3>
|
|
Object Construction: <code>{}</code>
|
|
<a href="#object-construction" class="icon-link" aria-label="Link to this section: Object Construction: `{}`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example11" aria-expanded="false" aria-controls="example11">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example11" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '{user, title: .titles[]}'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"user":"stedolan","titles":["JQ Primer", "More JQ"]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"user":"stedolan", "title": "JQ Primer"}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"user":"stedolan", "title": "More JQ"}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%7Buser%2C%20title%3A%20.titles%5B%5D%7D&j=%7B%22user%22%3A%22stedolan%22%2C%22titles%22%3A%5B%22JQ%20Primer%22%2C%20%22More%20JQ%22%5D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '{(.user): .titles}'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"user":"stedolan","titles":["JQ Primer", "More JQ"]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"stedolan": ["JQ Primer", "More JQ"]}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%7B%28.user%29%3A%20.titles%7D&j=%7B%22user%22%3A%22stedolan%22%2C%22titles%22%3A%5B%22JQ%20Primer%22%2C%20%22More%20JQ%22%5D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="recursive-descent">
|
|
<h3>
|
|
Recursive Descent: <code>..</code>
|
|
<a href="#recursive-descent" class="icon-link" aria-label="Link to this section: Recursive Descent: `..`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example12" aria-expanded="false" aria-controls="example12">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example12" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.. | .a?'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[[{"a":1}]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=..%20%7C%20.a%3F&j=%5B%5B%7B%22a%22%3A1%7D%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
</section>
|
|
<section id="builtin-operators-and-functions">
|
|
<h2>Builtin operators and functions <a href="#builtin-operators-and-functions" class="icon-link" aria-label="Link to this section: Builtin operators and functions"><span class="bi bi-link-45deg" aria-hidden="true"></span></a></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>
|
|
<a href="#addition" class="icon-link" aria-label="Link to this section: Addition: `+`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example13" aria-expanded="false" aria-controls="example13">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example13" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.a + 1'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a": 7}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">8</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.a%20%2B%201&j=%7B%22a%22%3A%207%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.a + .b'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a": [1,2], "b": [3,4]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1,2,3,4]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.a%20%2B%20.b&j=%7B%22a%22%3A%20%5B1%2C2%5D%2C%20%22b%22%3A%20%5B3%2C4%5D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.a + null'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a": 1}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.a%20%2B%20null&j=%7B%22a%22%3A%201%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.a + 1'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.a%20%2B%201&j=%7B%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '{a: 1} + {b: 2} + {c: 3} + {a: 42}'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a": 42, "b": 2, "c": 3}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%7Ba%3A%201%7D%20%2B%20%7Bb%3A%202%7D%20%2B%20%7Bc%3A%203%7D%20%2B%20%7Ba%3A%2042%7D&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="subtraction">
|
|
<h3>
|
|
Subtraction: <code>-</code>
|
|
<a href="#subtraction" class="icon-link" aria-label="Link to this section: Subtraction: `-`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example14" aria-expanded="false" aria-controls="example14">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example14" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '4 - .a'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a":3}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=4%20-%20.a&j=%7B%22a%22%3A3%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '. - ["xml", "yaml"]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["xml", "yaml", "json"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["json"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%20-%20%5B%22xml%22%2C%20%22yaml%22%5D&j=%5B%22xml%22%2C%20%22yaml%22%2C%20%22json%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="multiplication-division-modulo">
|
|
<h3>
|
|
Multiplication, division, modulo: <code>*</code>, <code>/</code>, <code>%</code>
|
|
<a href="#multiplication-division-modulo" class="icon-link" aria-label="Link to this section: Multiplication, division, modulo: `*`, `/`, `%`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example15" aria-expanded="false" aria-controls="example15">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example15" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '10 / . * 3'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">5</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">6</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=10%20/%20.%20%2A%203&j=5" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '. / ", "'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"a, b,c,d, e"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["a","b,c,d","e"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%20/%20%22%2C%20%22&j=%22a%2C%20b%2Cc%2Cd%2C%20e%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '{"k": {"a": 1, "b": 2}} * {"k": {"a": 0,"c": 3}}'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"k": {"a": 0, "b": 2, "c": 3}}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%7B%22k%22%3A%20%7B%22a%22%3A%201%2C%20%22b%22%3A%202%7D%7D%20%2A%20%7B%22k%22%3A%20%7B%22a%22%3A%200%2C%22c%22%3A%203%7D%7D&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] | (1 / .)?'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,0,-1]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">-1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20%7C%20%281%20/%20.%29%3F&j=%5B1%2C0%2C-1%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="abs">
|
|
<h3>
|
|
<code>abs</code>
|
|
<a href="#abs" class="icon-link" aria-label="Link to this section: `abs`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>The builtin function <code>abs</code> is defined naively as: <code>if . < 0 then - . else . end</code>.</p>
|
|
<p>For numeric input, this is the absolute value. See the
|
|
section on the identity filter for the implications of this
|
|
definition for numeric input.</p>
|
|
<p>To compute the absolute value of a number as a floating point number, you may wish use <code>fabs</code>.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example16" aria-expanded="false" aria-controls="example16">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example16" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'map(abs)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[-10, -1.1, -1e-1]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[10,1.1,1e-1]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=map%28abs%29&j=%5B-10%2C%20-1.1%2C%20-1e-1%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="length">
|
|
<h3>
|
|
<code>length</code>
|
|
<a href="#length" class="icon-link" aria-label="Link to this section: `length`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example17" aria-expanded="false" aria-controls="example17">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example17" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] | length'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[[1,2], "string", {"a":2}, null, -5]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">2</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">6</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">0</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">5</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20%7C%20length&j=%5B%5B1%2C2%5D%2C%20%22string%22%2C%20%7B%22a%22%3A2%7D%2C%20null%2C%20-5%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="utf8bytelength">
|
|
<h3>
|
|
<code>utf8bytelength</code>
|
|
<a href="#utf8bytelength" class="icon-link" aria-label="Link to this section: `utf8bytelength`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>The builtin function <code>utf8bytelength</code> outputs the number of
|
|
bytes used to encode a string in UTF-8.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example18" aria-expanded="false" aria-controls="example18">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example18" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'utf8bytelength'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"\u03bc"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">2</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=utf8bytelength&j=%22%5Cu03bc%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="keys-keys_unsorted">
|
|
<h3>
|
|
<code>keys</code>, <code>keys_unsorted</code>
|
|
<a href="#keys-keys_unsorted" class="icon-link" aria-label="Link to this section: `keys`, `keys_unsorted`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example19" aria-expanded="false" aria-controls="example19">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example19" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'keys'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"abc": 1, "abcd": 2, "Foo": 3}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["Foo", "abc", "abcd"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=keys&j=%7B%22abc%22%3A%201%2C%20%22abcd%22%3A%202%2C%20%22Foo%22%3A%203%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'keys'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[42,3,35]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[0,1,2]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=keys&j=%5B42%2C3%2C35%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="has">
|
|
<h3>
|
|
<code>has(key)</code>
|
|
<a href="#has" class="icon-link" aria-label="Link to this section: `has(key)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example20" aria-expanded="false" aria-controls="example20">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example20" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'map(has("foo"))'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"foo": 42}, {}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[true, false]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=map%28has%28%22foo%22%29%29&j=%5B%7B%22foo%22%3A%2042%7D%2C%20%7B%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'map(has(2))'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[[0,1], ["a","b","c"]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[false, true]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=map%28has%282%29%29&j=%5B%5B0%2C1%5D%2C%20%5B%22a%22%2C%22b%22%2C%22c%22%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="in">
|
|
<h3>
|
|
<code>in</code>
|
|
<a href="#in" class="icon-link" aria-label="Link to this section: `in`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example21" aria-expanded="false" aria-controls="example21">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example21" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] | in({"foo": 42})'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["foo", "bar"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20%7C%20in%28%7B%22foo%22%3A%2042%7D%29&j=%5B%22foo%22%2C%20%22bar%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'map(in([0,1]))'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[2, 0]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[false, true]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=map%28in%28%5B0%2C1%5D%29%29&j=%5B2%2C%200%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="map-map_values">
|
|
<h3>
|
|
<code>map(f)</code>, <code>map_values(f)</code>
|
|
<a href="#map-map_values" class="icon-link" aria-label="Link to this section: `map(f)`, `map_values(f)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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_values(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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example22" aria-expanded="false" aria-controls="example22">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example22" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'map(.+1)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,2,3]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[2,3,4]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=map%28.%2B1%29&j=%5B1%2C2%2C3%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'map_values(.+1)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a": 1, "b": 2, "c": 3}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a": 2, "b": 3, "c": 4}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=map_values%28.%2B1%29&j=%7B%22a%22%3A%201%2C%20%22b%22%3A%202%2C%20%22c%22%3A%203%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'map(., .)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,2]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1,1,2,2]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=map%28.%2C%20.%29&j=%5B1%2C2%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'map_values(. // empty)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a": null, "b": true, "c": false}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"b":true}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=map_values%28.%20//%20empty%29&j=%7B%22a%22%3A%20null%2C%20%22b%22%3A%20true%2C%20%22c%22%3A%20false%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="pick">
|
|
<h3>
|
|
<code>pick(pathexps)</code>
|
|
<a href="#pick" class="icon-link" aria-label="Link to this section: `pick(pathexps)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>Emit the projection of the input object or array defined by the
|
|
specified sequence of path expressions, such that if <code>p</code> 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 <code>.[m:n]</code> specifications should not be used.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example23" aria-expanded="false" aria-controls="example23">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example23" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'pick(.a, .b.c, .x)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a": 1, "b": {"c": 2, "d": 3}, "e": 4}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a":1,"b":{"c":2},"x":null}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=pick%28.a%2C%20.b.c%2C%20.x%29&j=%7B%22a%22%3A%201%2C%20%22b%22%3A%20%7B%22c%22%3A%202%2C%20%22d%22%3A%203%7D%2C%20%22e%22%3A%204%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'pick(.[2], .[0], .[0])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,2,3,4]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1,null,3]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=pick%28.%5B2%5D%2C%20.%5B0%5D%2C%20.%5B0%5D%29&j=%5B1%2C2%2C3%2C4%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="path">
|
|
<h3>
|
|
<code>path(path_expression)</code>
|
|
<a href="#path" class="icon-link" aria-label="Link to this section: `path(path_expression)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example24" aria-expanded="false" aria-controls="example24">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example24" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'path(.a[0].b)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["a",0,"b"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=path%28.a%5B0%5D.b%29&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[path(..)]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a":[{"b":1}]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[[],["a"],["a",0],["a",0,"b"]]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Bpath%28..%29%5D&j=%7B%22a%22%3A%5B%7B%22b%22%3A1%7D%5D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="del">
|
|
<h3>
|
|
<code>del(path_expression)</code>
|
|
<a href="#del" class="icon-link" aria-label="Link to this section: `del(path_expression)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>The builtin function <code>del</code> removes a key and its corresponding
|
|
value from an object.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example25" aria-expanded="false" aria-controls="example25">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example25" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'del(.foo)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo": 42, "bar": 9001, "baz": 42}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"bar": 9001, "baz": 42}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=del%28.foo%29&j=%7B%22foo%22%3A%2042%2C%20%22bar%22%3A%209001%2C%20%22baz%22%3A%2042%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'del(.[1, 2])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["foo", "bar", "baz"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["foo"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=del%28.%5B1%2C%202%5D%29&j=%5B%22foo%22%2C%20%22bar%22%2C%20%22baz%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="getpath">
|
|
<h3>
|
|
<code>getpath(PATHS)</code>
|
|
<a href="#getpath" class="icon-link" aria-label="Link to this section: `getpath(PATHS)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>The builtin function <code>getpath</code> outputs the values in <code>.</code> found
|
|
at each path in <code>PATHS</code>.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example26" aria-expanded="false" aria-controls="example26">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example26" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'getpath(["a","b"])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=getpath%28%5B%22a%22%2C%22b%22%5D%29&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[getpath(["a","b"], ["a","c"])]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a":{"b":0, "c":1}}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[0, 1]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Bgetpath%28%5B%22a%22%2C%22b%22%5D%2C%20%5B%22a%22%2C%22c%22%5D%29%5D&j=%7B%22a%22%3A%7B%22b%22%3A0%2C%20%22c%22%3A1%7D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="setpath">
|
|
<h3>
|
|
<code>setpath(PATHS; VALUE)</code>
|
|
<a href="#setpath" class="icon-link" aria-label="Link to this section: `setpath(PATHS; VALUE)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>The builtin function <code>setpath</code> sets the <code>PATHS</code> in <code>.</code> to <code>VALUE</code>.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example27" aria-expanded="false" aria-controls="example27">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example27" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'setpath(["a","b"]; 1)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a": {"b": 1}}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=setpath%28%5B%22a%22%2C%22b%22%5D%3B%201%29&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'setpath(["a","b"]; 1)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a":{"b":0}}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a": {"b": 1}}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=setpath%28%5B%22a%22%2C%22b%22%5D%3B%201%29&j=%7B%22a%22%3A%7B%22b%22%3A0%7D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'setpath([0,"a"]; 1)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[{"a":1}]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=setpath%28%5B0%2C%22a%22%5D%3B%201%29&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="delpaths">
|
|
<h3>
|
|
<code>delpaths(PATHS)</code>
|
|
<a href="#delpaths" class="icon-link" aria-label="Link to this section: `delpaths(PATHS)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>The builtin function <code>delpaths</code> deletes 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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example28" aria-expanded="false" aria-controls="example28">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example28" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'delpaths([["a","b"]])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a":{"b":1},"x":{"y":2}}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a":{},"x":{"y":2}}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=delpaths%28%5B%5B%22a%22%2C%22b%22%5D%5D%29&j=%7B%22a%22%3A%7B%22b%22%3A1%7D%2C%22x%22%3A%7B%22y%22%3A2%7D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="to_entries-from_entries-with_entries">
|
|
<h3>
|
|
<code>to_entries</code>, <code>from_entries</code>, <code>with_entries(f)</code>
|
|
<a href="#to_entries-from_entries-with_entries" class="icon-link" aria-label="Link to this section: `to_entries`, `from_entries`, `with_entries(f)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example29" aria-expanded="false" aria-controls="example29">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example29" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'to_entries'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a": 1, "b": 2}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[{"key":"a", "value":1}, {"key":"b", "value":2}]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=to_entries&j=%7B%22a%22%3A%201%2C%20%22b%22%3A%202%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'from_entries'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"key":"a", "value":1}, {"key":"b", "value":2}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a": 1, "b": 2}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=from_entries&j=%5B%7B%22key%22%3A%22a%22%2C%20%22value%22%3A1%7D%2C%20%7B%22key%22%3A%22b%22%2C%20%22value%22%3A2%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'with_entries(.key |= "KEY_" + .)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a": 1, "b": 2}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"KEY_a": 1, "KEY_b": 2}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=with_entries%28.key%20%7C%3D%20%22KEY_%22%20%2B%20.%29&j=%7B%22a%22%3A%201%2C%20%22b%22%3A%202%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="select">
|
|
<h3>
|
|
<code>select(boolean_expression)</code>
|
|
<a href="#select" class="icon-link" aria-label="Link to this section: `select(boolean_expression)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example30" aria-expanded="false" aria-controls="example30">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example30" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'map(select(. >= 2))'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,5,3,0,7]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[5,3,7]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=map%28select%28.%20%3E%3D%202%29%29&j=%5B1%2C5%2C3%2C0%2C7%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] | select(.id == "second")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"id": "first", "val": 1}, {"id": "second", "val": 2}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"id": "second", "val": 2}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20%7C%20select%28.id%20%3D%3D%20%22second%22%29&j=%5B%7B%22id%22%3A%20%22first%22%2C%20%22val%22%3A%201%7D%2C%20%7B%22id%22%3A%20%22second%22%2C%20%22val%22%3A%202%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></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>
|
|
<a href="#arrays-objects-iterables-booleans-numbers-normals-finites-strings-nulls-values-scalars" class="icon-link" aria-label="Link to this section: `arrays`, `objects`, `iterables`, `booleans`, `numbers`, `normals`, `finites`, `strings`, `nulls`, `values`, `scalars`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example31" aria-expanded="false" aria-controls="example31">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example31" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[]|numbers'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[[],{},1,"foo",null,true,false]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%7Cnumbers&j=%5B%5B%5D%2C%7B%7D%2C1%2C%22foo%22%2Cnull%2Ctrue%2Cfalse%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="empty">
|
|
<h3>
|
|
<code>empty</code>
|
|
<a href="#empty" class="icon-link" aria-label="Link to this section: `empty`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example32" aria-expanded="false" aria-controls="example32">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example32" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '1, empty, 2'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">2</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=1%2C%20empty%2C%202&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[1,2,empty,3]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1,2,3]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B1%2C2%2Cempty%2C3%5D&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="error">
|
|
<h3>
|
|
<code>error</code>, <code>error(message)</code>
|
|
<a href="#error" class="icon-link" aria-label="Link to this section: `error`, `error(message)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example33" aria-expanded="false" aria-controls="example33">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example33" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'try error catch .'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"error message"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"error message"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=try%20error%20catch%20.&j=%22error%20message%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'try error("invalid value: \(.)") catch .'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">42</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"invalid value: 42"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=try%20error%28%22invalid%20value%3A%20%5C%28.%29%22%29%20catch%20.&j=42" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="halt">
|
|
<h3>
|
|
<code>halt</code>
|
|
<a href="#halt" class="icon-link" aria-label="Link to this section: `halt`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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">
|
|
<h3>
|
|
<code>halt_error</code>, <code>halt_error(exit_code)</code>
|
|
<a href="#halt_error" class="icon-link" aria-label="Link to this section: `halt_error`, `halt_error(exit_code)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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>
|
|
<a href="#$__loc__" class="icon-link" aria-label="Link to this section: `$__loc__`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example34" aria-expanded="false" aria-controls="example34">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example34" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'try error("\($__loc__)") catch .'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"{\"file\":\"<top-level>\",\"line\":1}"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=try%20error%28%22%5C%28%24__loc__%29%22%29%20catch%20.&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="paths">
|
|
<h3>
|
|
<code>paths</code>, <code>paths(node_filter)</code>
|
|
<a href="#paths" class="icon-link" aria-label="Link to this section: `paths`, `paths(node_filter)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example35" aria-expanded="false" aria-controls="example35">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example35" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[paths]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,[[],{"a":2}]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[[0],[1],[1,0],[1,1],[1,1,"a"]]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Bpaths%5D&j=%5B1%2C%5B%5B%5D%2C%7B%22a%22%3A2%7D%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[paths(type == "number")]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,[[],{"a":2}]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[[0],[1,1,"a"]]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Bpaths%28type%20%3D%3D%20%22number%22%29%5D&j=%5B1%2C%5B%5B%5D%2C%7B%22a%22%3A2%7D%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="add">
|
|
<h3>
|
|
<code>add</code>
|
|
<a href="#add" class="icon-link" aria-label="Link to this section: `add`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example36" aria-expanded="false" aria-controls="example36">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example36" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'add'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["a","b","c"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"abc"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=add&j=%5B%22a%22%2C%22b%22%2C%22c%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'add'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1, 2, 3]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">6</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=add&j=%5B1%2C%202%2C%203%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'add'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=add&j=%5B%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="any">
|
|
<h3>
|
|
<code>any</code>, <code>any(condition)</code>, <code>any(generator; condition)</code>
|
|
<a href="#any" class="icon-link" aria-label="Link to this section: `any`, `any(condition)`, `any(generator; condition)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example37" aria-expanded="false" aria-controls="example37">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example37" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'any'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[true, false]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=any&j=%5Btrue%2C%20false%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'any'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[false, false]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=any&j=%5Bfalse%2C%20false%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'any'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=any&j=%5B%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="all">
|
|
<h3>
|
|
<code>all</code>, <code>all(condition)</code>, <code>all(generator; condition)</code>
|
|
<a href="#all" class="icon-link" aria-label="Link to this section: `all`, `all(condition)`, `all(generator; condition)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example38" aria-expanded="false" aria-controls="example38">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example38" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'all'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[true, false]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=all&j=%5Btrue%2C%20false%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'all'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[true, true]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=all&j=%5Btrue%2C%20true%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'all'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=all&j=%5B%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="flatten">
|
|
<h3>
|
|
<code>flatten</code>, <code>flatten(depth)</code>
|
|
<a href="#flatten" class="icon-link" aria-label="Link to this section: `flatten`, `flatten(depth)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example39" aria-expanded="false" aria-controls="example39">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example39" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'flatten'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1, [2], [[3]]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1, 2, 3]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=flatten&j=%5B1%2C%20%5B2%5D%2C%20%5B%5B3%5D%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'flatten(1)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1, [2], [[3]]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1, 2, [3]]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=flatten%281%29&j=%5B1%2C%20%5B2%5D%2C%20%5B%5B3%5D%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'flatten'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[[]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=flatten&j=%5B%5B%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'flatten'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"foo": "bar"}, [{"foo": "baz"}]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[{"foo": "bar"}, {"foo": "baz"}]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=flatten&j=%5B%7B%22foo%22%3A%20%22bar%22%7D%2C%20%5B%7B%22foo%22%3A%20%22baz%22%7D%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="range">
|
|
<h3>
|
|
<code>range(upto)</code>, <code>range(from; upto)</code>, <code>range(from; upto; by)</code>
|
|
<a href="#range" class="icon-link" aria-label="Link to this section: `range(upto)`, `range(from; upto)`, `range(from; upto; by)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example40" aria-expanded="false" aria-controls="example40">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example40" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'range(2; 4)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">2</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">3</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=range%282%3B%204%29&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[range(2; 4)]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[2,3]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Brange%282%3B%204%29%5D&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[range(4)]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[0,1,2,3]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Brange%284%29%5D&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[range(0; 10; 3)]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[0,3,6,9]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Brange%280%3B%2010%3B%203%29%5D&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[range(0; 10; -1)]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Brange%280%3B%2010%3B%20-1%29%5D&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[range(0; -5; -1)]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[0,-1,-2,-3,-4]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Brange%280%3B%20-5%3B%20-1%29%5D&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="floor">
|
|
<h3>
|
|
<code>floor</code>
|
|
<a href="#floor" class="icon-link" aria-label="Link to this section: `floor`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>The <code>floor</code> function returns the floor of its numeric input.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example41" aria-expanded="false" aria-controls="example41">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example41" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'floor'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">3.14159</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">3</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=floor&j=3.14159" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="sqrt">
|
|
<h3>
|
|
<code>sqrt</code>
|
|
<a href="#sqrt" class="icon-link" aria-label="Link to this section: `sqrt`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>The <code>sqrt</code> function returns the square root of its numeric input.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example42" aria-expanded="false" aria-controls="example42">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example42" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'sqrt'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">9</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">3</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=sqrt&j=9" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="tonumber">
|
|
<h3>
|
|
<code>tonumber</code>
|
|
<a href="#tonumber" class="icon-link" aria-label="Link to this section: `tonumber`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example43" aria-expanded="false" aria-controls="example43">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example43" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] | tonumber'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1, "1"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20%7C%20tonumber&j=%5B1%2C%20%221%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="tostring">
|
|
<h3>
|
|
<code>tostring</code>
|
|
<a href="#tostring" class="icon-link" aria-label="Link to this section: `tostring`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example44" aria-expanded="false" aria-controls="example44">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example44" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] | tostring'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1, "1", [1]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"1"</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">"1"</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">"[1]"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20%7C%20tostring&j=%5B1%2C%20%221%22%2C%20%5B1%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="type">
|
|
<h3>
|
|
<code>type</code>
|
|
<a href="#type" class="icon-link" aria-label="Link to this section: `type`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example45" aria-expanded="false" aria-controls="example45">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example45" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'map(type)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[0, false, [], {}, null, "hello"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["number", "boolean", "array", "object", "null", "string"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=map%28type%29&j=%5B0%2C%20false%2C%20%5B%5D%2C%20%7B%7D%2C%20null%2C%20%22hello%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></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>
|
|
<a href="#infinite-nan-isinfinite-isnan-isfinite-isnormal" class="icon-link" aria-label="Link to this section: `infinite`, `nan`, `isinfinite`, `isnan`, `isfinite`, `isnormal`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example46" aria-expanded="false" aria-controls="example46">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example46" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] | (infinite * .) < 0'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[-1, 1]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20%7C%20%28infinite%20%2A%20.%29%20%3C%200&j=%5B-1%2C%201%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'infinite, nan | type'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"number"</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">"number"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=infinite%2C%20nan%20%7C%20type&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="sort-sort_by">
|
|
<h3>
|
|
<code>sort</code>, <code>sort_by(path_expression)</code>
|
|
<a href="#sort-sort_by" class="icon-link" aria-label="Link to this section: `sort`, `sort_by(path_expression)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example47" aria-expanded="false" aria-controls="example47">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example47" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'sort'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[8,3,null,6]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[null,3,6,8]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=sort&j=%5B8%2C3%2Cnull%2C6%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'sort_by(.foo)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"foo":4, "bar":10}, {"foo":3, "bar":10}, {"foo":2, "bar":1}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[{"foo":2, "bar":1}, {"foo":3, "bar":10}, {"foo":4, "bar":10}]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=sort_by%28.foo%29&j=%5B%7B%22foo%22%3A4%2C%20%22bar%22%3A10%7D%2C%20%7B%22foo%22%3A3%2C%20%22bar%22%3A10%7D%2C%20%7B%22foo%22%3A2%2C%20%22bar%22%3A1%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'sort_by(.foo, .bar)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"foo":4, "bar":10}, {"foo":3, "bar":20}, {"foo":2, "bar":1}, {"foo":3, "bar":10}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[{"foo":2, "bar":1}, {"foo":3, "bar":10}, {"foo":3, "bar":20}, {"foo":4, "bar":10}]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=sort_by%28.foo%2C%20.bar%29&j=%5B%7B%22foo%22%3A4%2C%20%22bar%22%3A10%7D%2C%20%7B%22foo%22%3A3%2C%20%22bar%22%3A20%7D%2C%20%7B%22foo%22%3A2%2C%20%22bar%22%3A1%7D%2C%20%7B%22foo%22%3A3%2C%20%22bar%22%3A10%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="group_by">
|
|
<h3>
|
|
<code>group_by(path_expression)</code>
|
|
<a href="#group_by" class="icon-link" aria-label="Link to this section: `group_by(path_expression)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example48" aria-expanded="false" aria-controls="example48">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example48" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'group_by(.foo)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"foo":1, "bar":10}, {"foo":3, "bar":100}, {"foo":1, "bar":1}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[[{"foo":1, "bar":10}, {"foo":1, "bar":1}], [{"foo":3, "bar":100}]]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=group_by%28.foo%29&j=%5B%7B%22foo%22%3A1%2C%20%22bar%22%3A10%7D%2C%20%7B%22foo%22%3A3%2C%20%22bar%22%3A100%7D%2C%20%7B%22foo%22%3A1%2C%20%22bar%22%3A1%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="min-max-min_by-max_by">
|
|
<h3>
|
|
<code>min</code>, <code>max</code>, <code>min_by(path_exp)</code>, <code>max_by(path_exp)</code>
|
|
<a href="#min-max-min_by-max_by" class="icon-link" aria-label="Link to this section: `min`, `max`, `min_by(path_exp)`, `max_by(path_exp)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example49" aria-expanded="false" aria-controls="example49">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example49" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'min'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[5,4,2,7]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">2</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=min&j=%5B5%2C4%2C2%2C7%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'max_by(.foo)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"foo":1, "bar":14}, {"foo":2, "bar":3}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"foo":2, "bar":3}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=max_by%28.foo%29&j=%5B%7B%22foo%22%3A1%2C%20%22bar%22%3A14%7D%2C%20%7B%22foo%22%3A2%2C%20%22bar%22%3A3%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="unique-unique_by">
|
|
<h3>
|
|
<code>unique</code>, <code>unique_by(path_exp)</code>
|
|
<a href="#unique-unique_by" class="icon-link" aria-label="Link to this section: `unique`, `unique_by(path_exp)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example50" aria-expanded="false" aria-controls="example50">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example50" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'unique'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,2,5,3,5,3,1,3]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1,2,3,5]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=unique&j=%5B1%2C2%2C5%2C3%2C5%2C3%2C1%2C3%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'unique_by(.foo)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"foo": 1, "bar": 2}, {"foo": 1, "bar": 3}, {"foo": 4, "bar": 5}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[{"foo": 1, "bar": 2}, {"foo": 4, "bar": 5}]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=unique_by%28.foo%29&j=%5B%7B%22foo%22%3A%201%2C%20%22bar%22%3A%202%7D%2C%20%7B%22foo%22%3A%201%2C%20%22bar%22%3A%203%7D%2C%20%7B%22foo%22%3A%204%2C%20%22bar%22%3A%205%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'unique_by(length)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["chunky", "bacon", "kitten", "cicada", "asparagus"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["bacon", "chunky", "asparagus"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=unique_by%28length%29&j=%5B%22chunky%22%2C%20%22bacon%22%2C%20%22kitten%22%2C%20%22cicada%22%2C%20%22asparagus%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="reverse">
|
|
<h3>
|
|
<code>reverse</code>
|
|
<a href="#reverse" class="icon-link" aria-label="Link to this section: `reverse`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>This function reverses an array.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example51" aria-expanded="false" aria-controls="example51">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example51" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'reverse'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,2,3,4]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[4,3,2,1]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=reverse&j=%5B1%2C2%2C3%2C4%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="contains">
|
|
<h3>
|
|
<code>contains(element)</code>
|
|
<a href="#contains" class="icon-link" aria-label="Link to this section: `contains(element)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example52" aria-expanded="false" aria-controls="example52">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example52" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'contains("bar")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"foobar"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=contains%28%22bar%22%29&j=%22foobar%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'contains(["baz", "bar"])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["foobar", "foobaz", "blarp"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=contains%28%5B%22baz%22%2C%20%22bar%22%5D%29&j=%5B%22foobar%22%2C%20%22foobaz%22%2C%20%22blarp%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'contains(["bazzzzz", "bar"])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["foobar", "foobaz", "blarp"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=contains%28%5B%22bazzzzz%22%2C%20%22bar%22%5D%29&j=%5B%22foobar%22%2C%20%22foobaz%22%2C%20%22blarp%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'contains({foo: 12, bar: [{barp: 12}]})'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=contains%28%7Bfoo%3A%2012%2C%20bar%3A%20%5B%7Bbarp%3A%2012%7D%5D%7D%29&j=%7B%22foo%22%3A%2012%2C%20%22bar%22%3A%5B1%2C2%2C%7B%22barp%22%3A12%2C%20%22blip%22%3A13%7D%5D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'contains({foo: 12, bar: [{barp: 15}]})'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=contains%28%7Bfoo%3A%2012%2C%20bar%3A%20%5B%7Bbarp%3A%2015%7D%5D%7D%29&j=%7B%22foo%22%3A%2012%2C%20%22bar%22%3A%5B1%2C2%2C%7B%22barp%22%3A12%2C%20%22blip%22%3A13%7D%5D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="indices">
|
|
<h3>
|
|
<code>indices(s)</code>
|
|
<a href="#indices" class="icon-link" aria-label="Link to this section: `indices(s)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example53" aria-expanded="false" aria-controls="example53">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example53" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'indices(", ")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"a,b, cd, efg, hijk"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[3,7,12]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=indices%28%22%2C%20%22%29&j=%22a%2Cb%2C%20cd%2C%20efg%2C%20hijk%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'indices(1)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[0,1,2,1,3,1,4]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1,3,5]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=indices%281%29&j=%5B0%2C1%2C2%2C1%2C3%2C1%2C4%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'indices([1,2])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[0,1,2,3,1,4,2,5,1,2,6,7]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1,8]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=indices%28%5B1%2C2%5D%29&j=%5B0%2C1%2C2%2C3%2C1%2C4%2C2%2C5%2C1%2C2%2C6%2C7%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="index-rindex">
|
|
<h3>
|
|
<code>index(s)</code>, <code>rindex(s)</code>
|
|
<a href="#index-rindex" class="icon-link" aria-label="Link to this section: `index(s)`, `rindex(s)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example54" aria-expanded="false" aria-controls="example54">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example54" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'index(", ")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"a,b, cd, efg, hijk"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">3</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=index%28%22%2C%20%22%29&j=%22a%2Cb%2C%20cd%2C%20efg%2C%20hijk%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'index(1)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[0,1,2,1,3,1,4]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=index%281%29&j=%5B0%2C1%2C2%2C1%2C3%2C1%2C4%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'index([1,2])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[0,1,2,3,1,4,2,5,1,2,6,7]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=index%28%5B1%2C2%5D%29&j=%5B0%2C1%2C2%2C3%2C1%2C4%2C2%2C5%2C1%2C2%2C6%2C7%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'rindex(", ")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"a,b, cd, efg, hijk"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">12</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=rindex%28%22%2C%20%22%29&j=%22a%2Cb%2C%20cd%2C%20efg%2C%20hijk%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'rindex(1)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[0,1,2,1,3,1,4]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">5</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=rindex%281%29&j=%5B0%2C1%2C2%2C1%2C3%2C1%2C4%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'rindex([1,2])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[0,1,2,3,1,4,2,5,1,2,6,7]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">8</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=rindex%28%5B1%2C2%5D%29&j=%5B0%2C1%2C2%2C3%2C1%2C4%2C2%2C5%2C1%2C2%2C6%2C7%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="inside">
|
|
<h3>
|
|
<code>inside</code>
|
|
<a href="#inside" class="icon-link" aria-label="Link to this section: `inside`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example55" aria-expanded="false" aria-controls="example55">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example55" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'inside("foobar")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"bar"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=inside%28%22foobar%22%29&j=%22bar%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'inside(["foobar", "foobaz", "blarp"])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["baz", "bar"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=inside%28%5B%22foobar%22%2C%20%22foobaz%22%2C%20%22blarp%22%5D%29&j=%5B%22baz%22%2C%20%22bar%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'inside(["foobar", "foobaz", "blarp"])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["bazzzzz", "bar"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=inside%28%5B%22foobar%22%2C%20%22foobaz%22%2C%20%22blarp%22%5D%29&j=%5B%22bazzzzz%22%2C%20%22bar%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'inside({"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]})'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo": 12, "bar": [{"barp": 12}]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=inside%28%7B%22foo%22%3A%2012%2C%20%22bar%22%3A%5B1%2C2%2C%7B%22barp%22%3A12%2C%20%22blip%22%3A13%7D%5D%7D%29&j=%7B%22foo%22%3A%2012%2C%20%22bar%22%3A%20%5B%7B%22barp%22%3A%2012%7D%5D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'inside({"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]})'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo": 12, "bar": [{"barp": 15}]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=inside%28%7B%22foo%22%3A%2012%2C%20%22bar%22%3A%5B1%2C2%2C%7B%22barp%22%3A12%2C%20%22blip%22%3A13%7D%5D%7D%29&j=%7B%22foo%22%3A%2012%2C%20%22bar%22%3A%20%5B%7B%22barp%22%3A%2015%7D%5D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="startswith">
|
|
<h3>
|
|
<code>startswith(str)</code>
|
|
<a href="#startswith" class="icon-link" aria-label="Link to this section: `startswith(str)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>Outputs <code>true</code> if . starts with the given string argument.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example56" aria-expanded="false" aria-controls="example56">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example56" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[.[]|startswith("foo")]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["fo", "foo", "barfoo", "foobar", "barfoob"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[false, true, false, true, false]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.%5B%5D%7Cstartswith%28%22foo%22%29%5D&j=%5B%22fo%22%2C%20%22foo%22%2C%20%22barfoo%22%2C%20%22foobar%22%2C%20%22barfoob%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="endswith">
|
|
<h3>
|
|
<code>endswith(str)</code>
|
|
<a href="#endswith" class="icon-link" aria-label="Link to this section: `endswith(str)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>Outputs <code>true</code> if . ends with the given string argument.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example57" aria-expanded="false" aria-controls="example57">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example57" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[.[]|endswith("foo")]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["foobar", "barfoo"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[false, true]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.%5B%5D%7Cendswith%28%22foo%22%29%5D&j=%5B%22foobar%22%2C%20%22barfoo%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="combinations">
|
|
<h3>
|
|
<code>combinations</code>, <code>combinations(n)</code>
|
|
<a href="#combinations" class="icon-link" aria-label="Link to this section: `combinations`, `combinations(n)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example58" aria-expanded="false" aria-controls="example58">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example58" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'combinations'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[[1,2], [3, 4]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1, 3]</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">[1, 4]</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">[2, 3]</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">[2, 4]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=combinations&j=%5B%5B1%2C2%5D%2C%20%5B3%2C%204%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'combinations(2)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[0, 1]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[0, 0]</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">[0, 1]</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">[1, 0]</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">[1, 1]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=combinations%282%29&j=%5B0%2C%201%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="ltrimstr">
|
|
<h3>
|
|
<code>ltrimstr(str)</code>
|
|
<a href="#ltrimstr" class="icon-link" aria-label="Link to this section: `ltrimstr(str)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>Outputs its input with the given prefix string removed, if it
|
|
starts with it.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example59" aria-expanded="false" aria-controls="example59">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example59" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[.[]|ltrimstr("foo")]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["fo", "foo", "barfoo", "foobar", "afoo"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["fo","","barfoo","bar","afoo"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.%5B%5D%7Cltrimstr%28%22foo%22%29%5D&j=%5B%22fo%22%2C%20%22foo%22%2C%20%22barfoo%22%2C%20%22foobar%22%2C%20%22afoo%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="rtrimstr">
|
|
<h3>
|
|
<code>rtrimstr(str)</code>
|
|
<a href="#rtrimstr" class="icon-link" aria-label="Link to this section: `rtrimstr(str)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>Outputs its input with the given suffix string removed, if it
|
|
ends with it.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example60" aria-expanded="false" aria-controls="example60">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example60" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[.[]|rtrimstr("foo")]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["fo", "foo", "barfoo", "foobar", "foob"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["fo","","bar","foobar","foob"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.%5B%5D%7Crtrimstr%28%22foo%22%29%5D&j=%5B%22fo%22%2C%20%22foo%22%2C%20%22barfoo%22%2C%20%22foobar%22%2C%20%22foob%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="explode">
|
|
<h3>
|
|
<code>explode</code>
|
|
<a href="#explode" class="icon-link" aria-label="Link to this section: `explode`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>Converts an input string into an array of the string's
|
|
codepoint numbers.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example61" aria-expanded="false" aria-controls="example61">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example61" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'explode'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"foobar"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[102,111,111,98,97,114]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=explode&j=%22foobar%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="implode">
|
|
<h3>
|
|
<code>implode</code>
|
|
<a href="#implode" class="icon-link" aria-label="Link to this section: `implode`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>The inverse of explode.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example62" aria-expanded="false" aria-controls="example62">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example62" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'implode'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[65, 66, 67]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"ABC"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=implode&j=%5B65%2C%2066%2C%2067%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="split-1">
|
|
<h3>
|
|
<code>split(str)</code>
|
|
<a href="#split-1" class="icon-link" aria-label="Link to this section: `split(str)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example63" aria-expanded="false" aria-controls="example63">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example63" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'split(", ")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"a, b,c,d, e, "</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["a","b,c,d","e",""]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=split%28%22%2C%20%22%29&j=%22a%2C%20b%2Cc%2Cd%2C%20e%2C%20%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="join">
|
|
<h3>
|
|
<code>join(str)</code>
|
|
<a href="#join" class="icon-link" aria-label="Link to this section: `join(str)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example64" aria-expanded="false" aria-controls="example64">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example64" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'join(", ")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["a","b,c,d","e"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"a, b,c,d, e"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=join%28%22%2C%20%22%29&j=%5B%22a%22%2C%22b%2Cc%2Cd%22%2C%22e%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'join(" ")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["a",1,2.3,true,null,false]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"a 1 2.3 true false"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=join%28%22%20%22%29&j=%5B%22a%22%2C1%2C2.3%2Ctrue%2Cnull%2Cfalse%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="ascii_downcase-ascii_upcase">
|
|
<h3>
|
|
<code>ascii_downcase</code>, <code>ascii_upcase</code>
|
|
<a href="#ascii_downcase-ascii_upcase" class="icon-link" aria-label="Link to this section: `ascii_downcase`, `ascii_upcase`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example65" aria-expanded="false" aria-controls="example65">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example65" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'ascii_upcase'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"useful but not for é"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"USEFUL BUT NOT FOR é"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=ascii_upcase&j=%22useful%20but%20not%20for%20%C3%A9%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="while">
|
|
<h3>
|
|
<code>while(cond; update)</code>
|
|
<a href="#while" class="icon-link" aria-label="Link to this section: `while(cond; update)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example66" aria-expanded="false" aria-controls="example66">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example66" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[while(.<100; .*2)]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1,2,4,8,16,32,64]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Bwhile%28.%3C100%3B%20.%2A2%29%5D&j=1" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="repeat">
|
|
<h3>
|
|
<code>repeat(exp)</code>
|
|
<a href="#repeat" class="icon-link" aria-label="Link to this section: `repeat(exp)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example67" aria-expanded="false" aria-controls="example67">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example67" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[repeat(.*2, error)?]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[2]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Brepeat%28.%2A2%2C%20error%29%3F%5D&j=1" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="until">
|
|
<h3>
|
|
<code>until(cond; next)</code>
|
|
<a href="#until" class="icon-link" aria-label="Link to this section: `until(cond; next)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example68" aria-expanded="false" aria-controls="example68">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example68" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[.,1]|until(.[0] < 1; [.[0] - 1, .[1] * .[0]])|.[1]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">4</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">24</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.%2C1%5D%7Cuntil%28.%5B0%5D%20%3C%201%3B%20%5B.%5B0%5D%20-%201%2C%20.%5B1%5D%20%2A%20.%5B0%5D%5D%29%7C.%5B1%5D&j=4" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="recurse">
|
|
<h3>
|
|
<code>recurse(f)</code>, <code>recurse</code>, <code>recurse(f; condition)</code>
|
|
<a href="#recurse" class="icon-link" aria-label="Link to this section: `recurse(f)`, `recurse`, `recurse(f; condition)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example69" aria-expanded="false" aria-controls="example69">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example69" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'recurse(.foo[])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo":[{"foo": []}, {"foo":[{"foo":[]}]}]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"foo":[{"foo":[]},{"foo":[{"foo":[]}]}]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"foo":[]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"foo":[{"foo":[]}]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"foo":[]}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=recurse%28.foo%5B%5D%29&j=%7B%22foo%22%3A%5B%7B%22foo%22%3A%20%5B%5D%7D%2C%20%7B%22foo%22%3A%5B%7B%22foo%22%3A%5B%5D%7D%5D%7D%5D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'recurse'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a":0,"b":[1]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a":0,"b":[1]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">0</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">[1]</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=recurse&j=%7B%22a%22%3A0%2C%22b%22%3A%5B1%5D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'recurse(. * .; . < 20)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">2</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">2</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">4</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">16</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=recurse%28.%20%2A%20.%3B%20.%20%3C%2020%29&j=2" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="walk">
|
|
<h3>
|
|
<code>walk(f)</code>
|
|
<a href="#walk" class="icon-link" aria-label="Link to this section: `walk(f)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example70" aria-expanded="false" aria-controls="example70">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example70" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'walk(if type == "array" then sort else . end)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[[4, 1, 7], [8, 5, 2], [3, 6, 9]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[[1,4,7],[2,5,8],[3,6,9]]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=walk%28if%20type%20%3D%3D%20%22array%22%20then%20sort%20else%20.%20end%29&j=%5B%5B4%2C%201%2C%207%5D%2C%20%5B8%2C%205%2C%202%5D%2C%20%5B3%2C%206%2C%209%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'walk( if type == "object" then with_entries( .key |= sub( "^_+"; "") ) else . end )'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[ { "_a": { "__b": 2 } } ]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[{"a":{"b":2}}]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=walk%28%20if%20type%20%3D%3D%20%22object%22%20then%20with_entries%28%20.key%20%7C%3D%20sub%28%20%22%5E_%2B%22%3B%20%22%22%29%20%29%20else%20.%20end%20%29&j=%5B%20%7B%20%22_a%22%3A%20%7B%20%22__b%22%3A%202%20%7D%20%7D%20%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="$jq_build_configuration">
|
|
<h3>
|
|
<code>$JQ_BUILD_CONFIGURATION</code>
|
|
<a href="#$jq_build_configuration" class="icon-link" aria-label="Link to this section: `$JQ_BUILD_CONFIGURATION`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>This builtin binding shows the jq executable's build
|
|
configuration. Its value has no particular format, but
|
|
it can be expected to be at least the <code>./configure</code>
|
|
command-line arguments, and may be enriched in the
|
|
future to include the version strings for the build
|
|
tooling used.</p>
|
|
<p>Note that this can be overriden in the command-line
|
|
with <code>--arg</code> and related options.</p>
|
|
</section>
|
|
<section id="$env-env">
|
|
<h3>
|
|
<code>$ENV</code>, <code>env</code>
|
|
<a href="#$env-env" class="icon-link" aria-label="Link to this section: `$ENV`, `env`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example71" aria-expanded="false" aria-controls="example71">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example71" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '$ENV.PAGER'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"less"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%24ENV.PAGER&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'env.PAGER'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"less"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=env.PAGER&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="transpose">
|
|
<h3>
|
|
<code>transpose</code>
|
|
<a href="#transpose" class="icon-link" aria-label="Link to this section: `transpose`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>Transpose a possibly jagged matrix (an array of arrays).
|
|
Rows are padded with nulls so the result is always rectangular.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example72" aria-expanded="false" aria-controls="example72">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example72" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'transpose'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[[1], [2,3]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[[1,2],[null,3]]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=transpose&j=%5B%5B1%5D%2C%20%5B2%2C3%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="bsearch">
|
|
<h3>
|
|
<code>bsearch(x)</code>
|
|
<a href="#bsearch" class="icon-link" aria-label="Link to this section: `bsearch(x)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example73" aria-expanded="false" aria-controls="example73">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example73" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'bsearch(0)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[0,1]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">0</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=bsearch%280%29&j=%5B0%2C1%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'bsearch(0)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,2,3]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">-1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=bsearch%280%29&j=%5B1%2C2%2C3%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'bsearch(4) as $ix | if $ix < 0 then .[-(1+$ix)] = 4 else . end'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,2,3]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1,2,3,4]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=bsearch%284%29%20as%20%24ix%20%7C%20if%20%24ix%20%3C%200%20then%20.%5B-%281%2B%24ix%29%5D%20%3D%204%20else%20.%20end&j=%5B1%2C2%2C3%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="string-interpolation">
|
|
<h3>
|
|
String interpolation: <code>\(exp)</code>
|
|
<a href="#string-interpolation" class="icon-link" aria-label="Link to this section: String interpolation: `\(exp)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example74" aria-expanded="false" aria-controls="example74">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example74" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '"The input was \(.), which is one less than \(.+1)"'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">42</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"The input was 42, which is one less than 43"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%22The%20input%20was%20%5C%28.%29%2C%20which%20is%20one%20less%20than%20%5C%28.%2B1%29%22&j=42" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="convert-to-from-json">
|
|
<h3>
|
|
Convert to/from JSON
|
|
<a href="#convert-to-from-json" class="icon-link" aria-label="Link to this section: Convert to/from JSON"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example75" aria-expanded="false" aria-controls="example75">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example75" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[.[]|tostring]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1, "foo", ["foo"]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["1","foo","[\"foo\"]"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.%5B%5D%7Ctostring%5D&j=%5B1%2C%20%22foo%22%2C%20%5B%22foo%22%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[.[]|tojson]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1, "foo", ["foo"]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["1","\"foo\"","[\"foo\"]"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.%5B%5D%7Ctojson%5D&j=%5B1%2C%20%22foo%22%2C%20%5B%22foo%22%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[.[]|tojson|fromjson]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1, "foo", ["foo"]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1,"foo",["foo"]]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.%5B%5D%7Ctojson%7Cfromjson%5D&j=%5B1%2C%20%22foo%22%2C%20%5B%22foo%22%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="format-strings-and-escaping">
|
|
<h3>
|
|
Format strings and escaping
|
|
<a href="#format-strings-and-escaping" class="icon-link" aria-label="Link to this section: Format strings and escaping"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example76" aria-expanded="false" aria-controls="example76">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example76" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '@html'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"This works if x < y"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"This works if x &lt; y"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%40html&j=%22This%20works%20if%20x%20%3C%20y%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '@sh "echo \(.)"'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"O'Hara's Ale"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"echo 'O'\\''Hara'\\''s Ale'"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%40sh%20%22echo%20%5C%28.%29%22&j=%22O%27Hara%27s%20Ale%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '@base64'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"This is a message"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"VGhpcyBpcyBhIG1lc3NhZ2U="</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%40base64&j=%22This%20is%20a%20message%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '@base64d'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"VGhpcyBpcyBhIG1lc3NhZ2U="</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"This is a message"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%40base64d&j=%22VGhpcyBpcyBhIG1lc3NhZ2U%3D%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="dates">
|
|
<h3>
|
|
Dates
|
|
<a href="#dates" class="icon-link" aria-label="Link to this section: Dates"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example77" aria-expanded="false" aria-controls="example77">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example77" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'fromdate'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"2015-03-05T23:51:47Z"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1425599507</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=fromdate&j=%222015-03-05T23%3A51%3A47Z%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'strptime("%Y-%m-%dT%H:%M:%SZ")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"2015-03-05T23:51:47Z"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[2015,2,5,23,51,47,4,63]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=strptime%28%22%25Y-%25m-%25dT%25H%3A%25M%3A%25SZ%22%29&j=%222015-03-05T23%3A51%3A47Z%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'strptime("%Y-%m-%dT%H:%M:%SZ")|mktime'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"2015-03-05T23:51:47Z"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1425599507</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=strptime%28%22%25Y-%25m-%25dT%25H%3A%25M%3A%25SZ%22%29%7Cmktime&j=%222015-03-05T23%3A51%3A47Z%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="sql-style-operators">
|
|
<h3>
|
|
SQL-Style Operators
|
|
<a href="#sql-style-operators" class="icon-link" aria-label="Link to this section: SQL-Style Operators"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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>
|
|
<a href="#builtins" class="icon-link" aria-label="Link to this section: `builtins`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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="conditionals-and-comparisons">
|
|
<h2>Conditionals and Comparisons <a href="#conditionals-and-comparisons" class="icon-link" aria-label="Link to this section: Conditionals and Comparisons"><span class="bi bi-link-45deg" aria-hidden="true"></span></a></h2>
|
|
|
|
<section id="==-!=">
|
|
<h3>
|
|
<code>==</code>, <code>!=</code>
|
|
<a href="#==-!=" class="icon-link" aria-label="Link to this section: `==`, `!=`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example78" aria-expanded="false" aria-controls="example78">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example78" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '. == false'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%20%3D%3D%20false&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '. == {"b": {"d": (4 + 1e-20), "c": 3}, "a":1}'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a":1, "b": {"c": 3, "d": 4}}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%20%3D%3D%20%7B%22b%22%3A%20%7B%22d%22%3A%20%284%20%2B%201e-20%29%2C%20%22c%22%3A%203%7D%2C%20%22a%22%3A1%7D&j=%7B%22a%22%3A1%2C%20%22b%22%3A%20%7B%22c%22%3A%203%2C%20%22d%22%3A%204%7D%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] == 1'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1, 1.0, "1", "banana"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20%3D%3D%201&j=%5B1%2C%201.0%2C%20%221%22%2C%20%22banana%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="if-then-else-end">
|
|
<h3>
|
|
if-then-else-end
|
|
<a href="#if-then-else-end" class="icon-link" aria-label="Link to this section: if-then-else-end"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example79" aria-expanded="false" aria-controls="example79">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example79" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'if . == 0 then
|
|
"zero"
|
|
elif . == 1 then
|
|
"one"
|
|
else
|
|
"many"
|
|
end'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">2</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"many"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=if%20.%20%3D%3D%200%20then%0A%20%20%22zero%22%0Aelif%20.%20%3D%3D%201%20then%0A%20%20%22one%22%0Aelse%0A%20%20%22many%22%0Aend&j=2" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id=">->=-<=-<">
|
|
<h3>
|
|
<code>></code>, <code>>=</code>, <code><=</code>, <code><</code>
|
|
<a href="#>->=-<=-<" class="icon-link" aria-label="Link to this section: `>`, `>=`, `<=`, `<`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example80" aria-expanded="false" aria-controls="example80">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example80" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '. < 5'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">2</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%20%3C%205&j=2" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="and-or-not">
|
|
<h3>
|
|
<code>and</code>, <code>or</code>, <code>not</code>
|
|
<a href="#and-or-not" class="icon-link" aria-label="Link to this section: `and`, `or`, `not`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example81" aria-expanded="false" aria-controls="example81">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example81" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '42 and "a string"'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=42%20and%20%22a%20string%22&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '(true, false) or false'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%28true%2C%20false%29%20or%20false&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '(true, true) and (true, false)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%28true%2C%20true%29%20and%20%28true%2C%20false%29&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[true, false | not]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[false, true]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Btrue%2C%20false%20%7C%20not%5D&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="alternative-operator">
|
|
<h3>
|
|
Alternative operator: <code>//</code>
|
|
<a href="#alternative-operator" class="icon-link" aria-label="Link to this section: Alternative operator: `//`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>The <code>//</code> operator produces all the values of its left-hand
|
|
side that are neither <code>false</code> nor <code>null</code>, or, if the
|
|
left-hand side produces no values other than <code>false</code> or
|
|
<code>null</code>, then <code>//</code> produces all the values of its right-hand
|
|
side.</p>
|
|
<p>A filter of the form <code>a // b</code> produces all the results of
|
|
<code>a</code> that are not <code>false</code> or <code>null</code>. If <code>a</code> produces no
|
|
results, or no results other than <code>false</code> or <code>null</code>, then <code>a
|
|
// b</code> produces the results of <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>
|
|
<p>Note: <code>some_generator // defaults_here</code> is not the same
|
|
as <code>some_generator | . // defaults_here</code>. The latter will
|
|
produce default values for all non-<code>false</code>, non-<code>null</code>
|
|
values of the left-hand side, while the former will not.
|
|
Precedence rules can make this confusing. For example, in
|
|
<code>false, 1 // 2</code> the left-hand side of <code>//</code> is <code>1</code>, not
|
|
<code>false, 1</code> -- <code>false, 1 // 2</code> parses the same way as <code>false,
|
|
(1 // 2)</code>. In <code>(false, null, 1) | . // 42</code> the left-hand
|
|
side of <code>//</code> is <code>.</code>, which always produces just one value,
|
|
while in <code>(false, null, 1) // 42</code> the left-hand side is a
|
|
generator of three values, and since it produces a
|
|
value other <code>false</code> and <code>null</code>, the default <code>42</code> is not
|
|
produced.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example82" aria-expanded="false" aria-controls="example82">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example82" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'empty // 42'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">42</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=empty%20//%2042&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.foo // 42'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo": 19}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">19</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.foo%20//%2042&j=%7B%22foo%22%3A%2019%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.foo // 42'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">42</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.foo%20//%2042&j=%7B%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '(false, null, 1) // 42'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%28false%2C%20null%2C%201%29%20//%2042&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '(false, null, 1) | . // 42'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">42</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">42</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%28false%2C%20null%2C%201%29%20%7C%20.%20//%2042&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="try-catch">
|
|
<h3>
|
|
try-catch
|
|
<a href="#try-catch" class="icon-link" aria-label="Link to this section: try-catch"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example83" aria-expanded="false" aria-controls="example83">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example83" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'try .a catch ". is not an object"'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">". is not an object"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=try%20.a%20catch%20%22.%20is%20not%20an%20object%22&j=true" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[.[]|try .a]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{}, true, {"a":1}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[null, 1]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.%5B%5D%7Ctry%20.a%5D&j=%5B%7B%7D%2C%20true%2C%20%7B%22a%22%3A1%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'try error("some exception") catch .'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"some exception"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=try%20error%28%22some%20exception%22%29%20catch%20.&j=true" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="breaking-out-of-control-structures">
|
|
<h3>
|
|
Breaking out of control structures
|
|
<a href="#breaking-out-of-control-structures" class="icon-link" aria-label="Link to this section: Breaking out of control structures"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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
|
|
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="error-suppression-optional-operator">
|
|
<h3>
|
|
Error Suppression / Optional Operator: <code>?</code>
|
|
<a href="#error-suppression-optional-operator" class="icon-link" aria-label="Link to this section: Error Suppression / Optional Operator: `?`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>The <code>?</code> operator, used as <code>EXP?</code>, is shorthand for <code>try EXP</code>.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example84" aria-expanded="false" aria-controls="example84">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example84" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[.[] | .a?]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{}, true, {"a":1}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[null, 1]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.%5B%5D%20%7C%20.a%3F%5D&j=%5B%7B%7D%2C%20true%2C%20%7B%22a%22%3A1%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[.[] | tonumber?]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["1", "invalid", "3", 4]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1, 3, 4]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B.%5B%5D%20%7C%20tonumber%3F%5D&j=%5B%221%22%2C%20%22invalid%22%2C%20%223%22%2C%204%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
</section>
|
|
<section id="regular-expressions">
|
|
<h2>Regular expressions <a href="#regular-expressions" class="icon-link" aria-label="Link to this section: Regular expressions"><span class="bi bi-link-45deg" aria-hidden="true"></span></a></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">
|
|
<h3>
|
|
<code>test(val)</code>, <code>test(regex; flags)</code>
|
|
<a href="#test" class="icon-link" aria-label="Link to this section: `test(val)`, `test(regex; flags)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example85" aria-expanded="false" aria-controls="example85">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example85" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'test("foo")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"foo"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=test%28%22foo%22%29&j=%22foo%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] | test("a b c # spaces are ignored"; "ix")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["xabcd", "ABC"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20%7C%20test%28%22a%20b%20c%20%23%20spaces%20are%20ignored%22%3B%20%22ix%22%29&j=%5B%22xabcd%22%2C%20%22ABC%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="match">
|
|
<h3>
|
|
<code>match(val)</code>, <code>match(regex; flags)</code>
|
|
<a href="#match" class="icon-link" aria-label="Link to this section: `match(val)`, `match(regex; flags)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example86" aria-expanded="false" aria-controls="example86">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example86" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'match("(abc)+"; "g")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"abc abc"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"offset": 0, "length": 3, "string": "abc", "captures": [{"offset": 0, "length": 3, "string": "abc", "name": null}]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"offset": 4, "length": 3, "string": "abc", "captures": [{"offset": 4, "length": 3, "string": "abc", "name": null}]}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=match%28%22%28abc%29%2B%22%3B%20%22g%22%29&j=%22abc%20abc%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'match("foo")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"foo bar foo"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"offset": 0, "length": 3, "string": "foo", "captures": []}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=match%28%22foo%22%29&j=%22foo%20bar%20foo%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'match(["foo", "ig"])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"foo bar FOO"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"offset": 0, "length": 3, "string": "foo", "captures": []}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"offset": 8, "length": 3, "string": "FOO", "captures": []}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=match%28%5B%22foo%22%2C%20%22ig%22%5D%29&j=%22foo%20bar%20FOO%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'match("foo (?<bar123>bar)? foo"; "ig")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"foo bar foo foo foo"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"offset": 0, "length": 11, "string": "foo bar foo", "captures": [{"offset": 4, "length": 3, "string": "bar", "name": "bar123"}]}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"offset": 12, "length": 8, "string": "foo foo", "captures": [{"offset": -1, "length": 0, "string": null, "name": "bar123"}]}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=match%28%22foo%20%28%3F%3Cbar123%3Ebar%29%3F%20foo%22%3B%20%22ig%22%29&j=%22foo%20bar%20foo%20foo%20%20foo%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[ match("."; "g")] | length'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"abc"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">3</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5B%20match%28%22.%22%3B%20%22g%22%29%5D%20%7C%20length&j=%22abc%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="capture">
|
|
<h3>
|
|
<code>capture(val)</code>, <code>capture(regex; flags)</code>
|
|
<a href="#capture" class="icon-link" aria-label="Link to this section: `capture(val)`, `capture(regex; flags)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example87" aria-expanded="false" aria-controls="example87">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example87" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'capture("(?<a>[a-z]+)-(?<n>[0-9]+)")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"xyzzy-14"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{ "a": "xyzzy", "n": "14" }</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=capture%28%22%28%3F%3Ca%3E%5Ba-z%5D%2B%29-%28%3F%3Cn%3E%5B0-9%5D%2B%29%22%29&j=%22xyzzy-14%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="scan">
|
|
<h3>
|
|
<code>scan(regex)</code>, <code>scan(regex; flags)</code>
|
|
<a href="#scan" class="icon-link" aria-label="Link to this section: `scan(regex)`, `scan(regex; flags)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example88" aria-expanded="false" aria-controls="example88">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example88" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'scan("c")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"abcdefabc"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"c"</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">"c"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=scan%28%22c%22%29&j=%22abcdefabc%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="split-2">
|
|
<h3>
|
|
<code>split(regex; flags)</code>
|
|
<a href="#split-2" class="icon-link" aria-label="Link to this section: `split(regex; flags)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example89" aria-expanded="false" aria-controls="example89">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example89" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'split(", *"; null)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"ab,cd, ef"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["ab","cd","ef"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=split%28%22%2C%20%2A%22%3B%20null%29&j=%22ab%2Ccd%2C%20ef%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="splits">
|
|
<h3>
|
|
<code>splits(regex)</code>, <code>splits(regex; flags)</code>
|
|
<a href="#splits" class="icon-link" aria-label="Link to this section: `splits(regex)`, `splits(regex; flags)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>These provide the same results as their <code>split</code> counterparts,
|
|
but as a stream instead of an array.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example90" aria-expanded="false" aria-controls="example90">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example90" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'splits(", *")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"ab,cd, ef, gh"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"ab"</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">"cd"</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">"ef"</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">"gh"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=splits%28%22%2C%20%2A%22%29&j=%22ab%2Ccd%2C%20%20%20ef%2C%20gh%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="sub">
|
|
<h3>
|
|
<code>sub(regex; tostring)</code>, <code>sub(regex; tostring; flags)</code>
|
|
<a href="#sub" class="icon-link" aria-label="Link to this section: `sub(regex; tostring)`, `sub(regex; tostring; flags)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example91" aria-expanded="false" aria-controls="example91">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example91" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'sub("[^a-z]*(?<x>[a-z]+)"; "Z\(.x)"; "g")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"123abc456def"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"ZabcZdef"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=sub%28%22%5B%5Ea-z%5D%2A%28%3F%3Cx%3E%5Ba-z%5D%2B%29%22%3B%20%22Z%5C%28.x%29%22%3B%20%22g%22%29&j=%22123abc456def%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[sub("(?<a>.)"; "\(.a|ascii_upcase)", "\(.a|ascii_downcase)")]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"aB"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["AB","aB"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Bsub%28%22%28%3F%3Ca%3E.%29%22%3B%20%22%5C%28.a%7Cascii_upcase%29%22%2C%20%22%5C%28.a%7Cascii_downcase%29%22%29%5D&j=%22aB%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="gsub">
|
|
<h3>
|
|
<code>gsub(regex; tostring)</code>, <code>gsub(regex; tostring; flags)</code>
|
|
<a href="#gsub" class="icon-link" aria-label="Link to this section: `gsub(regex; tostring)`, `gsub(regex; tostring; flags)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example92" aria-expanded="false" aria-controls="example92">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example92" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'gsub("(?<x>.)[^a]*"; "+\(.x)-")'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"Abcabc"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">"+A-+a-"</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=gsub%28%22%28%3F%3Cx%3E.%29%5B%5Ea%5D%2A%22%3B%20%22%2B%5C%28.x%29-%22%29&j=%22Abcabc%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[gsub("p"; "a", "b")]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">"p"</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">["a","b"]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Bgsub%28%22p%22%3B%20%22a%22%2C%20%22b%22%29%5D&j=%22p%22" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
</section>
|
|
<section id="advanced-features">
|
|
<h2>Advanced features <a href="#advanced-features" class="icon-link" aria-label="Link to this section: Advanced features"><span class="bi bi-link-45deg" aria-hidden="true"></span></a></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-symbolic-binding-operator">
|
|
<h3>
|
|
Variable / Symbolic Binding Operator: <code>... as $identifier | ...</code>
|
|
<a href="#variable-symbolic-binding-operator" class="icon-link" aria-label="Link to this section: Variable / Symbolic Binding Operator: `... as $identifier | ...`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example93" aria-expanded="false" aria-controls="example93">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example93" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.bar as $x | .foo | . + $x'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo":10, "bar":200}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">210</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.bar%20as%20%24x%20%7C%20.foo%20%7C%20.%20%2B%20%24x&j=%7B%22foo%22%3A10%2C%20%22bar%22%3A200%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '. as $i|[(.*2|. as $i| $i), $i]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">5</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[10,5]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%20as%20%24i%7C%5B%28.%2A2%7C.%20as%20%24i%7C%20%24i%29%2C%20%24i%5D&j=5" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '. as [$a, $b, {c: $c}] | $a + $b + $c'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[2, 3, {"c": 4, "d": 5}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">9</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%20as%20%5B%24a%2C%20%24b%2C%20%7Bc%3A%20%24c%7D%5D%20%7C%20%24a%20%2B%20%24b%20%2B%20%24c&j=%5B2%2C%203%2C%20%7B%22c%22%3A%204%2C%20%22d%22%3A%205%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] as [$a, $b] | {a: $a, b: $b}'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[[0], [0, 1], [2, 1, 0]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a":0,"b":null}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"a":0,"b":1}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"a":2,"b":1}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20as%20%5B%24a%2C%20%24b%5D%20%7C%20%7Ba%3A%20%24a%2C%20b%3A%20%24b%7D&j=%5B%5B0%5D%2C%20%5B0%2C%201%5D%2C%20%5B2%2C%201%2C%200%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="destructuring-alternative-operator">
|
|
<h3>
|
|
Destructuring Alternative Operator: <code>?//</code>
|
|
<a href="#destructuring-alternative-operator" class="icon-link" aria-label="Link to this section: Destructuring Alternative Operator: `?//`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example94" aria-expanded="false" aria-controls="example94">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example94" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] as {$a, $b, c: {$d, $e}} ?// {$a, $b, c: [{$d, $e}]} | {$a, $b, $d, $e}'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"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 class="font-monospace">{"a":1,"b":2,"d":3,"e":4}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"a":1,"b":2,"d":3,"e":4}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20as%20%7B%24a%2C%20%24b%2C%20c%3A%20%7B%24d%2C%20%24e%7D%7D%20%3F//%20%7B%24a%2C%20%24b%2C%20c%3A%20%5B%7B%24d%2C%20%24e%7D%5D%7D%20%7C%20%7B%24a%2C%20%24b%2C%20%24d%2C%20%24e%7D&j=%5B%7B%22a%22%3A%201%2C%20%22b%22%3A%202%2C%20%22c%22%3A%20%7B%22d%22%3A%203%2C%20%22e%22%3A%204%7D%7D%2C%20%7B%22a%22%3A%201%2C%20%22b%22%3A%202%2C%20%22c%22%3A%20%5B%7B%22d%22%3A%203%2C%20%22e%22%3A%204%7D%5D%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] as {$a, $b, c: {$d}} ?// {$a, $b, c: [{$e}]} | {$a, $b, $d, $e}'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"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 class="font-monospace">{"a":1,"b":2,"d":3,"e":null}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"a":1,"b":2,"d":null,"e":4}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20as%20%7B%24a%2C%20%24b%2C%20c%3A%20%7B%24d%7D%7D%20%3F//%20%7B%24a%2C%20%24b%2C%20c%3A%20%5B%7B%24e%7D%5D%7D%20%7C%20%7B%24a%2C%20%24b%2C%20%24d%2C%20%24e%7D&j=%5B%7B%22a%22%3A%201%2C%20%22b%22%3A%202%2C%20%22c%22%3A%20%7B%22d%22%3A%203%2C%20%22e%22%3A%204%7D%7D%2C%20%7B%22a%22%3A%201%2C%20%22b%22%3A%202%2C%20%22c%22%3A%20%5B%7B%22d%22%3A%203%2C%20%22e%22%3A%204%7D%5D%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.[] as [$a] ?// [$b] | if $a != null then error("err: \($a)") else {$a,$b} end'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[[3]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a":null,"b":3}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%5B%5D%20as%20%5B%24a%5D%20%3F//%20%5B%24b%5D%20%7C%20if%20%24a%20%21%3D%20null%20then%20error%28%22err%3A%20%5C%28%24a%29%22%29%20else%20%7B%24a%2C%24b%7D%20end&j=%5B%5B3%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="defining-functions">
|
|
<h3>
|
|
Defining Functions
|
|
<a href="#defining-functions" class="icon-link" aria-label="Link to this section: Defining Functions"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example95" aria-expanded="false" aria-controls="example95">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example95" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'def addvalue(f): . + [f]; map(addvalue(.[0]))'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[[1,2],[10,20]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[[1,2,1], [10,20,10]]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=def%20addvalue%28f%29%3A%20.%20%2B%20%5Bf%5D%3B%20map%28addvalue%28.%5B0%5D%29%29&j=%5B%5B1%2C2%5D%2C%5B10%2C20%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'def addvalue(f): f as $x | map(. + $x); addvalue(.[0])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[[1,2],[10,20]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[[1,2,1,2], [10,20,1,2]]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=def%20addvalue%28f%29%3A%20f%20as%20%24x%20%7C%20map%28.%20%2B%20%24x%29%3B%20addvalue%28.%5B0%5D%29&j=%5B%5B1%2C2%5D%2C%5B10%2C20%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="scoping">
|
|
<h3>
|
|
Scoping
|
|
<a href="#scoping" class="icon-link" aria-label="Link to this section: Scoping"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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">
|
|
<h3>
|
|
<code>isempty(exp)</code>
|
|
<a href="#isempty" class="icon-link" aria-label="Link to this section: `isempty(exp)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>Returns true if <code>exp</code> produces no outputs, false otherwise.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example96" aria-expanded="false" aria-controls="example96">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example96" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'isempty(empty)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=isempty%28empty%29&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'isempty(.[])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=isempty%28.%5B%5D%29&j=%5B%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'isempty(.[])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,2,3]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">false</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=isempty%28.%5B%5D%29&j=%5B1%2C2%2C3%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="limit">
|
|
<h3>
|
|
<code>limit(n; exp)</code>
|
|
<a href="#limit" class="icon-link" aria-label="Link to this section: `limit(n; exp)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>The <code>limit</code> function extracts up to <code>n</code> outputs from <code>exp</code>.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example97" aria-expanded="false" aria-controls="example97">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example97" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[limit(3;.[])]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[0,1,2,3,4,5,6,7,8,9]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[0,1,2]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Blimit%283%3B.%5B%5D%29%5D&j=%5B0%2C1%2C2%2C3%2C4%2C5%2C6%2C7%2C8%2C9%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="first-last-nth-2">
|
|
<h3>
|
|
<code>first(expr)</code>, <code>last(expr)</code>, <code>nth(n; expr)</code>
|
|
<a href="#first-last-nth-2" class="icon-link" aria-label="Link to this section: `first(expr)`, `last(expr)`, `nth(n; expr)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example98" aria-expanded="false" aria-controls="example98">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example98" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[first(range(.)), last(range(.)), nth(./2; range(.))]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">10</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[0,9,5]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Bfirst%28range%28.%29%29%2C%20last%28range%28.%29%29%2C%20nth%28./2%3B%20range%28.%29%29%5D&j=10" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="first-last-nth-1">
|
|
<h3>
|
|
<code>first</code>, <code>last</code>, <code>nth(n)</code>
|
|
<a href="#first-last-nth-1" class="icon-link" aria-label="Link to this section: `first`, `last`, `nth(n)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example99" aria-expanded="false" aria-controls="example99">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example99" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '[range(.)]|[first, last, nth(5)]'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">10</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[0,9,5]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%5Brange%28.%29%5D%7C%5Bfirst%2C%20last%2C%20nth%285%29%5D&j=10" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="reduce">
|
|
<h3>
|
|
<code>reduce</code>
|
|
<a href="#reduce" class="icon-link" aria-label="Link to this section: `reduce`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example100" aria-expanded="false" aria-controls="example100">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example100" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'reduce .[] as $item (0; . + $item)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,2,3,4,5]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">15</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=reduce%20.%5B%5D%20as%20%24item%20%280%3B%20.%20%2B%20%24item%29&j=%5B1%2C2%2C3%2C4%2C5%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'reduce .[] as [$i,$j] (0; . + $i * $j)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[[1,2],[3,4],[5,6]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">44</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=reduce%20.%5B%5D%20as%20%5B%24i%2C%24j%5D%20%280%3B%20.%20%2B%20%24i%20%2A%20%24j%29&j=%5B%5B1%2C2%5D%2C%5B3%2C4%5D%2C%5B5%2C6%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'reduce .[] as {$x,$y} (null; .x += $x | .y += [$y])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[{"x":"a","y":1},{"x":"b","y":2},{"x":"c","y":3}]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"x":"abc","y":[1,2,3]}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=reduce%20.%5B%5D%20as%20%7B%24x%2C%24y%7D%20%28null%3B%20.x%20%2B%3D%20%24x%20%7C%20.y%20%2B%3D%20%5B%24y%5D%29&j=%5B%7B%22x%22%3A%22a%22%2C%22y%22%3A1%7D%2C%7B%22x%22%3A%22b%22%2C%22y%22%3A2%7D%2C%7B%22x%22%3A%22c%22%2C%22y%22%3A3%7D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="foreach">
|
|
<h3>
|
|
<code>foreach</code>
|
|
<a href="#foreach" class="icon-link" aria-label="Link to this section: `foreach`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example101" aria-expanded="false" aria-controls="example101">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example101" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'foreach .[] as $item (0; . + $item)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,2,3,4,5]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">3</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">6</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">10</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">15</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=foreach%20.%5B%5D%20as%20%24item%20%280%3B%20.%20%2B%20%24item%29&j=%5B1%2C2%2C3%2C4%2C5%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'foreach .[] as $item (0; . + $item; [$item, . * 2])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[1,2,3,4,5]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1,2]</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">[2,6]</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">[3,12]</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">[4,20]</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">[5,30]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=foreach%20.%5B%5D%20as%20%24item%20%280%3B%20.%20%2B%20%24item%3B%20%5B%24item%2C%20.%20%2A%202%5D%29&j=%5B1%2C2%2C3%2C4%2C5%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'foreach .[] as $item (0; . + 1; {index: ., $item})'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">["foo", "bar", "baz"]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"index":1,"item":"foo"}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"index":2,"item":"bar"}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"index":3,"item":"baz"}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=foreach%20.%5B%5D%20as%20%24item%20%280%3B%20.%20%2B%201%3B%20%7Bindex%3A%20.%2C%20%24item%7D%29&j=%5B%22foo%22%2C%20%22bar%22%2C%20%22baz%22%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="recursion">
|
|
<h3>
|
|
Recursion
|
|
<a href="#recursion" class="icon-link" aria-label="Link to this section: Recursion"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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="generators-and-iterators">
|
|
<h3>
|
|
Generators and iterators
|
|
<a href="#generators-and-iterators" class="icon-link" aria-label="Link to this section: Generators and iterators"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 the values generated 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 construct new generators
|
|
using only recursion and the comma operator. If
|
|
recursive calls 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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example102" aria-expanded="false" aria-controls="example102">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example102" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">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 class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">0</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">3</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">6</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">9</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=def%20range%28init%3B%20upto%3B%20by%29%3A%20def%20_range%3A%20if%20%28by%20%3E%200%20and%20.%20%3C%20upto%29%20or%20%28by%20%3C%200%20and%20.%20%3E%20upto%29%20then%20.%2C%20%28%28.%2Bby%29%7C_range%29%20else%20.%20end%3B%20if%20by%20%3D%3D%200%20then%20init%20else%20init%7C_range%20end%20%7C%20select%28%28by%20%3E%200%20and%20.%20%3C%20upto%29%20or%20%28by%20%3C%200%20and%20.%20%3E%20upto%29%29%3B%20range%280%3B%2010%3B%203%29&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">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 class="font-monospace">1</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1,2,4,8,16,32,64]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=def%20while%28cond%3B%20update%29%3A%20def%20_while%3A%20if%20cond%20then%20.%2C%20%28update%20%7C%20_while%29%20else%20empty%20end%3B%20_while%3B%20%5Bwhile%28.%3C100%3B%20.%2A2%29%5D&j=1" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
</section>
|
|
<section id="math">
|
|
<h2>Math <a href="#math" class="icon-link" aria-label="Link to this section: Math"><span class="bi bi-link-45deg" aria-hidden="true"></span></a></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 <a href="#io" class="icon-link" aria-label="Link to this section: I/O"><span class="bi bi-link-45deg" aria-hidden="true"></span></a></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>
|
|
<a href="#input" class="icon-link" aria-label="Link to this section: `input`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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>
|
|
<a href="#inputs" class="icon-link" aria-label="Link to this section: `inputs`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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">
|
|
<h3>
|
|
<code>debug</code>, <code>debug(msgs)</code>
|
|
<a href="#debug" class="icon-link" aria-label="Link to this section: `debug`, `debug(msgs)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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>
|
|
<a href="#stderr" class="icon-link" aria-label="Link to this section: `stderr`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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>
|
|
<a href="#input_filename" class="icon-link" aria-label="Link to this section: `input_filename`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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>
|
|
<a href="#input_line_number" class="icon-link" aria-label="Link to this section: `input_line_number`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>Returns the line number of the input currently being filtered.</p>
|
|
</section>
|
|
</section>
|
|
<section id="streaming">
|
|
<h2>Streaming <a href="#streaming" class="icon-link" aria-label="Link to this section: Streaming"><span class="bi bi-link-45deg" aria-hidden="true"></span></a></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">
|
|
<h3>
|
|
<code>truncate_stream(stream_expression)</code>
|
|
<a href="#truncate_stream" class="icon-link" aria-label="Link to this section: `truncate_stream(stream_expression)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example103" aria-expanded="false" aria-controls="example103">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example103" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]])'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">1</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[[0],2]</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">[[0]]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=truncate_stream%28%5B%5B0%5D%2C1%5D%2C%5B%5B1%2C0%5D%2C2%5D%2C%5B%5B1%2C0%5D%5D%2C%5B%5B1%5D%5D%29&j=1" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="fromstream">
|
|
<h3>
|
|
<code>fromstream(stream_expression)</code>
|
|
<a href="#fromstream" class="icon-link" aria-label="Link to this section: `fromstream(stream_expression)`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>Outputs values corresponding to the stream expression's
|
|
outputs.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example104" aria-expanded="false" aria-controls="example104">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example104" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq 'fromstream(1|truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]]))'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[2]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=fromstream%281%7Ctruncate_stream%28%5B%5B0%5D%2C1%5D%2C%5B%5B1%2C0%5D%2C2%5D%2C%5B%5B1%2C0%5D%5D%2C%5B%5B1%5D%5D%29%29&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="tostream">
|
|
<h3>
|
|
<code>tostream</code>
|
|
<a href="#tostream" class="icon-link" aria-label="Link to this section: `tostream`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</h3>
|
|
<p>The <code>tostream</code> builtin outputs the streamed form of its input.</p>
|
|
<div class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example105" aria-expanded="false" aria-controls="example105">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example105" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '. as $dot|fromstream($dot|tostream)|.==$dot'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[0,[1,{"a":1},{"b":2}]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">true</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.%20as%20%24dot%7Cfromstream%28%24dot%7Ctostream%29%7C.%3D%3D%24dot&j=%5B0%2C%5B1%2C%7B%22a%22%3A1%7D%2C%7B%22b%22%3A2%7D%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
</section>
|
|
<section id="assignment">
|
|
<h2>Assignment <a href="#assignment" class="icon-link" aria-label="Link to this section: Assignment"><span class="bi bi-link-45deg" aria-hidden="true"></span></a></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>
|
|
<a href="#update-assignment" class="icon-link" aria-label="Link to this section: Update-assignment: `|=`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example106" aria-expanded="false" aria-controls="example106">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example106" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '(..|select(type=="boolean")) |= if . then 1 else 0 end'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">[true,false,[5,true,[true,[false]],false]]</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">[1,0,[5,1,[1,[0]],0]]</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%28..%7Cselect%28type%3D%3D%22boolean%22%29%29%20%7C%3D%20if%20.%20then%201%20else%200%20end&j=%5Btrue%2Cfalse%2C%5B5%2Ctrue%2C%5Btrue%2C%5Bfalse%5D%5D%2Cfalse%5D%5D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="arithmetic-update-assignment">
|
|
<h3>
|
|
Arithmetic update-assignment: <code>+=</code>, <code>-=</code>, <code>*=</code>, <code>/=</code>, <code>%=</code>, <code>//=</code>
|
|
<a href="#arithmetic-update-assignment" class="icon-link" aria-label="Link to this section: Arithmetic update-assignment: `+=`, `-=`, `*=`, `/=`, `%=`, `//=`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example107" aria-expanded="false" aria-controls="example107">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Example
|
|
</button>
|
|
<div id="example107" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.foo += 1'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"foo": 42}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"foo": 43}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.foo%20%2B%3D%201&j=%7B%22foo%22%3A%2042%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="plain-assignment">
|
|
<h3>
|
|
Plain assignment: <code>=</code>
|
|
<a href="#plain-assignment" class="icon-link" aria-label="Link to this section: Plain assignment: `=`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 class="pb-3">
|
|
<button type="button" class="btn btn-sm btn-secondary text-body-secondary bg-transparent link-body-emphasis border-0" data-bs-toggle="collapse" data-bs-target="#example108" aria-expanded="false" aria-controls="example108">
|
|
<span class="me-1 d-print-none" aria-hidden="true"><span class="bi bi-chevron-right"></span><span class="bi bi-chevron-down"></span></span>Examples
|
|
</button>
|
|
<div id="example108" class="collapse mx-3 small d-print-block">
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.a = .b'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a": {"b": 10}, "b": 20}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a":20,"b":20}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.a%20%3D%20.b&j=%7B%22a%22%3A%20%7B%22b%22%3A%2010%7D%2C%20%22b%22%3A%2020%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '.a |= .b'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">{"a": {"b": 10}, "b": 20}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a":10,"b":20}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=.a%20%7C%3D%20.b&j=%7B%22a%22%3A%20%7B%22b%22%3A%2010%7D%2C%20%22b%22%3A%2020%7D" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '(.a, .b) = range(3)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a":0,"b":0}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"a":1,"b":1}</td>
|
|
</tr>
|
|
<tr>
|
|
<th></th>
|
|
<td class="font-monospace">{"a":2,"b":2}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%28.a%2C%20.b%29%20%3D%20range%283%29&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
<table class="table table-borderless table-sm w-auto">
|
|
<tr>
|
|
<th class="pe-3">Command</th>
|
|
<td class="font-monospace">jq '(.a, .b) |= range(3)'</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Input</th>
|
|
<td class="font-monospace">null</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Output</th>
|
|
<td class="font-monospace">{"a":0,"b":0}</td>
|
|
</tr>
|
|
<tr class="d-print-none">
|
|
<th><a href="https://jqplay.org/jq?q=%28.a%2C%20.b%29%20%7C%3D%20range%283%29&j=null" class="btn btn-outline-primary btn-sm" target="_blank" rel="noopener">Run<span class="bi bi-box-arrow-up-right ms-2" aria-hidden="true"></span></a></th>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
<section id="complex-assignments">
|
|
<h3>
|
|
Complex assignments
|
|
<a href="#complex-assignments" class="icon-link" aria-label="Link to this section: Complex assignments"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 <a href="#modules" class="icon-link" aria-label="Link to this section: Modules"><span class="bi bi-link-45deg" aria-hidden="true"></span></a></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 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="import-relativepathstring-as-name">
|
|
<h3>
|
|
<code>import RelativePathString as NAME [<metadata>];</code>
|
|
<a href="#import-relativepathstring-as-name" class="icon-link" aria-label="Link to this section: `import RelativePathString as NAME [<metadata>];`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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="include-relativepathstring">
|
|
<h3>
|
|
<code>include RelativePathString [<metadata>];</code>
|
|
<a href="#include-relativepathstring" class="icon-link" aria-label="Link to this section: `include RelativePathString [<metadata>];`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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="import-relativepathstring-as-$name">
|
|
<h3>
|
|
<code>import RelativePathString as $NAME [<metadata>];</code>
|
|
<a href="#import-relativepathstring-as-$name" class="icon-link" aria-label="Link to this section: `import RelativePathString as $NAME [<metadata>];`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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>
|
|
<a href="#module-<metadata>" class="icon-link" aria-label="Link to this section: `module <metadata>;`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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>
|
|
<a href="#modulemeta" class="icon-link" aria-label="Link to this section: `modulemeta`"><span class="bi bi-link-45deg" aria-hidden="true"></span></a>
|
|
</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 and the module's defined
|
|
functions as an array value for the <code>defs</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 <a href="#colors" class="icon-link" aria-label="Link to this section: Colors"><span class="bi bi-link-45deg" aria-hidden="true"></span></a></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="0;90: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>
|
|
</main>
|
|
|
|
</div>
|
|
|
|
<footer class="bd-footer bg-body-tertiary">
|
|
<div class="py-3 text-center">
|
|
<p>
|
|
This website is made with <a href="https://getbootstrap.com" target="_blank" rel="noopener">Bootstrap</a>,
|
|
themed with <a href="https://bootswatch.com" target="_blank" rel="noopener">Bootswatch</a>.
|
|
</p>
|
|
<p>
|
|
jq is licensed under the MIT license (code) and the
|
|
<a href="https://creativecommons.org/licenses/by/3.0/" target="_blank" rel="noopener">CC-BY-3.0</a> license (docs).
|
|
</p>
|
|
</div>
|
|
</footer>
|
|
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.1/dist/js/bootstrap.bundle.min.js"
|
|
integrity="sha384-HwwvtgBNo3bZJJLYd8oVXjrBZt8cqVSpeBNS5n7C8IVInixGAoxmnlMuBnhbgrkm" crossorigin="anonymous"></script>
|
|
<script src="https://cdn.jsdelivr.net/npm/@tarekraafat/autocomplete.js@10.2.7/dist/autoComplete.min.js"
|
|
integrity="sha384-xbzjoN6H5XHmAqoSSR42hZVRninPGx85y+XZQGlWxVu2y91lTmr/oD80i5cjeUBv" crossorigin="anonymous"></script>
|
|
<script id="section-ids" type="application/json">
|
|
{
|
|
"Invoking jq": "invoking-jq",
|
|
"Identity: .": "identity",
|
|
"Object Identifier-Index: .foo, .foo.bar": "object-identifier-index",
|
|
"Optional Object Identifier-Index: .foo?": "optional-object-identifier-index",
|
|
"Object Index: .[\u003cstring\u003e]": "object-index",
|
|
"Array Index: .[\u003cnumber\u003e]": "array-index",
|
|
"Array/String Slice: .[\u003cnumber\u003e:\u003cnumber\u003e]": "array-string-slice",
|
|
"Array/Object Value Iterator: .[]": "array-object-value-iterator",
|
|
".[]?": ".[]?",
|
|
"Comma: ,": "comma",
|
|
"Pipe: |": "pipe",
|
|
"Parenthesis": "parenthesis",
|
|
"Basic filters": "basic-filters",
|
|
"Array construction: []": "array-construction",
|
|
"Object Construction: {}": "object-construction",
|
|
"Recursive Descent: ..": "recursive-descent",
|
|
"Types and Values": "types-and-values",
|
|
"Addition: +": "addition",
|
|
"Subtraction: -": "subtraction",
|
|
"Multiplication, division, modulo: *, /, %": "multiplication-division-modulo",
|
|
"abs": "abs",
|
|
"length": "length",
|
|
"utf8bytelength": "utf8bytelength",
|
|
"keys, keys_unsorted": "keys-keys_unsorted",
|
|
"has(key)": "has",
|
|
"in": "in",
|
|
"map(f), map_values(f)": "map-map_values",
|
|
"pick(pathexps)": "pick",
|
|
"path(path_expression)": "path",
|
|
"del(path_expression)": "del",
|
|
"getpath(PATHS)": "getpath",
|
|
"setpath(PATHS; VALUE)": "setpath",
|
|
"delpaths(PATHS)": "delpaths",
|
|
"to_entries, from_entries, with_entries(f)": "to_entries-from_entries-with_entries",
|
|
"select(boolean_expression)": "select",
|
|
"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",
|
|
"halt": "halt",
|
|
"halt_error, halt_error(exit_code)": "halt_error",
|
|
"$__loc__": "$__loc__",
|
|
"paths, paths(node_filter)": "paths",
|
|
"add": "add",
|
|
"any, any(condition), any(generator; condition)": "any",
|
|
"all, all(condition), all(generator; condition)": "all",
|
|
"flatten, flatten(depth)": "flatten",
|
|
"range(upto), range(from; upto), range(from; upto; by)": "range",
|
|
"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",
|
|
"group_by(path_expression)": "group_by",
|
|
"min, max, min_by(path_exp), max_by(path_exp)": "min-max-min_by-max_by",
|
|
"unique, unique_by(path_exp)": "unique-unique_by",
|
|
"reverse": "reverse",
|
|
"contains(element)": "contains",
|
|
"indices(s)": "indices",
|
|
"index(s), rindex(s)": "index-rindex",
|
|
"inside": "inside",
|
|
"startswith(str)": "startswith",
|
|
"endswith(str)": "endswith",
|
|
"combinations, combinations(n)": "combinations",
|
|
"ltrimstr(str)": "ltrimstr",
|
|
"rtrimstr(str)": "rtrimstr",
|
|
"explode": "explode",
|
|
"implode": "implode",
|
|
"split(str)": "split-1",
|
|
"join(str)": "join",
|
|
"ascii_downcase, ascii_upcase": "ascii_downcase-ascii_upcase",
|
|
"while(cond; update)": "while",
|
|
"repeat(exp)": "repeat",
|
|
"until(cond; next)": "until",
|
|
"recurse(f), recurse, recurse(f; condition)": "recurse",
|
|
"walk(f)": "walk",
|
|
"$JQ_BUILD_CONFIGURATION": "$jq_build_configuration",
|
|
"$ENV, env": "$env-env",
|
|
"transpose": "transpose",
|
|
"bsearch(x)": "bsearch",
|
|
"String interpolation: \\(exp)": "string-interpolation",
|
|
"Convert to/from JSON": "convert-to-from-json",
|
|
"Format strings and escaping": "format-strings-and-escaping",
|
|
"Dates": "dates",
|
|
"SQL-Style Operators": "sql-style-operators",
|
|
"builtins": "builtins",
|
|
"Builtin operators and functions": "builtin-operators-and-functions",
|
|
"==, !=": "==-!=",
|
|
"if-then-else-end": "if-then-else-end",
|
|
"\u003e, \u003e=, \u003c=, \u003c": "\u003e-\u003e=-\u003c=-\u003c",
|
|
"and, or, not": "and-or-not",
|
|
"Alternative operator: //": "alternative-operator",
|
|
"try-catch": "try-catch",
|
|
"Breaking out of control structures": "breaking-out-of-control-structures",
|
|
"Error Suppression / Optional Operator: ?": "error-suppression-optional-operator",
|
|
"Conditionals and Comparisons": "conditionals-and-comparisons",
|
|
"test(val), test(regex; flags)": "test",
|
|
"match(val), match(regex; flags)": "match",
|
|
"capture(val), capture(regex; flags)": "capture",
|
|
"scan(regex), scan(regex; flags)": "scan",
|
|
"split(regex; flags)": "split-2",
|
|
"splits(regex), splits(regex; flags)": "splits",
|
|
"sub(regex; tostring), sub(regex; tostring; flags)": "sub",
|
|
"gsub(regex; tostring), gsub(regex; tostring; flags)": "gsub",
|
|
"Regular expressions": "regular-expressions",
|
|
"Variable / Symbolic Binding Operator: ... as $identifier | ...": "variable-symbolic-binding-operator",
|
|
"Destructuring Alternative Operator: ?//": "destructuring-alternative-operator",
|
|
"Defining Functions": "defining-functions",
|
|
"Scoping": "scoping",
|
|
"isempty(exp)": "isempty",
|
|
"limit(n; exp)": "limit",
|
|
"first(expr), last(expr), nth(n; expr)": "first-last-nth-2",
|
|
"first, last, nth(n)": "first-last-nth-1",
|
|
"reduce": "reduce",
|
|
"foreach": "foreach",
|
|
"Recursion": "recursion",
|
|
"Generators and iterators": "generators-and-iterators",
|
|
"Advanced features": "advanced-features",
|
|
"Math": "math",
|
|
"input": "input",
|
|
"inputs": "inputs",
|
|
"debug, debug(msgs)": "debug",
|
|
"stderr": "stderr",
|
|
"input_filename": "input_filename",
|
|
"input_line_number": "input_line_number",
|
|
"I/O": "io",
|
|
"truncate_stream(stream_expression)": "truncate_stream",
|
|
"fromstream(stream_expression)": "fromstream",
|
|
"tostream": "tostream",
|
|
"Streaming": "streaming",
|
|
"Update-assignment: |=": "update-assignment",
|
|
"Arithmetic update-assignment: +=, -=, *=, /=, %=, //=": "arithmetic-update-assignment",
|
|
"Plain assignment: =": "plain-assignment",
|
|
"Complex assignments": "complex-assignments",
|
|
"Assignment": "assignment",
|
|
"import RelativePathString as NAME [\u003cmetadata\u003e];": "import-relativepathstring-as-name",
|
|
"include RelativePathString [\u003cmetadata\u003e];": "include-relativepathstring",
|
|
"import RelativePathString as $NAME [\u003cmetadata\u003e];": "import-relativepathstring-as-$name",
|
|
"module \u003cmetadata\u003e;": "module-\u003cmetadata\u003e",
|
|
"modulemeta": "modulemeta",
|
|
"Modules": "modules",
|
|
"Colors": "colors"
|
|
}
|
|
</script>
|
|
<script src="/jq/js/manual-search.js"></script>
|
|
</body>
|
|
</html> |