diff options
Diffstat (limited to 'manual/v1.6/index.html')
| -rw-r--r-- | manual/v1.6/index.html | 7532 |
1 files changed, 7532 insertions, 0 deletions
diff --git a/manual/v1.6/index.html b/manual/v1.6/index.html new file mode 100644 index 00000000..247188a3 --- /dev/null +++ b/manual/v1.6/index.html @@ -0,0 +1,7532 @@ +<!DOCTYPE html> +<html lang="en"> + <head> + <script> + if ((window.location.host == "stedolan.github.io") && (window.location.protocol != "https:")) + window.location.protocol = "https"; + </script> + <meta charset="utf-8"> + <title>jq Manual (development version)</title> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <meta http-equiv="X-UA-Compatible" content="IE=edge" /> + <link rel="canonical" href="https://stedolan.github.io/jq/manual/v1.6/" /> + <link href="https://maxcdn.bootstrapcdn.com/bootswatch/3.3.5/spacelab/bootstrap.min.css" rel="stylesheet" integrity="sha256-j7Dtnd7ZjexEiPNbscbopFn9+Cs0b3TLipKsWAPHZIM= sha512-RFhfi6P8zWMAJrEGU+CPjuxPh3r/UUBGqQ+/o6WKPIVZmQqeOipGotH2ihRULuQ8wsMBoK15TSZqc/7VYWyuIw==" crossorigin="anonymous"> + <link rel="stylesheet" href="/jq/css/base.css" type="text/css"> + <!--[if lt IE 9]> + <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script> + <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script> + <![endif]--> + </head> + + + <body id="v1.6" data-spy="scroll" data-target="#navcolumn" data-offset="100"> + <div class="navbar navbar-default navbar-fixed-top" role="navigation"> + <div class="container"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#nav-collapse"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <a class="navbar-brand" href="/jq/">jq</a> + </div> + + <div class="navbar-collapse collapse" id="nav-collapse"> + <ul class="nav navbar-nav"> + + <li > + <a href="/jq/tutorial/">Tutorial</a> + </li> + + <li > + <a href="/jq/download/">Download</a> + </li> + + <li > + <a href="/jq/manual/">Manual</a> + </li> + + <li><a href="https://github.com/stedolan/jq/issues">Issues</a></li> + <li><a href="https://github.com/stedolan/jq">Source</a></li> + <li><a href="https://jqplay.org">Try online!</a></li> + <li><a href="https://raw.githubusercontent.com/stedolan/jq/master/NEWS">News</a></li> + </ul> + </div> + </div> + </div> + + + <div class="container"> + <div class="row"> + <div class="affix" id="navcolumn"> + <h4>Contents</h4> + <ul class="nav nav-pills nav-stacked"> + + <li> + <a href="#Invokingjq">Invoking jq</a> + </li> + + <li> + <a href="#Basicfilters">Basic filters</a> + </li> + + <li> + <a href="#TypesandValues">Types and Values</a> + </li> + + <li> + <a href="#Builtinoperatorsandfunctions">Builtin operators and functions</a> + </li> + + <li> + <a href="#ConditionalsandComparisons">Conditionals and Comparisons</a> + </li> + + <li> + <a href="#RegularexpressionsPCRE">Regular expressions (PCRE)</a> + </li> + + <li> + <a href="#Advancedfeatures">Advanced features</a> + </li> + + <li> + <a href="#Math">Math</a> + </li> + + <li> + <a href="#IO">I/O</a> + </li> + + <li> + <a href="#Streaming">Streaming</a> + </li> + + <li> + <a href="#Assignment">Assignment</a> + </li> + + <li> + <a href="#Modules">Modules</a> + </li> + + <li> + <a href="#Colors">Colors</a> + </li> + + </ul> + <form class="form-group" onsubmit="go_to_section(); return false;"> + <input type="text" + class="form-control" + placeholder="Search" + autocomplete="off" + id="searchbox"> + </form> + </div> + + <div id="manualcontent"> + <h1>jq Manual (development version)</h1> + <p><em>For released versions, see <a href='/jq/manual/v1.5'>jq 1.5</a>, +<a href='/jq/manual/v1.4'>jq 1.4</a> or <a href='/jq/manual/v1.3'>jq 1.3</a>.</em></p> + <p>A jq program is a “filter”: it takes an input, and produces an +output. There are a lot of builtin filters for extracting a +particular field of an object, or converting a number to a string, +or various other standard tasks.</p><p>Filters can be combined in various ways - you can pipe the output of +one filter into another filter, or collect the output of a filter +into an array.</p><p>Some filters produce multiple results, for instance there’s one that +produces all the elements of its input array. Piping that filter +into a second runs the second filter for each element of the +array. Generally, things that would be done with loops and iteration +in other languages are just done by gluing filters together in jq.</p><p>It’s important to remember that every filter has an input and an +output. Even literals like “hello” or 42 are filters - they take an +input but always produce the same literal as output. Operations that +combine two filters, like addition, generally feed the same input to +both and combine the results. So, you can implement an averaging +filter as <code>add / length</code> - feeding the input array both to the <code>add</code> +filter and the <code>length</code> filter and then performing the division.</p><p>But that’s getting ahead of ourselves. :) Let’s start with something +simpler:</p> + + <section id="Invokingjq"> + <h2>Invoking jq</h2> + +<p>jq filters run on a stream of JSON data. The input to jq is parsed as a sequence of whitespace-separated JSON values which are passed through the provided filter one at a time. The output(s) of the filter are written to standard out, again as a sequence of whitespace-separated JSON data.</p> + +<p>Note: it is important to mind the shell’s quoting rules. As a general rule it’s best to always quote (with single-quote characters) the jq program, as too many characters with special meaning to jq are also shell meta-characters. For example, <code>jq +"foo"</code> will fail on most Unix shells because that will be the same as <code>jq foo</code>, which will generally fail because <code>foo is not +defined</code>. When using the Windows command shell (cmd.exe) it’s best to use double quotes around your jq program when given on the command-line (instead of the <code>-f program-file</code> option), but then double-quotes in the jq program need backslash escaping.</p> + +<p>You can affect how jq reads and writes its input and output using some command-line options:</p> + +<ul> +<li> +<p><code>--version</code>:</p> + +<p>Output the jq version and exit with zero.</p> +</li> + +<li> +<p><code>--seq</code>:</p> + +<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> +</li> + +<li> +<p><code>--stream</code>:</p> + +<p>Parse the input in streaming fashion, outputing 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>[[1,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> +</li> + +<li> +<p><code>--slurp</code>/<code>-s</code>:</p> + +<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> +</li> + +<li> +<p><code>--raw-input</code>/<code>-R</code>:</p> + +<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> +</li> + +<li> +<p><code>--null-input</code>/<code>-n</code>:</p> + +<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> +</li> + +<li> +<p><code>--compact-output</code> / <code>-c</code>:</p> + +<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> +</li> + +<li> +<p><code>--tab</code>:</p> + +<p>Use a tab for each indentation level instead of two spaces.</p> +</li> + +<li> +<p><code>--indent n</code>:</p> + +<p>Use the given number of spaces (no more than 8) for indentation.</p> +</li> + +<li> +<p><code>--color-output</code> / <code>-C</code> and <code>--monochrome-output</code> / <code>-M</code>:</p> + +<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>.</p> + +<p>Colors can be configured with the <code>JQ_COLORS</code> environment variable (see below).</p> +</li> + +<li> +<p><code>--ascii-output</code> / <code>-a</code>:</p> + +<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> +</li> + +<li> +<p><code>--unbuffered</code></p> + +<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> +</li> + +<li> +<p><code>--sort-keys</code> / <code>-S</code>:</p> + +<p>Output the fields of each object with the keys in sorted order.</p> +</li> + +<li> +<p><code>--raw-output</code> / <code>-r</code>:</p> + +<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> +</li> + +<li> +<p><code>--join-output</code> / <code>-j</code>:</p> + +<p>Like <code>-r</code> but jq won’t print a newline after each output.</p> +</li> + +<li> +<p><code>-f filename</code> / <code>--from-file filename</code>:</p> + +<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> +</li> + +<li> +<p><code>-Ldirectory</code> / <code>-L directory</code>:</p> + +<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> +</li> + +<li> +<p><code>-e</code> / <code>--exit-status</code>:</p> + +<p>Sets the exit status of jq to 0 if the last output values 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> +</li> + +<li> +<p><code>--arg name value</code>:</p> + +<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> +</li> + +<li> +<p><code>--argjson name JSON-text</code>:</p> + +<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> +</li> + +<li> +<p><code>--slurpfile variable-name filename</code>:</p> + +<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> +</li> + +<li> +<p><code>--rawfile variable-name filename</code>:</p> + +<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 texs in the file named <code>bar</code>.</p> +</li> + +<li> +<p><code>--argfile variable-name filename</code>:</p> + +<p>Do not use. Use <code>--slurpfile</code> instead.</p> + +<p>(This option is like <code>--slurpfile</code>, but when the file has just one text, then that is used, else an array of texts is used as in <code>--slurpfile</code>.)</p> +</li> + +<li> +<p><code>--args</code>:</p> + +<p>Remaining arguments are positional string arguments. These are available to the jq program as <code>$ARGS.positional[]</code>.</p> +</li> + +<li> +<p><code>--jsonargs</code>:</p> + +<p>Remaining arguments are positional JSON text arguments. These are available to the jq program as <code>$ARGS.positional[]</code>.</p> +</li> + +<li> +<p><code>--run-tests [filename]</code>:</p> + +<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 “%%FAIL”, 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> +</li> +</ul> + + + </section> + + <section id="Basicfilters"> + <h2>Basic filters</h2> + + + <section id="Identity:."> + <h3> + +Identity: <code>.</code> + + + </h3> + +<p>The absolute simplest filter is <code>.</code> . This is a filter that takes its input and produces it unchanged as output. That is, this is the identity operator.</p> + +<p>Since jq by default pretty-prints all output, this trivial program can be a useful way of formatting JSON output from, say, <code>curl</code>.</p> + + + + <div> + + <a data-toggle="collapse" href="#example1"> + <i class="glyphicon glyphicon-chevron-right"></i> + Example + </a> + <div id="example1" class="manual-example collapse"> + + <table> + <tr><th></th><td class="jqprogram">jq '.'</td></tr> + <tr><th>Input</th><td>"Hello, world!"</td></tr> + + + <tr> + + <th>Output</th> + + <td>"Hello, world!"</td> + </tr> + + </table> + + </div> + </div> + + </section> + + <section id="ObjectIdentifier-Index:.foo,.foo.bar"> + <h3> + +Object Identifier-Index: <code>.foo</code>, <code>.foo.bar</code> + + + </h3> + +<p>The simplest <em>useful</em> filter is <code>.foo</code>. When given a JSON object (aka dictionary or hash) as input, it produces the value at the key “foo”, or null if there’s none present.</p> + +<p>A filter of the form <code>.foo.bar</code> is equivalent to <code>.foo|.bar</code>.</p> + +<p>This syntax only works for simple, identifier-like keys, that is, keys that are all made of alphanumeric characters and underscore, and which do not start with a digit.</p> + +<p>If the key contains special characters, 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, and <code>.foo.bar</code> means <code>.["foo"].["bar"]</code>.</p> + + + + <div> + + <a data-toggle="collapse" href="#example2"> + <i class="glyphicon glyphicon-chevron-right"></i> + Examples + </a> + <div id="example2" class="manual-example collapse"> + + <table> + <tr><th></th><td class="jqprogram">jq '.foo'</td></tr> + <tr><th>Input</th><td>{"foo": 42, "bar": "less interesting data"}</td></tr> + + + <tr> + + <th>Output</th> + + <td>42</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '.foo'</td></tr> + <tr><th>Input</th><td>{"notfoo": true, "alsonotfoo": false}</td></tr> + + + <tr> + + <th>Output</th> + + <td>null</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '.["foo"]'</td></tr> + <tr><th>Input</th><td>{"foo": 42}</td></tr> + + + <tr> + + <th>Output</th> + + <td>42</td> + </tr> + + </table> + + </div> + </div> + + </section> + + <section id="OptionalObjectIdentifier-Index:.foo?"> + <h3> + +Optional Object Identifier-Index: <code>.foo?</code> + + + </h3> + +<p>Just like <code>.foo</code>, but does not output even an error when <code>.</code> is not an array or an object.</p> + + + + <div> + + <a data-toggle="collapse" href="#example3"> + <i class="glyphicon glyphicon-chevron-right"></i> + Examples + </a> + <div id="example3" class="manual-example collapse"> + + <table> + <tr><th></th><td class="jqprogram">jq '.foo?'</td></tr> + <tr><th>Input</th><td>{"foo": 42, "bar": "less interesting data"}</td></tr> + + + <tr> + + <th>Output</th> + + <td>42</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '.foo?'</td></tr> + <tr><th>Input</th><td>{"notfoo": true, "alsonotfoo": false}</td></tr> + + + <tr> + + <th>Output</th> + + <td>null</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '.["foo"]?'</td></tr> + <tr><th>Input</th><td>{"foo": 42}</td></tr> + + + <tr> + + <th>Output</th> + + <td>42</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '[.foo?]'</td></tr> + <tr><th>Input</th><td>[1,2]</td></tr> + + + <tr> + + <th>Output</th> + + <td>[]</td> + </tr> + + </table> + + </div> + </div> + + </section> + + <section id="GenericObjectIndex:.[<string>]"> + <h3> + +Generic Object Index: <code>.[<string>]</code> + + + </h3> + +<p>You can also look up fields of an object using syntax like <code>.["foo"]</code> (.foo above is a shorthand version of this, but only for identifier-like strings).</p> + + + + </section> + + <section id="ArrayIndex:.[2]"> + <h3> + +Array Index: <code>.[2]</code> + + + </h3> + +<p>When the index value is an integer, <code>.[<value>]</code> can index arrays. Arrays are zero-based, so <code>.[2]</code> returns the third element.</p> + +<p>Negative indices are allowed, with -1 referring to the last element, -2 referring to the next to last element, and so on.</p> + + + + <div> + + <a data-toggle="collapse" href="#example4"> + <i class="glyphicon glyphicon-chevron-right"></i> + Examples + </a> + <div id="example4" class="manual-example collapse"> + + <table> + <tr><th></th><td class="jqprogram">jq '.[0]'</td></tr> + <tr><th>Input</th><td>[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]</td></tr> + + + <tr> + + <th>Output</th> + + <td>{"name":"JSON", "good":true}</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '.[2]'</td></tr> + <tr><th>Input</th><td>[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]</td></tr> + + + <tr> + + <th>Output</th> + + <td>null</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '.[-2]'</td></tr> + <tr><th>Input</th><td>[1,2,3]</td></tr> + + + <tr> + + <th>Output</th> + + <td>2</td> + </tr> + + </table> + + </div> + </div> + + </section> + + <section id="Array/StringSlice:.[10:15]"> + <h3> + +Array/String Slice: <code>.[10:15]</code> + + + </h3> + +<p>The <code>.[10:15]</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).</p> + + + + <div> + + <a data-toggle="collapse" href="#example5"> + <i class="glyphicon glyphicon-chevron-right"></i> + Examples + </a> + <div id="example5" class="manual-example collapse"> + + <table> + <tr><th></th><td class="jqprogram">jq '.[2:4]'</td></tr> + <tr><th>Input</th><td>["a","b","c","d","e"]</td></tr> + + + <tr> + + <th>Output</th> + + <td>["c", "d"]</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '.[2:4]'</td></tr> + <tr><th>Input</th><td>"abcdefghi"</td></tr> + + + <tr> + + <th>Output</th> + + <td>"cd"</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '.[:3]'</td></tr> + <tr><th>Input</th><td>["a","b","c","d","e"]</td></tr> + + + <tr> + + <th>Output</th> + + <td>["a", "b", "c"]</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '.[-2:]'</td></tr> + <tr><th>Input</th><td>["a","b","c","d","e"]</td></tr> + + + <tr> + + <th>Output</th> + + <td>["d", "e"]</td> + </tr> + + </table> + + </div> + </div> + + </section> + + <section id="Array/ObjectValueIterator:.[]"> + <h3> + +Array/Object Value Iterator: <code>.[]</code> + + + </h3> + +<p>If you use the <code>.[index]</code> syntax, but omit the index entirely, it will return <em>all</em> of the elements of an array. Running <code>.[]</code> with the input <code>[1,2,3]</code> will produce the numbers as three separate results, rather than as a single array.</p> + +<p>You can also use this on an object, and it will return all the values of the object.</p> + + + + <div> + + <a data-toggle="collapse" href="#example6"> + <i class="glyphicon glyphicon-chevron-right"></i> + Examples + </a> + <div id="example6" class="manual-example collapse"> + + <table> + <tr><th></th><td class="jqprogram">jq '.[]'</td></tr> + <tr><th>Input</th><td>[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]</td></tr> + + + <tr> + + <th>Output</th> + + <td>{"name":"JSON", "good":true}</td> + </tr> + + <tr> + + <th></th> + + <td>{"name":"XML", "good":false}</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '.[]'</td></tr> + <tr><th>Input</th><td>[]</td></tr> + + <tr> + <th>Output</th> + <td><i>none</i></td> + </tr> + + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '.[]'</td></tr> + <tr><th>Input</th><td>{"a": 1, "b": 1}</td></tr> + + + <tr> + + <th>Output</th> + + <td>1</td> + </tr> + + <tr> + + <th></th> + + <td>1</td> + </tr> + |