@port-labs/jq-node-bindings 0.0.13 → 0.0.15-dev1

package/deps/jq/docs/content/{3.manual → manual}/v1.3/manual.yml

@@ -1,11 +1,6 @@
 ---
 headline: jq 1.3 Manual
 
-history: |
-
-  *The manual for the development version of jq can be found
-  [here](/jq/manual).*
-
 body: |
 
   A jq program is a "filter": it takes an input, and produces an
@@ -63,7 +58,7 @@ manpage_epilogue: |
 
   Presumably. Report them or discuss them at:
 
-      https://github.com/stedolan/jq/issues
+      https://github.com/jqlang/jq/issues
 
   ## AUTHOR
 
@@ -76,30 +71,30 @@ sections:
       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.
+      output(s) of the filter are written to standard output, as a
+      sequence of newline-separated JSON data.
 
       You can affect how jq reads and writes its input and output
       using some command-line options:
 
-      * `--slurp`/`-s`:
+      * `--null-input` / `-n`:
 
-        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.
+        Don't read any input at all. Instead, the filter is run once
+        using `null` as the input. This is useful when using jq as a
+        simple calculator or to construct JSON data from scratch.
 
-      * `--raw-input`/`-R`:
+      * `--raw-input` / `-R`:
 
         Don't parse the input as JSON. Instead, each line of text is
         passed to the filter as a string. If combined with `--slurp`,
         then the entire input is passed to the filter as a single long
         string.
 
-      * `--null-input`/`-n`:
+      * `--slurp` / `-s`:
 
-        Don't read any input at all! Instead, the filter is run once
-        using `null` as the input. This is useful when using jq as a
-        simple calculator or to construct JSON data from scratch.
+        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.
 
       * `--compact-output` / `-c`:
 
@@ -107,11 +102,12 @@ sections:
         will result in more compact output by instead putting each
         JSON object on a single line.
 
-      * `--color-output` / `-C` and `--monochrome-output` / `-M`:
+      * `--raw-output` / `-r`:
 
-        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 `-C`, and disable color with `-M`.
+        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.
 
       * `--ascii-output` / `-a`:
 
@@ -121,12 +117,11 @@ sections:
         ASCII output with every non-ASCII character replaced with the
         equivalent escape sequence.
 
-      * `--raw-output` / `-r`:
+      * `--color-output` / `-C` and `--monochrome-output` / `-M`:
 
-        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.
+        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 `-C`, and disable color with `-M`.
 
       * `--arg name value`:
 
@@ -162,7 +157,7 @@ sections:
         examples:
           - program: '.foo'
             input: '{"foo": 42, "bar": "less interesting data"}'
-            output: [42]
+            output: ['42']
           - program: '.foo'
             input: '{"notfoo": true, "alsonotfoo": false}'
             output: ['null']
@@ -171,10 +166,9 @@ sections:
         body: |
 
           You can also look up fields of an object using syntax like
