diff options
Diffstat (limited to 'manual/index.html')
| -rw-r--r-- | manual/index.html | 287 |
1 files changed, 247 insertions, 40 deletions
diff --git a/manual/index.html b/manual/index.html index b3de11b1..f1abd39f 100644 --- a/manual/index.html +++ b/manual/index.html @@ -111,6 +111,10 @@ <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" @@ -123,8 +127,9 @@ <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><em>For released versions, see <a href='/jq/manual/v1.6'>jq 1.6</a>, +<a href='/jq/manual/v1.5'>jq 1.5</a>, <a href='/jq/manual/v1.4'>jq 1.4</a> +or <a href='/jq/manual/v1.3'>jq 1.3</a>.</em></p> <p>A jq program is a “filter”: it takes an input, and produces an output. There are a lot of builtin filters for extracting a particular field of an object, or converting a number to a string, @@ -215,6 +220,8 @@ defined</code>. When using the Windows command shell (cmd.exe) it’s best to us <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> @@ -284,7 +291,13 @@ defined</code>. When using the Windows command shell (cmd.exe) it’s best to us <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>--argfile 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> +<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> @@ -4875,7 +4888,7 @@ Dates <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 Greenwhich Meridian time as an array of numbers representing (in this order): the year, the month (zero-based), the day of the month, 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.</p> +<p>The <code>gmtime</code> builtin consumes a number of seconds since the Unix epoch and outputs a “broken down time” representation of Greenwhich Meridian time as an array of numbers representing (in this order): the year, the month (zero-based), the day of the month (one-based), the hour of the day, the minute of the hour, the second of the minute, the day of the week, and the day of the year – all one-based unless otherwise stated. The day of the week number may be wrong on some systems for dates before March 1st 1900, or after December 31 2099.</p> <p>The <code>localtime</code> builtin works like the <code>gmtime</code> builtin, but using the local timezone setting.</p> @@ -4887,7 +4900,7 @@ Dates <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.</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> @@ -5452,10 +5465,10 @@ try repeat(exp) catch .=="break" then empty else error;</code></pre> </section> - <section id="ErrorSuppresion/OptionalOperator:?"> + <section id="ErrorSuppression/OptionalOperator:?"> <h3> -Error Suppresion / Optional Operator: <code>?</code> +Error Suppression / Optional Operator: <code>?</code> </h3> @@ -6021,6 +6034,108 @@ Variable / Symbolic Binding Operator: <code>... as $identifier | ...</code> </section> + <section id="DestructuringAlternativeOperator:?//"> + <h3> + +Destructuring Alternative Operator: <code>?//</code> + + + </h3> + +<p>The destructuring alternative operator provides a concise mechanism for destructuring an input that can take one of several forms.</p> + +<p>Suppose we have an API that returns a list of resources and events associated with them, and we want to get the user_id and timestamp of the first event for each resource. The API (having been clumsily converted from XML) will only wrap the events in an array if the resource has multiple events:</p> + +<pre><code>{"resources": [{"id": 1, "kind": "widget", "events": {"action": "create", "user_id": 1, "ts": 13}}, + {"id": 2, "kind": "widget", "events": [{"action": "create", "user_id": 1, "ts": 14}, {"action": "destroy", "user_id": 1, "ts": 15}]}]}</code></pre> + +<p>We can use the destructuring alternative operator to handle this structural change simply:</p> + +<pre><code>.resources[] as {$id, $kind, events: {$user_id, $ts}} ?// {$id, $kind, events: [{$user_id, $ts}]} | {$user_id, $kind, $id, $ts}</code></pre> + +<p>Or, if we aren’t sure if the input is an array of values or an object:</p> + +<pre><code>.[] as [$id, $kind, $user_id, $ts] ?// {$id, $kind, $user_id, $ts} | ...</code></pre> + +<p>Each alternative need not define all of the same variables, but all named variables will be available to the subsequent expression. Variables not matched in the alternative that succeeded will be <code>null</code>:</p> + +<pre><code>.resources[] as {$id, $kind, events: {$user_id, $ts}} ?// {$id, $kind, events: [{$first_user_id, $first_ts}]} | {$user_id, $first_user_id, $kind, $id, $ts, $first_ts}</code></pre> + +<p>Additionally, if the subsequent expression returns an error, the alternative operator will attempt to try the next binding. Errors that occur during the final alternative are passed through.</p> + +<pre><code>[[3]] | .[] as [$a] ?// [$b] | if $a != null then error("err: \($a)") else {$a,$b} end</code></pre> + + + + <div> + + <a data-toggle="collapse" href="#example84"> + <i class="glyphicon glyphicon-chevron-right"></i> + Examples + </a> + <div id="example84" class="manual-example collapse"> + + <table> + <tr><th></th><td class="jqprogram">jq '.[] as {$a, $b, c: {$d, $e}} ?// {$a, $b, c: [{$d, $e}]} | {$a, $b, $d, $e}'</td></tr> + <tr><th>Input</th><td>[{"a": 1, "b": 2, "c": {"d": 3, "e": 4}}, {"a": 1, "b": 2, "c": [{"d": 3, "e": 4}]}]</td></tr> + + + <tr> + + <th>Output</th> + + <td>{"a":1,"b":2,"d":3,"e":4}</td> + </tr> + + <tr> + + <th></th> + + <td>{"a":1,"b":2,"d":3,"e":4}</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '.[] as {$a, $b, c: {$d}} ?// {$a, $b, c: [{$e}]} | {$a, $b, $d, $e}'</td></tr> + <tr><th>Input</th><td>[{"a": 1, "b": 2, "c": {"d": 3, "e": 4}}, {"a": 1, "b": 2, "c": [{"d": 3, "e": 4}]}]</td></tr> + + + <tr> + + <th>Output</th> + + <td>{"a":1,"b":2,"d":3,"e":null}</td> + </tr> + + <tr> + + <th></th> + + <td>{"a":1,"b":2,"d":null,"e":4}</td> + </tr> + + </table> + + <table> + <tr><th></th><td class="jqprogram">jq '.[] as [$a] ?// [$b] | if $a != null then error("err: \($a)") else {$a,$b} end'</td></tr> + <tr><th>Input</th><td>[[3]]</td></tr> + + + <tr> + + <th>Output</th> + + <td>{"a":null,"b":3}</td> + </tr> + + </table> + + </div> + </div> + + </section> + <section id="DefiningFunctions"> <h3> @@ -6060,11 +6175,11 @@ Defining Functions <div> - <a data-toggle="collapse" href="#example84"> + <a data-toggle="collapse" href="#example85"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example84" class="manual-example collapse"> + <div id="example85" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'def addvalue(f): . + [f]; map(addvalue(.[0]))'</td></tr> @@ -6135,18 +6250,15 @@ Reduce (2 as $item | . + $item) | (1 as $item | . + $item)</code></pre> -<p>If the reduction update expression outputs <code>empty</code> (that is, no values), then the reduction state is left as-is. For example, <code>reduce range(4) as $n ({}; if .==2 then empty else -.[$n|tostring] |= $n)</code> will produce <code>{"0":0,"1":1,"3":3}</code>.</p> - <div> - <a data-toggle="collapse" href="#example85"> + <a data-toggle="collapse" href="#example86"> <i class="glyphicon glyphicon-chevron-right"></i> - Examples + Example </a> - <div id="example85" class="manual-example collapse"> + <div id="example86" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'reduce .[] as $item (0; . + $item)'</td></tr> @@ -6162,16 +6274,41 @@ Reduce </table> + </div> + </div> + + </section> + + <section id="isempty(exp)"> + <h3> + +<code>isempty(exp)</code> + + + </h3> + +<p>Returns true if <code>exp</code> produces no outputs, false otherwise.</p> + + + + <div> + + <a data-toggle="collapse" href="#example87"> + <i class="glyphicon glyphicon-chevron-right"></i> + Example + </a> + <div id="example87" class="manual-example collapse"> + <table> - <tr><th></th><td class="jqprogram">jq 'reduce .[] as $n ([]; if $n%2==0 then empty else . + [$n] end)'</td></tr> - <tr><th>Input</th><td>[0,1,2,3,4,5]</td></tr> + <tr><th></th><td class="jqprogram">jq 'isempty(empty)'</td></tr> + <tr><th>Input</th><td>null</td></tr> <tr> <th>Output</th> - <td>[1,3,5]</td> + <td>true</td> </tr> </table> @@ -6195,11 +6332,11 @@ Reduce <div> - <a data-toggle="collapse" href="#example86"> + <a data-toggle="collapse" href="#example88"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example86" class="manual-example collapse"> + <div id="example88" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '[limit(3;.[])]'</td></tr> @@ -6237,11 +6374,11 @@ last(limit(n + 1; expr));</code>. Note that <code>nth(n; expr)</code> doesn’t <div> - <a data-toggle="collapse" href="#example87"> + <a data-toggle="collapse" href="#example89"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example87" class="manual-example collapse"> + <div id="example89" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '[first(range(.)), last(range(.)), nth(./2; range(.))]'</td></tr> @@ -6278,11 +6415,11 @@ last(limit(n + 1; expr));</code>. Note that <code>nth(n; expr)</code> doesn’t <div> - <a data-toggle="collapse" href="#example88"> + <a data-toggle="collapse" href="#example90"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example88" class="manual-example collapse"> + <div id="example90" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '[range(.)]|[first, last, nth(5)]'</td></tr> @@ -6321,11 +6458,11 @@ last(limit(n + 1; expr));</code>. Note that <code>nth(n; expr)</code> doesn’t <div> - <a data-toggle="collapse" href="#example89"> + <a data-toggle="collapse" href="#example91"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example89" class="manual-example collapse"> + <div id="example91" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '[foreach .[] as $item ([[],[]]; if $item == null then [[],.[0]] else [(.[0] + [$item]),[]] end; if $item == null then .[1] else empty end)]'</td></tr> @@ -6396,11 +6533,11 @@ Generators and iterators <div> - <a data-toggle="collapse" href="#example90"> + <a data-toggle="collapse" href="#example92"> <i class="glyphicon glyphicon-chevron-right"></i> Examples </a> - <div id="example90" class="manual-example collapse"> + <div id="example92" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'def range(init; upto; by): def _range: if (by > 0 and . < upto) or (by < 0 and . > upto) then ., ((.+by)|_range) else . end; if by == 0 then init else init|_range end | select((by > 0 and . < upto) or (by < 0 and . > upto)); range(0; 10; 3)'</td></tr> @@ -6604,11 +6741,11 @@ Generators and iterators <div> - <a data-toggle="collapse" href="#example91"> + <a data-toggle="collapse" href="#example93"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example91" class="manual-example collapse"> + <div id="example93" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '[1|truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]])]'</td></tr> @@ -6643,11 +6780,11 @@ Generators and iterators <div> - <a data-toggle="collapse" href="#example92"> + <a data-toggle="collapse" href="#example94"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example92" class="manual-example collapse"> + <div id="example94" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq 'fromstream(1|truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]]))'</td></tr> @@ -6682,11 +6819,11 @@ Generators and iterators <div> - <a data-toggle="collapse" href="#example93"> + <a data-toggle="collapse" href="#example95"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example93" class="manual-example collapse"> + <div id="example95" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '. as $dot|fromstream($dot|tostream)|.==$dot'</td></tr> @@ -6718,7 +6855,7 @@ Generators and iterators <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) procides values to set to the paths named by the LHS path expressions.</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> @@ -6753,11 +6890,11 @@ Update-assignment: <code>|=</code> <div> - <a data-toggle="collapse" href="#example94"> + <a data-toggle="collapse" href="#example96"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example94" class="manual-example collapse"> + <div id="example96" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '(..|select(type=="boolean")) |= if . then 1 else 0 end'</td></tr> @@ -6792,11 +6929,11 @@ Arithmetic update-assignment: <code>+=</code>, <code>-=</code>, <code>*=</code>, <div> - <a data-toggle="collapse" href="#example95"> + <a data-toggle="collapse" href="#example97"> <i class="glyphicon glyphicon-chevron-right"></i> Example </a> - <div id="example95" class="manual-example collapse"> + <div id="example97" class="manual-example collapse"> <table> <tr><th></th><td class="jqprogram">jq '.foo += 1'</td></tr> @@ -7005,6 +7142,68 @@ Complex assignments </section> + <section id="Colors"> + <h2>Colors</h2> + +<p>To configure alternative colors just set the <code>JQ_COLORS</code> environment variable to colon-delimited list of partial terminal escape sequences like <code>"1;31"</code>, in this order:</p> + +<ul> +<li>color for <code>null</code></li> + +<li>color for <code>false</code></li> + +<li>color for <code>true</code></li> + +<li>color for numbers</li> + +<li>color for strings</li> + +<li>color for arrays</li> + +<li>color for objects</li> +</ul> + +<p>The default color scheme is the same as setting <code>"JQ_COLORS=1;30:0;39:0;39:0;39:0;32:1;39:1;39"</code>.</p> + +<p>This is not a manual for VT100/ANSI escapes. However, each of these color specifications should consist of two numbers separated by a semi-colon, where the first number is one of these:</p> + +<ul> +<li>1 (bright)</li> + +<li>2 (dim)</li> + +<li>4 (underscore)</li> + +<li>5 (blink)</li> + +<li>7 (reverse)</li> + +<li>8 (hidden)</li> +</ul> + +<p>and the second is one of these:</p> + +<ul> +<li>30 (black)</li> + +<li>31 (red)</li> + +<li>32 (green)</li> + +<li>33 (yellow)</li> + +<li>34 (blue)</li> + +<li>35 (magenta)</li> + +<li>36 (cyan)</li> + +<li>37 (white)</li> +</ul> + + + </section> + </div> </div> </div> @@ -7214,7 +7413,7 @@ Complex assignments "Breaking out of control structures" : "Breakingoutofcontrolstructures", - "Error Suppresion / Optional Operator: ?" : "ErrorSuppresion/OptionalOperator:?", + "Error Suppression / Optional Operator: ?" : "ErrorSuppression/OptionalOperator:?", "Conditionals and Comparisons" : "ConditionalsandComparisons" , @@ -7242,12 +7441,16 @@ Complex assignments "Variable / Symbolic Binding Operator: ... as $identifier | ..." : "Variable/SymbolicBindingOperator:...as$identifier|...", + "Destructuring Alternative Operator: ?//" : "DestructuringAlternativeOperator:?//", + "Defining Functions" : "DefiningFunctions", "Scoping" : "Scoping", "Reduce" : "Reduce", + "isempty(exp)" : "isempty(exp)", + "limit(n; exp)" : "limit(n;exp)", "first(expr), last(expr), nth(n; expr)" : "first(expr),last(expr),nth(n;expr)", @@ -7317,6 +7520,10 @@ Complex assignments "modulemeta" : "modulemeta", "Modules" : "Modules" + , + + + "Colors" : "Colors" }; |