diff options
Diffstat (limited to 'manual/v1.5/index.html')
| -rw-r--r-- | manual/v1.5/index.html | 737 |
1 files changed, 512 insertions, 225 deletions
diff --git a/manual/v1.5/index.html b/manual/v1.5/index.html index 34425aad..84be4c69 100644 --- a/manual/v1.5/index.html +++ b/manual/v1.5/index.html @@ -150,8 +150,8 @@ simpler:</p> <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> +output(s) of the filter are written to standard output, as a +sequence of newline-separated JSON data.</p> <p>Note: it is important to mind the shell's quoting rules. As a general rule it's best to always quote (with single-quote characters) the jq program, as too many characters with special @@ -519,16 +519,15 @@ object.</p> </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). This -one works for arrays as well, if the key is an -integer. Arrays are zero-based (like javascript), so <code>.[2]</code> -returns the third element of the array.</p> +one works for arrays as well, if the key is an integer. Arrays +are zero-based, so <code>.[2]</code> returns the third element of the array.</p> <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> +or end of the array). Indices are zero-based.</p> <p>The <code>.[2]</code> syntax can be used to return the element at the given index. Negative indices are allowed, with -1 referring to the last element, -2 referring to the next to last element, @@ -663,7 +662,8 @@ slice-able.</p> 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> +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> @@ -710,6 +710,34 @@ the values of the object.</p> </table> <table> + <tr><th></th><td class="jqprogram">jq '.foo[]'</td></tr> + <tr><th>Input</th><td>{"foo":[1,2,3]}</td></tr> + + + <tr> + + <th>Output</th> + + <td>1</td> + </tr> + + <tr> + + <th></th> + + <td>2</td> + </tr> + + <tr> + + <th></th> + + <td>3</td> + </tr> + + </table> + + <table> <tr><th></th><td class="jqprogram">jq '.[]'</td></tr> <tr><th>Input</th><td>{"a": 1, "b": 1}</td></tr> @@ -741,7 +769,8 @@ the values of the object.</p> </h3> <p>Like <code>.[]</code>, but no errors will be output if . is not an array -or object.</p> +or object. A filter of the form <code>.foo[]?</code> is equivalent to +<code>.foo | .[]?</code>.</p> </section> @@ -899,7 +928,7 @@ element of the input array.</p> 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 javascript. Just like everything else in jq, these simple +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> @@ -1890,16 +1919,58 @@ non-iterables, respectively.</p> </section> - <section id="error(message)"> + <section id="error,error(message)"> <h3> - <code>error(message)</code> + <code>error</code>, <code>error(message)</code> </h3> - <p>Produces an error, just like <code>.a</code> applied to values other than -null and objects would, but with the given message as the -error's value.</p> + <p>Produces an error with the input value, or with the message +given as the argument. Errors can be caught with try/catch; +see below.</p> +<p>When the error value is <code>null</code>, it produces nothing and works +just like <code>empty</code>. So <code>[null | error]</code> and <code>[error(null)]</code> both +emit <code>[]</code>.</p> + <div> + + <a data-toggle="collapse" href="#example23"> + <i class="glyphicon glyphicon-chevron-right"></i> + Examples + </a> + <div id="example23" class="manual-example collapse"> + + <table> + <tr><th></th><td class="jqprogram">jq 'try error catch .'</td></tr> + <tr><th>Input</th><td>"error message"</td></tr> + + + <tr> + + <th>Output</th> + + <td>"error message"</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq 'try error("invalid value: \(.)") catch .'</td></tr> + <tr><th>Input</th><td>42</td></tr> + + + <tr> + + <th>Output</th> + + <td>"invalid value: 42"</td> + </tr> + + </table> + + </div> + </div> + </section> <section id="$__loc__"> @@ -1914,11 +1985,11 @@ values.</p> <div> - <a data-toggle="collapse" href="#example23"> + <a data-toggle="collapse" href="#example24"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example23" class="manual-example collapse"> + <div id="example24" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'try error("\($__loc__)") catch .'</td></tr> @@ -1955,11 +2026,11 @@ it's defined. Similarly, <code>map_values(f)</code> is defined as <code>.[] |= f <div> - <a data-toggle="collapse" href="#example24"> + <a data-toggle="collapse" href="#example25"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example24" class="manual-example collapse"> + <div id="example25" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'map(.+1)'</td></tr> @@ -2011,11 +2082,11 @@ values.</p> <div> - <a data-toggle="collapse" href="#example25"> + <a data-toggle="collapse" href="#example26"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example25" class="manual-example collapse"> + <div id="example26" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '[paths]'</td></tr> @@ -2065,11 +2136,11 @@ as those for the <code>+</code> operator (described above).</p> <div> - <a data-toggle="collapse" href="#example26"> + <a data-toggle="collapse" href="#example27"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example26" class="manual-example collapse"> + <div id="example27" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'add'</td></tr> @@ -2135,11 +2206,11 @@ condition to all the outputs of the given generator.</p> <div> - <a data-toggle="collapse" href="#example27"> + <a data-toggle="collapse" href="#example28"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example27" class="manual-example collapse"> + <div id="example28" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'any'</td></tr> @@ -2205,11 +2276,11 @@ condition to all the outputs of the given generator.</p> <div> - <a data-toggle="collapse" href="#example28"> + <a data-toggle="collapse" href="#example29"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example28" class="manual-example collapse"> + <div id="example29" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'all'</td></tr> @@ -2273,11 +2344,11 @@ levels deep.</p> <div> - <a data-toggle="collapse" href="#example29"> + <a data-toggle="collapse" href="#example30"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example29" class="manual-example collapse"> + <div id="example30" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'flatten'</td></tr> @@ -2340,9 +2411,9 @@ levels deep.</p> </section> - <section id="range(upto),range(from;upto)range(from;upto;by)"> + <section id="range(upto),range(from;upto),range(from;upto;by)"> <h3> - <code>range(upto)</code>, <code>range(from; upto)</code> <code>range(from; upto; by)</code> + <code>range(upto)</code>, <code>range(from; upto)</code>, <code>range(from; upto; by)</code> </h3> <p>The <code>range</code> function produces a range of numbers. <code>range(4; 10)</code> @@ -2359,11 +2430,11 @@ with an increment of <code>by</code>.</p> <div> - <a data-toggle="collapse" href="#example30"> + <a data-toggle="collapse" href="#example31"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example30" class="manual-example collapse"> + <div id="example31" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'range(2; 4)'</td></tr> @@ -2471,11 +2542,11 @@ with an increment of <code>by</code>.</p> <div> - <a data-toggle="collapse" href="#example31"> + <a data-toggle="collapse" href="#example32"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example31" class="manual-example collapse"> + <div id="example32" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'floor'</td></tr> @@ -2506,11 +2577,11 @@ with an increment of <code>by</code>.</p> <div> - <a data-toggle="collapse" href="#example32"> + <a data-toggle="collapse" href="#example33"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example32" class="manual-example collapse"> + <div id="example33" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'sqrt'</td></tr> @@ -2543,11 +2614,11 @@ equivalent, leave numbers alone, and give an error on all other input.</p> <div> - <a data-toggle="collapse" href="#example33"> + <a data-toggle="collapse" href="#example34"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example33" class="manual-example collapse"> + <div id="example34" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '.[] | tonumber'</td></tr> @@ -2587,11 +2658,11 @@ JSON-encoded.</p> <div> - <a data-toggle="collapse" href="#example34"> + <a data-toggle="collapse" href="#example35"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example34" class="manual-example collapse"> + <div id="example35" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '.[] | tostring'</td></tr> @@ -2638,11 +2709,11 @@ or object.</p> <div> - <a data-toggle="collapse" href="#example35"> + <a data-toggle="collapse" href="#example36"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example35" class="manual-example collapse"> + <div id="example36" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'map(type)'</td></tr> @@ -2682,11 +2753,11 @@ NaNs, and sub-normals do not raise errors.</p> <div> - <a data-toggle="collapse" href="#example36"> + <a data-toggle="collapse" href="#example37"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example36" class="manual-example collapse"> + <div id="example37" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '.[] | (infinite * .) < 0'</td></tr> @@ -2755,19 +2826,21 @@ array. Values are sorted in the following order:</p> 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</code> may be used to sort by a particular field of an -object, or by applying any jq filter.</p> -<p><code>sort_by(f)</code> compares two elements by comparing the result of -<code>f</code> on each element.</p> +<p><code>sort_by</code> may be used to sort by a particular field of an +object, or by applying any jq filter. <code>sort_by(f)</code> compares +two elements by comparing the result of <code>f</code> on each element. +When <code>f</code> produces multiple values, it firstly compares the +first values, and the second values if the first values are +equal, and so on.</p> <div> - <a data-toggle="collapse" href="#example37"> + <a data-toggle="collapse" href="#example38"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example37" class="manual-example collapse"> + <div id="example38" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'sort'</td></tr> @@ -2785,14 +2858,28 @@ object, or by applying any jq filter.</p> <table> <tr><th></th><td class="jqprogram">jq 'sort_by(.foo)'</td></tr> - <tr><th>Input</th><td>[{"foo":4, "bar":10}, {"foo":3, "bar":100}, {"foo":2, "bar":1}]</td></tr> + <tr><th>Input</th><td>[{"foo":4, "bar":10}, {"foo":3, "bar":10}, {"foo":2, "bar":1}]</td></tr> + + + <tr> + + <th>Output</th> + + <td>[{"foo":2, "bar":1}, {"foo":3, "bar":10}, {"foo":4, "bar":10}]</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq 'sort_by(.foo, .bar)'</td></tr> + <tr><th>Input</th><td>[{"foo":4, "bar":10}, {"foo":3, "bar":20}, {"foo":2, "bar":1}, {"foo":3, "bar":10}]</td></tr> <tr> <th>Output</th> - <td>[{"foo":2, "bar":1}, {"foo":3, "bar":100}, {"foo":4, "bar":10}]</td> + <td>[{"foo":2, "bar":1}, {"foo":3, "bar":10}, {"foo":3, "bar":20}, {"foo":4, "bar":10}]</td> </tr> </table> @@ -2818,11 +2905,11 @@ in the <code>sort</code> function above.</p> <div> - <a data-toggle="collapse" href="#example38"> + <a data-toggle="collapse" href="#example39"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example38" class="manual-example collapse"> + <div id="example39" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'group_by(.foo)'</td></tr> @@ -2856,11 +2943,11 @@ you to specify a particular field or property to examine, e.g. <div> - <a data-toggle="collapse" href="#example39"> + <a data-toggle="collapse" href="#example40"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example39" class="manual-example collapse"> + <div id="example40" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'min'</td></tr> @@ -2911,11 +2998,11 @@ produced by <code>group</code>.</p> <div> - <a data-toggle="collapse" href="#example40"> + <a data-toggle="collapse" href="#example41"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example40" class="manual-example collapse"> + <div id="example41" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'unique'</td></tr> @@ -2974,11 +3061,11 @@ produced by <code>group</code>.</p> <div> - <a data-toggle="collapse" href="#example41"> + <a data-toggle="collapse" href="#example42"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example41" class="manual-example collapse"> + <div id="example42" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'reverse'</td></tr> @@ -3016,11 +3103,11 @@ be contained in each other if they are equal.</p> <div> - <a data-toggle="collapse" href="#example42"> + <a data-toggle="collapse" href="#example43"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example42" class="manual-example collapse"> + <div id="example43" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'contains("bar")'</td></tr> @@ -3110,11 +3197,11 @@ in <code>.</code> match those of <code>s</code>.</p> <div> - <a data-toggle="collapse" href="#example43"> + <a data-toggle="collapse" href="#example44"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example43" class="manual-example collapse"> + <div id="example44" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'indices(", ")'</td></tr> @@ -3174,11 +3261,11 @@ occurrence of <code>s</code> in the input.</p> <div> - <a data-toggle="collapse" href="#example44"> + <a data-toggle="collapse" href="#example45"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example44" class="manual-example collapse"> + <div id="example45" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'index(", ")'</td></tr> @@ -3195,6 +3282,34 @@ occurrence of <code>s</code> in the input.</p> </table> <table> + <tr><th></th><td class="jqprogram">jq 'index(1)'</td></tr> + <tr><th>Input</th><td>[0,1,2,1,3,1,4]</td></tr> + + + <tr> + + <th>Output</th> + + <td>1</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq 'index([1,2])'</td></tr> + <tr><th>Input</th><td>[0,1,2,3,1,4,2,5,1,2,6,7]</td></tr> + + + <tr> + + <th>Output</th> + + <td>1</td> + </tr> + + </table> + + <table> <tr><th></th><td class="jqprogram">jq 'rindex(", ")'</td></tr> <tr><th>Input</th><td>"a,b, cd, efg, hijk"</td></tr> @@ -3208,6 +3323,34 @@ occurrence of <code>s</code> in the input.</p> </table> + <table> + <tr><th></th><td class="jqprogram">jq 'rindex(1)'</td></tr> + <tr><th>Input</th><td>[0,1,2,1,3,1,4]</td></tr> + + + <tr> + + <th>Output</th> + + <td>5</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq 'rindex([1,2])'</td></tr> + <tr><th>Input</th><td>[0,1,2,3,1,4,2,5,1,2,6,7]</td></tr> + + + <tr> + + <th>Output</th> + + <td>8</td> + </tr> + + </table> + </div> </div> @@ -3225,11 +3368,11 @@ inversed version of <code>contains</code>.</p> <div> - <a data-toggle="collapse" href="#example45"> + <a data-toggle="collapse" href="#example46"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example45" class="manual-example collapse"> + <div id="example46" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'inside("foobar")'</td></tr> @@ -3316,11 +3459,11 @@ inversed version of <code>contains</code>.</p> <div> - <a data-toggle="collapse" href="#example46"> + <a data-toggle="collapse" href="#example47"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example46" class="manual-example collapse"> + <div id="example47" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '[.[]|startswith("foo")]'</td></tr> @@ -3351,11 +3494,11 @@ inversed version of <code>contains</code>.</p> <div> - <a data-toggle="collapse" href="#example47"> + <a data-toggle="collapse" href="#example48"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example47" class="manual-example collapse"> + <div id="example48" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '[.[]|endswith("foo")]'</td></tr> @@ -3388,11 +3531,11 @@ of <code>n</code> repetitions of the input array.</p> <div> - <a data-toggle="collapse" href="#example48"> + <a data-toggle="collapse" href="#example49"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example48" class="manual-example collapse"> + <div id="example49" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'combinations'</td></tr> @@ -3480,11 +3623,11 @@ starts with it.</p> <div> - <a data-toggle="collapse" href="#example49"> + <a data-toggle="collapse" href="#example50"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example49" class="manual-example collapse"> + <div id="example50" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '[.[]|ltrimstr("foo")]'</td></tr> @@ -3516,11 +3659,11 @@ ends with it.</p> <div> - <a data-toggle="collapse" href="#example50"> + <a data-toggle="collapse" href="#example51"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example50" class="manual-example collapse"> + <div id="example51" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '[.[]|rtrimstr("foo")]'</td></tr> @@ -3552,11 +3695,11 @@ codepoint numbers.</p> <div> - <a data-toggle="collapse" href="#example51"> + <a data-toggle="collapse" href="#example52"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example51" class="manual-example collapse"> + <div id="example52" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'explode'</td></tr> @@ -3587,11 +3730,11 @@ codepoint numbers.</p> <div> - <a data-toggle="collapse" href="#example52"> + <a data-toggle="collapse" href="#example53"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example52" class="manual-example collapse"> + <div id="example53" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'implode'</td></tr> @@ -3622,11 +3765,11 @@ codepoint numbers.</p> <div> - <a data-toggle="collapse" href="#example53"> + <a data-toggle="collapse" href="#example54"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example53" class="manual-example collapse"> + <div id="example54" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'split(", ")'</td></tr> @@ -3660,11 +3803,11 @@ returns said input string.</p> <div> - <a data-toggle="collapse" href="#example54"> + <a data-toggle="collapse" href="#example55"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example54" class="manual-example collapse"> + <div id="example |