-          `.["foo"]` (.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 `.[2]`
-          returns the third element of the array.
+          `.["foo"]` (`.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, so `.[2]` returns the third element of the array.
 
           The `.[10:15]` syntax can be used to return a subarray of an
           array. The array returned by `.[10:15]` will be of length 5,
@@ -279,13 +273,13 @@ sections:
       hashes with only string keys), and "null".
 
       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 - `42` is a valid jq
       expression that takes an input, ignores it, and returns 42
       instead.
 
     entries:
-      - title: Array construction - `[]`
+      - title: "Array construction: `[]`"
         body: |
 
           As in JSON, `[]` is used to construct arrays, as in
@@ -310,7 +304,7 @@ sections:
           - program: "[.user, .projects[]]"
             input: '{"user":"stedolan", "projects": ["jq", "wikiflow"]}'
             output: ['["stedolan", "jq", "wikiflow"]']
-      - title: Objects - `{}`
+      - title: "Objects: `{}`"
         body: |
 
           Like JSON, `{}` is for constructing objects (aka
@@ -371,14 +365,14 @@ sections:
   - title: Builtin operators and functions
     body: |
 
-      Some jq operator (for instance, `+`) do different things
+      Some jq operators (for instance, `+`) 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.
 
     entries:
-      - title: Addition - `+`
+      - title: "Addition: `+`"
         body: |
 
           The operator `+` takes two filters, applies them both
@@ -416,11 +410,11 @@ sections:
             input: 'null'
             output: ['{"a": 42, "b": 2, "c": 3}']
 
-      - title: Subtraction - `-`
+      - title: "Subtraction: `-`"
         body: |
 
           As well as normal arithmetic subtraction on numbers, the `-`
-          operator can be used on arrays to remove all occurences of
+          operator can be used on arrays to remove all occurrences of
           the second array's elements from the first array.
 
         examples:
@@ -431,17 +425,17 @@ sections:
             input: '["xml", "yaml", "json"]'
             output: ['["json"]']
 
-      - title: Multiplication, division - `*` and `/`
+      - title: "Multiplication, division: `*` and `/`"
         body: |
 
           These operators only work on numbers, and do the expected.
 
         examples:
           - program: '10 / . * 3'
-            input: 5
-            output: [6]
+            input: '5'
+            output: ['6']
 
-      - title: `length`
+      - title: '`length`'
         body: |
 
           The builtin function `length` gets the length of various
@@ -460,9 +454,9 @@ sections:
         examples:
           - program: '.[] | length'
             input: '[[1,2], "string", {"a":2}, null]'
-            output: [2, 6, 1, 0]
+            output: ['2', '6', '1', '0']
 
-      - title: `keys`
+      - title: '`keys`'
         body: |
 
           The builtin function `keys`, when given an object, returns
@@ -485,7 +479,7 @@ sections:
             input: '[42,3,35]'
             output: ['[0,1,2]']
 
-      - title: `has`
+      - title: '`has`'
         body: |
 
           The builtin function `has` returns whether the input object
@@ -504,7 +498,7 @@ sections:
             input: '[[0,1], ["a","b","c"]]'
             output: ['[false, true]']
 
-      - title: `to_entries`, `from_entries`, `with_entries`
+      - title: "`to_entries`, `from_entries`, `with_entries(f)`"
         body: |
 
           These functions convert between an object and an array of
@@ -513,9 +507,9 @@ sections:
           includes `{"key": k, "value": v}`.
 
           `from_entries` does the opposite conversion, and
-          `with_entries(foo)` is a shorthand for `to_entries |
-          map(foo) | from_entries`, useful for doing some operation to
-          all keys and values of an object.
+          `with_entries(f)` is a shorthand for `to_entries | map(f) |
+          from_entries`, useful for doing some operation to all keys
+          and values of an object.
 
         examples:
           - program: 'to_entries'
@@ -529,14 +523,14 @@ sections:
             output: ['{"KEY_a": 1, "KEY_b": 2}']
 
 
-      - title: `select`
+      - title: '`select`'
         body: |
 
           The function `select(foo)` produces its input unchanged if
           `foo` returns true for that input, and produces no output
           otherwise.
 
-          It's useful for filtering lists: `[1,2,3] | map(select(. >= 2))`
+          It's useful for filtering lists: '`[1,2,3] | map(select(. >= 2))`'
           will give you `[3]`.
 
         examples:
@@ -544,7 +538,7 @@ sections:
             input: '[1,5,3,0,7]'
             output: ['[5,3,7]']
 
-      - title: `empty`
+      - title: '`empty`'
         body: |
 
           `empty` returns no results. None at all. Not even `null`.
@@ -554,19 +548,19 @@ sections:
         examples:
           - program: '1, empty, 2'
             input: 'null'
-            output: [1, 2]
+            output: ['1', '2']
           - program: '[1,2,empty,3]'
             input: 'null'
             output: ['[1,2,3]']
 
-      - title: `map(x)`
+      - title: '`map(f)`'
         body: |
 
-          For any filter `x`, `map(x)` will run that filter for each
+          For any filter `f`, `map(f)` will run that filter for each
           element of the input array, and produce the outputs a new
           array. `map(.+1)` will increment each element of an array of numbers.
 
-          `map(x)` is equivalent to `[.[] | x]`. In fact, this is how
+          `map(f)` is equivalent to `[.[] | f]`. In fact, this is how
           it's defined.
 
         examples:
@@ -574,7 +568,7 @@ sections:
             input: '[1,2,3]'
             output: ['[2,3,4]']
 
-      - title: `add`
+      - title: '`add`'
         body: |
 
           The filter `add` takes as input an array, and produces as
@@ -591,12 +585,12 @@ sections:
             output: ['"abc"']
           - program: add
             input: '[1, 2, 3]'
-            output: [6]
+            output: ['6']
           - program: add
             input: '[]'
             output: ["null"]
 
-      - title: `range`
+      - title: '`range`'
         body: |
 
           The `range` function produces a range of numbers. `range(4;10)`
@@ -612,7 +606,7 @@ sections:
             input: 'null'
             output: ['[2,3]']
 
-      - title: `tonumber`
+      - title: '`tonumber`'
         body: |
 
           The `tonumber` function parses its input as a number. It
@@ -622,9 +616,9 @@ sections:
         examples:
           - program: '.[] | tonumber'
             input: '[1, "1"]'
-            output: [1, 1]
+            output: ['1', '1']
 
-      - title: `tostring`
+      - title: '`tostring`'
         body: |
 
           The `tostring` function prints its input as a
@@ -636,7 +630,7 @@ sections:
             input: '[1, "1", [1]]'
             output: ['"1"', '"1"', '"[1]"']
 
-      - title: `type`
+      - title: '`type`'
         body: |
 
           The `type` function returns the type of its argument as a
@@ -648,7 +642,7 @@ sections:
             input: '[0, false, [], {}, null, "hello"]'
             output: ['["number", "boolean", "array", "object", "null", "string"]']
 
-      - title: `sort, sort_by`
+      - title: '`sort`, `sort_by`'
         body: |
 
           The `sort` functions sorts its input, which must be an
@@ -680,7 +674,7 @@ sections:
             input: '[{"foo":4, "bar":10}, {"foo":3, "bar":100}, {"foo":2, "bar":1}]'
             output: ['[{"foo":2, "bar":1}, {"foo":3, "bar":100}, {"foo":4, "bar":10}]']
 
-      - title: `group_by`
+      - title: '`group_by`'
         body: |
 
           `group_by(.foo)` takes as input an array, groups the
@@ -697,7 +691,7 @@ sections:
             input: '[{"foo":1, "bar":10}, {"foo":3, "bar":100}, {"foo":1, "bar":1}]'
             output: ['[[{"foo":1, "bar":10}, {"foo":1, "bar":1}], [{"foo":3, "bar":100}]]']
 
-      - title: `min`, `max`, `min_by`, `max_by`
+      - title: '`min`, `max`, `min_by`, `max_by`'
         body: |
 
           Find the minimum or maximum element of the input array. The
@@ -713,7 +707,7 @@ sections:
             input: '[{"foo":1, "bar":14}, {"foo":2, "bar":3}]'
             output: ['{"foo":2, "bar":3}']
 
-      - title: `unique`
+      - title: '`unique`'
         body: |
 
           The `unique` function takes as input an array and produces
@@ -725,7 +719,7 @@ sections:
             input: '[1,2,5,3,5,3,1,3]'
             output: ['[1,2,3,5]']
 
-      - title: `reverse`
+      - title: '`reverse`'
         body: |
 
           This function reverses an array.
@@ -735,7 +729,7 @@ sections:
             input: '[1,2,3,4]'
             output: ['[4,3,2,1]']
 
-      - title: `contains`
+      - title: '`contains`'
         body: |
 
           The filter `contains(b)` will produce true if b is
@@ -764,7 +758,7 @@ sections:
             input: '{"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]}'
             output: ['false']
 
-      - title: `recurse`
+      - title: '`recurse`'
         body: |
 
           The `recurse` function allows you to search through a
@@ -796,7 +790,7 @@ sections:
               - '{"foo":[]}'
 
 
-      - title: "String interpolation - `\(foo)`"
+      - title: "String interpolation: `\\(exp)`"
         body: |
 
           Inside a string, you can put an expression inside parens
@@ -872,24 +866,20 @@ sections:
             input: '"This works if x < y"'
             output: ['"This works if x &lt; y"']
 
-#          - program: '@html "<span>Anonymous said: \(.)</span>"'
-#            input: '"<script>alert(\"lol hax\");</script>"'
-#            output: ["<span>Anonymous said: &lt;script&gt;alert(&quot;lol hax&quot;);&lt;/script&gt;</span>"]
-
           - program: '@sh "echo \(.)"'
             input: "\"O'Hara's Ale\""
             output: ["\"echo 'O'\\\\''Hara'\\\\''s Ale'\""]
 
   - title: Conditionals and Comparisons
     entries:
-      - title: `==`, `!=`
+      - title: '`==`, `!=`'
         body: |
 
           The expression 'a == b' will produce 'true' if the result of a and b
           are equal (that is, if they represent equivalent JSON documents) and
           'false' otherwise. In particular, strings are never considered equal
-          to numbers. If you're coming from Javascript, jq's == is like
-          Javascript's === - considering values equal only when they have the
+          to numbers. If you're coming from JavaScript, jq's == is like
+          JavaScript's === - considering values equal only when they have the
           same type as well as the same value.
 
           != is "not equal", and 'a != b' returns the opposite value of 'a == b'
@@ -898,7 +888,8 @@ sections:
           - program: '.[] == 1'
             input: '[1, 1.0, "1", "banana"]'
             output: ['true', 'true', 'false', 'false']
-      - title: if-then-else
+
+      - title: if-then-else-end
         body: |
 
           `if A then B else C end` will act the same as `B` if `A`
@@ -906,11 +897,11 @@ sections:
           as `C` otherwise.
 
           Checking for false or null is a simpler notion of
-          "truthiness" than is found in Javascript or Python, but it
+          "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 `if .name then A else B end`, you'll
-          need something more like `if (.name | count) > 0 then A else
+          need something more like `if (.name | length) > 0 then A else
           B end` instead.
 
           If the condition `A` produces multiple results, then `B` is evaluated
@@ -928,10 +919,10 @@ sections:
               else
                 "many"
               end
-            input: 2
+            input: '2'
             output: ['"many"']
 
-      - title: `>, >=, <=, <`
+      - title: "`>`, `>=`, `<=`, `<`"
         body: |
 
           The comparison operators `>`, `>=`, `<=`, `<` return whether
@@ -943,15 +934,16 @@ sections:
 
         examples:
           - program: '. < 5'
-            input: 2
+            input: '2'
             output: ['true']
 
-      - title: and/or/not
+      - title: "`and`, `or`, `not`"
         body: |
 
-          jq supports the normal Boolean operators and/or/not. They have the
-          same standard of truth as if expressions - false and null are
-          considered "false values", and anything else is a "true value".
+          jq supports the normal Boolean operators `and`, `or`, `not`.
+          They have the same standard of truth as if expressions -
+          `false` and `null` are considered "false values", and
+          anything else is a "true value".
 
           If an operand of one of these operators produces multiple
           results, the operator itself will produce a result for each input.
@@ -961,12 +953,12 @@ sections:
           rather than with special syntax, as in `.foo and .bar |
           not`.
 
-          These three only produce the values "true" and "false", and
+          These three only produce the values `true` and `false`, 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 "//" operator below.
+          evaluating a condition, see the `//` operator below.
 
         examples:
           - program: '42 and "a string"'
@@ -975,9 +967,6 @@ sections:
           - program: '(true, false) or false'
             input: 'null'
             output: ['true', 'false']
-#          - program: '(true, false) and (true, false)'
-#            input: 'null'
-#            output: ['true', 'false', 'false', 'false']
           - program: '(true, true) and (true, false)'
             input: 'null'
             output: ['true', 'false', 'true', 'false']
@@ -985,7 +974,7 @@ sections:
             input: 'null'
             output: ['[false, true]']
 
-      - title: Alternative operator - `//`
+      - title: "Alternative operator: `//`"
         body: |
 
           A filter of the form `a // b` produces the same
@@ -1001,10 +990,10 @@ sections:
         examples:
           - program: '.foo // 42'
             input: '{"foo": 19}'
-            output: [19]
+            output: ['19']
           - program: '.foo // 42'
             input: '{}'
-            output: [42]
+            output: ['42']
 
   - title: Advanced features
     body: |
@@ -1020,7 +1009,7 @@ sections:
 
       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 `map` and `find` are in fact written
+      (many jq functions such as `map` and `select` are in fact written
       in jq).
 
       Finally, jq has a `reduce` operation, which is very powerful but a
@@ -1045,7 +1034,7 @@ sections:
           produces its sum, and the `length` expression is given the array and
           produces its length.
 
-          So, there's generally a cleaner way to solve most problems in jq that
+          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 `expression as $variable`. All
           variable names start with `$`. Here's a slightly uglier version of the
@@ -1061,7 +1050,7 @@ sections:
           fields, and another object which is used to map author usernames to
           real names. Our input looks like:
 
-              {"posts": [{"title": "Frist psot", "author": "anon"},
+              {"posts": [{"title": "First post", "author": "anon"},
                          {"title": "A well-written article", "author": "person1"}],
                "realnames": {"anon": "Anonymous Coward",
                              "person1": "Person McPherson"}}
@@ -1069,7 +1058,7 @@ sections:
           We want to produce the posts with the author field containing a real
           name, as in:
 
-              {"title": "Frist psot", "author": "Anonymous Coward"}
+              {"title": "First post", "author": "Anonymous Coward"}
               {"title": "A well-written article", "author": "Person McPherson"}
 
           We use a variable, $names, to store the realnames object, so that we
@@ -1133,29 +1122,29 @@ sections:
             input: '[[1,2],[10,20]]'
             output: ['[[1,2,1,2], [10,20,1,2]]']
 
-      - title: Reduce
+      - title: "`reduce`"
         body: |
 
-          The `reduce` syntax in jq allows you to combine all of the
-          results of an expression by accumulating them into a single
-          answer. As an example, we'll pass `[3,2,1]` to this expression:
+          The `reduce` syntax allows you to combine all of the results of
+          an expression by accumulating them into a single answer.
+          The form is `reduce EXP as $var (INIT; UPDATE)`.
+          As an example, we'll pass `[1,2,3]` to this expression:
 
               reduce .[] as $item (0; . + $item)
 
           For each result that `.[]` produces, `. + $item` is run to
-          accumulate a running total, starting from 0. In this
-          example, `.[]` produces the results 3, 2, and 1, so the
-          effect is similar to running something like this:
+          accumulate a running total, starting from 0 as the input value.
+          In this example, `.[]` produces the results `1`, `2`, and `3`,
+          so the effect is similar to running something like this:
 
-              0 | (3 as $item | . + $item) |
-                  (2 as $item | . + $item) |
-                  (1 as $item | . + $item)
+              0 | 1 as $item | . + $item |
+                  2 as $item | . + $item |
+                  3 as $item | . + $item
 
         examples:
           - program: 'reduce .[] as $item (0; . + $item)'
-            input: '[10,2,5,3]'
-            output: ['20']
-
+            input: '[1,2,3,4,5]'
+            output: ['15']
 
   - title: Assignment
     body: |
@@ -1169,7 +1158,7 @@ sections:
       If an object has two fields which are arrays, `.foo` and `.bar`,
       and you append something to `.foo`, then `.bar` will not get
       bigger. Even if you've just set `.bar = .foo`. If you're used to
-      programming in languages like Python, Java, Ruby, Javascript,
+      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).
@@ -1186,7 +1175,7 @@ sections:
            .foo = .bar | .foo.baz = 1
 
           will not have the side-effect of setting .bar.baz to be set
-          to 1, as the similar-looking program in Javascript, Python,
+          to 1, as the similar-looking program in JavaScript, Python,
           Ruby or other languages would. Unlike these languages (but
           like Haskell and some other functional languages), there is
           no notion of two arrays or objects being "the same array" or
@@ -1232,7 +1221,7 @@ sections:
       - title: Complex assignments
         body: |
           Lots more things are allowed on the left-hand side of a jq assignment
-          than in most langauges. We've already seen simple field accesses on
+          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: