diff options
| author | David Tolnay <dtolnay@gmail.com> | 2015-07-26 01:29:15 -0700 |
|---|---|---|
| committer | David Tolnay <dtolnay@gmail.com> | 2015-07-26 01:29:15 -0700 |
| commit | f28dd4d841e761f82273dce8615d57ffc0abd36d (patch) | |
| tree | 1a10981238db968f06d3f6eb98ecfdf2985073ae | |
| parent | c002e269f7160218a795bd71b9129454b3de922c (diff) | |
Pick up historic manuals
| -rw-r--r-- | download/index.html | 2 | ||||
| -rw-r--r-- | index.html | 2 | ||||
| -rw-r--r-- | index/index.html | 2 | ||||
| -rw-r--r-- | manual/index.html | 8 | ||||
| -rw-r--r-- | manual/v1.3/index.html | 2934 | ||||
| -rw-r--r-- | manual/v1.4/index.html | 4154 | ||||
| -rw-r--r-- | sitemap.xml | 18 | ||||
| -rw-r--r-- | tutorial/index.html | 2 |
8 files changed, 7111 insertions, 11 deletions
diff --git a/download/index.html b/download/index.html index a4d72769..a00a9189 100644 --- a/download/index.html +++ b/download/index.html @@ -41,7 +41,7 @@ <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="http://jqplay.org">Try online!</a></li> - <li><a href="https://raw.githubusercontent.com/stedolan/jq/master/NEWS">NEWS</a></li> + <li><a href="https://raw.githubusercontent.com/stedolan/jq/master/NEWS">News</a></li> </ul> </div> </div> @@ -41,7 +41,7 @@ <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="http://jqplay.org">Try online!</a></li> - <li><a href="https://raw.githubusercontent.com/stedolan/jq/master/NEWS">NEWS</a></li> + <li><a href="https://raw.githubusercontent.com/stedolan/jq/master/NEWS">News</a></li> </ul> </div> </div> diff --git a/index/index.html b/index/index.html index 461e68b8..bb8606a9 100644 --- a/index/index.html +++ b/index/index.html @@ -41,7 +41,7 @@ <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="http://jqplay.org">Try online!</a></li> - <li><a href="https://raw.githubusercontent.com/stedolan/jq/master/NEWS">NEWS</a></li> + <li><a href="https://raw.githubusercontent.com/stedolan/jq/master/NEWS">News</a></li> </ul> </div> </div> diff --git a/manual/index.html b/manual/index.html index aae8788d..e314a2fe 100644 --- a/manual/index.html +++ b/manual/index.html @@ -2,7 +2,7 @@ <html lang="en"> <head> <meta charset=UTF-8> - <title>jq Manual</title> + <title>jq Manual (development version)</title> <link rel="stylesheet" href="/jq/bootstrap/css/bootstrap.css" type="text/css"> <link rel="stylesheet" href="/jq/css/base.css" type="text/css"> <!--[if IE]> @@ -41,7 +41,7 @@ <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="http://jqplay.org">Try online!</a></li> - <li><a href="https://raw.githubusercontent.com/stedolan/jq/master/NEWS">NEWS</a></li> + <li><a href="https://raw.githubusercontent.com/stedolan/jq/master/NEWS">News</a></li> </ul> </div> </div> @@ -407,7 +407,9 @@ </div> </div> <div class="span9"> - <h1>jq Manual</h1> + <h1>jq Manual (development version)</h1> + <p><em>For released versions, see <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, diff --git a/manual/v1.3/index.html b/manual/v1.3/index.html new file mode 100644 index 00000000..6e6856a6 --- /dev/null +++ b/manual/v1.3/index.html @@ -0,0 +1,2934 @@ +<!DOCTYPE html> +<html lang="en"> + <head> + <meta charset=UTF-8> + <title>jq 1.3 Manual</title> + <link rel="stylesheet" href="/jq/bootstrap/css/bootstrap.css" type="text/css"> + <link rel="stylesheet" href="/jq/css/base.css" type="text/css"> + <!--[if IE]> + <script src="http://html5shiv.googlecode.com/svn/trunk/html5.js"></script> + <![endif]--> + <script src="//ajax.googleapis.com/ajax/libs/jquery/1.8.1/jquery.min.js"></script> + <script src="/jq/bootstrap/js/bootstrap.js"></script> + +</head> + <body id="v1.3" data-spy="scroll" data-target="#navcolumn" data-offset="100"> + +<div class="navbar navbar-inverse navbar-fixed-top"> + <div class="navbar-inner"> + <div class="container"> + <button type="button" class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse"> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <a class="brand" href="/jq/">jq</a> + <div class="nav-collapse collapse"> + <ul class="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="http://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> + + <div class="container"> + <div class="row"> + <div class="span3" id="navcolumn"> + <div class="affix"> + <h4>Contents</h4> + <ul class="nav nav-pills nav-stacked"> + + <li class="active" > + <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="#Advancedfeatures">Advanced features</a> + </li> + + <li > + <a href="#Assignment">Assignment</a> + </li> + + </ul> + <form class="form-search"> + <script type="text/javascript"> + var section_map = { + + + "Invoking jq" : "Invokingjq" + , + + + "`.`" : "", + + "`.foo`" : "foo", + + "`.[foo]`, `.[2]`, `.[10:15]`" : "foo21015", + + "`.[]`" : "", + + "`,`" : "", + + "`|`" : "", + + "Basic filters" : "Basicfilters" + , + + + "Array construction - `[]`" : "Arrayconstruction", + + "Objects - `{}`" : "Objects", + + "Types and Values" : "TypesandValues" + , + + + "Addition - `+`" : "Addition", + + "Subtraction - `-`" : "Subtraction", + + "Multiplication, division - `*` and `/`" : "Multiplicationdivisionand", + + "`length`" : "length", + + "`keys`" : "keys", + + "`has`" : "has", + + "`to_entries`, `from_entries`, `with_entries`" : "to_entriesfrom_entrieswith_entries", + + "`select`" : "select", + + "`empty`" : "empty", + + "`map(x)`" : "mapx", + + "`add`" : "add", + + "`range`" : "range", + + "`tonumber`" : "tonumber", + + "`tostring`" : "tostring", + + "`type`" : "type", + + "`sort, sort_by`" : "sortsort_by", + + "`group_by`" : "group_by", + + "`min`, `max`, `min_by`, `max_by`" : "minmaxmin_bymax_by", + + "`unique`" : "unique", + + "`reverse`" : "reverse", + + "`contains`" : "contains", + + "`recurse`" : "recurse", + + "String interpolation - `\\(foo)`" : "Stringinterpolationfoo", + + "Format strings and escaping" : "Formatstringsandescaping", + + "Builtin operators and functions" : "Builtinoperatorsandfunctions" + , + + + "`==`, `!=`" : "", + + "if-then-else" : "ifthenelse", + + "`>, >=, <=, <`" : "", + + "and/or/not" : "andornot", + + "Alternative operator - `//`" : "Alternativeoperator", + + "Conditionals and Comparisons" : "ConditionalsandComparisons" + , + + + "Variables" : "Variables", + + "Defining Functions" : "DefiningFunctions", + + "Reduce" : "Reduce", + + "Advanced features" : "Advancedfeatures" + , + + + "`=`" : "", + + "`|=`" : "", + + "`+=`, `-=`, `*=`, `/=`, `//=`" : "", + + "Complex assignments" : "Complexassignments", + + "Assignment" : "Assignment" + + + }; + var section_names = $.map(section_map, function(v,k){return k}); + $(function(){ + $('#searchbox').typeahead({source: section_names}) + $('#searchbox').change(function() { + if ($(this).val() in section_map) { + location.hash = '#' + section_map[$(this).val()]; + } + }); + }); + // add "Run" button to execute examples on jqplay.org + $(function() { + $.each($('table.manual-example'), function(index, value) { + $value = $(value) + var j = $value.find('tr:nth-child(2) td:first').text(); + var q = $value.find('.jqprogram').text().replace(/^jq /, '').replace(/^'(.+)'$/, '$1'); + var url = 'https://jqplay.org/jq?q=' + encodeURIComponent(q) +'&j=' + encodeURIComponent(j) + var $last_tr = $value.find('tr:last'); + $last_tr.after('<tr><th><a href="' + url + '" class="btn btn-primary btn-small">Run</a></th><th></th></tr><tr><th></th><th></th></tr>'); + }); + }); + </script> + <input type="text" + class="input-medium search-query" + placeholder="Search" + autocomplete="off" + id="searchbox"> + </form> + </div> + </div> + <div class="span9"> + <h1>jq 1.3 Manual</h1> + <p><em>The manual for the development version of jq can be found +<a href='/jq/manual'>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 dividing the results.</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>You can affect how jq reads and writes its input and output using some command-line options:</p> + +<ul> +<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>--colour-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> +</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>--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>--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>.</p> +</li> +</ul> + + </section> + + <section id="Basicfilters"> + <h2>Basic filters</h2> + + + <section id=""> + <h3> + <p><code>.</code></p> + + </h3> + <p>The absolute simplest (and least interesting) filter is <code>.</code>. This is a filter that takes its input and produces it unchanged as output.</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="icon-chevron-right"></i> + Example + </a> + <div id="example1" class="collapse"> + + + <table class="manual-example"> + <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="foo"> + <h3> + <p><code>.foo</code></p> + + </h3> + <p>The simplest <em>useful</em> filter is .foo. 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> + + + <div> + + <a data-toggle="collapse" href="#example2"> + <i class="icon-chevron-right"></i> + Examples + </a> + <div id="example2" class="collapse"> + + + <table class="manual-example"> + <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 class="manual-example"> + <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> + + </div> + </div> + + </section> + + <section id="foo21015"> + <h3> + <p><code>.[foo]</code>, <code>.[2]</code>, <code>.[10:15]</code></p> + + </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). 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> + +<p>The <code>.[10:15]</code> syntax can be used to return a subarray of an array. 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="#example3"> + <i class="icon-chevron-right"></i> + Examples + </a> + <div id="example3" class="collapse"> + + + <table class="manual-example"> + <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 class="manual-example"> + <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 class="manual-example"> + <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 class="manual-example"> + <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 class="manual-example"> + <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=""> + <h3> + <p><code>.[]</code></p> + + </h3> + <p>If you use the <code>.[foo]</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="#example4"> + <i class="icon-chevron-right"></i> + Examples + </a> + <div id="example4" class="collapse"> + + + <table class="manual-example"> + <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 class="manual-example"> + <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 class="manual-example"> + <tr><th></th><td class="jqprogram">jq '.[]'</td></tr> + <tr><th>Input</th><td>{"a": 1, "b": 1}</td></tr> + + + <tr> + + <th>Output</th> + + <td>1</td> + </tr> + + <tr> + + <th></th> + + <td>1</td> + </tr> + + + </table> + + </div> + </div> + + </section> + + <section id=""> + <h3> + <p><code>,</code></p> + + </h3> + <p>If two filters are separated by a comma, then the input will be fed into both and there will be multiple outputs: first, all of the outputs produced by the left expression, and then all of the outputs produced by the right. For instance, filter <code>.foo, .bar</code>, produces both the “foo” fields and “bar” fields as separate outputs.</p> + + + <div> + + <a data-toggle="collapse" href="#example5"> + <i class="icon-chevron-right"></i> + Examples + </a> + <div id="example5" class="collapse"> + + + <table class="manual-example"> + <tr><th></th><td class="jqprogram">jq '.foo, .bar'</td></tr> + <tr><th>Input</th><td>{"foo": 42, "bar": "something else", "baz": true}</td></tr> + + + <tr> + + <th>Output</th> + + <td>42</td> + </tr> + + <tr> + + <th></th> + + <td>"something else"</td> + </tr> + + + </table> + + <table class="manual-example"> + <tr><th></th><td class="jqprogram">jq '.user, .projects[]'</td></tr> + <tr><th>Input</th><td>{"user":"stedolan", "projects": ["jq", "wikiflow"]}</td></tr> + + + <tr> + + <th>Output</th> + + <td>"stedolan"</td> + </tr> + + <tr> + + <th></th> + + <td>"jq"</td> + </tr> + + <tr> + + <th></th> + + <td>"wikiflow"</td> + </tr> + + + </table> + + <table class="manual-example"> + <tr><th></th><td class="jqprogram">jq '.[4,2]'</td></tr> + <tr><th>Input</th><td>["a","b","c","d","e"]</td></tr> + + + <tr> + + <th>Output</th> + + <td>"e"</td> + </tr> + + <tr> + + <th></th> + + <td>"c"</td> + </tr> + + + </table> + + </div> + </div> + + </section> + + <section id=""> + <h3> + <p><code>|</code></p> + + </h3> + <p>The | operator combines two filters by feeding the output(s) of the one on the left into th |