@port-labs/jq-node-bindings 1.0.4 → 1.1.0-dev

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

@@ -1,11 +1,6 @@
 ---
 headline: jq Manual (development version)
 
-history: |
-
-  *For released versions, see [jq 1.7](./v1.7/), [jq 1.6](./v1.6/), [jq 1.5](./v1.5/),
-  [jq 1.4](./v1.4/) or [jq 1.3](./v1.3/).*
-
 body: |
 
   A jq program is a "filter": it takes an input, and produces an
@@ -226,12 +221,13 @@ sections:
         RS.  This mode also parses the output of jq without the `--seq`
         option.
 
-      * `-f filename` / `--from-file filename`:
+      * `-f` / `--from-file`:
 
-        Read filter from the file rather than from a command line, like
-        awk's -f option. You can also use '#' to make comments.
+        Read the filter from a file rather than from a command line,
+        like awk's -f option. This changes the filter argument to be
+        interpreted as a filename, instead of the source of a program.
 
-      * `-L directory`:
+      * `-L directory` / `--library-path directory`:
 
         Prepend `directory` to the search list for modules.  If this
         option is used then no builtin search list is used.  See the
@@ -246,7 +242,8 @@ sections:
         bind `$foo` to `"123"`.
 
         Named arguments are also available to the jq program as
-        `$ARGS.named`.
+        `$ARGS.named`. When the name is not a valid identifier, this is
+        the only way to access it.
 
       * `--argjson name JSON-text`:
 
@@ -357,10 +354,13 @@ sections:
 
           The way in which jq handles numbers has changed over time
           and further changes are likely within the parameters set by
-          the relevant JSON standards.  The following remarks are
-          therefore offered with the understanding that they are
-          intended to be descriptive of the current version of jq and
-          should not be interpreted as being prescriptive:
+          the relevant JSON standards.  Moreover, build configuration
+          options can alter how jq processes numbers.
+
+          The following remarks are therefore offered with the
+          understanding that they are intended to be descriptive of the
+          current version of jq and should not be interpreted as being
+          prescriptive:
 
           (1) Any arithmetic operation on a number that has not
           already been converted to an IEEE754 double precision
@@ -368,17 +368,21 @@ sections:
           representation.
 
           (2) jq will attempt to maintain the original decimal
-          precision of number literals, but in expressions such
-          `1E1234567890`, precision will be lost if the exponent is
-          too large.
-
-          (3) In jq programs, a leading minus sign will trigger the
-          conversion of the number to an IEEE754 representation.
+          precision of number literals (if the `--disable-decnum`
+          build configuration option was not used), but in expressions
+          such `1E1234567890`, precision will be lost if the exponent
+          is too large.
 
-          (4) Comparisons are carried out using the untruncated
+          (3) Comparisons are carried out using the untruncated
           big decimal representation of numbers if available, as
           illustrated in one of the following examples.
 
+          The examples below use the builtin function `have_decnum` in
+          order to demonstrate the expected effects of using / not
+          using the `--disable-decnum` build configuration option, and
+          also to allow automated tests derived from these examples to
+          pass regardless of whether that option is used.
+
         examples:
           - program: '.'
             input: '"Hello, world!"'
@@ -388,21 +392,25 @@ sections:
             input: '0.12345678901234567890123456789'
             output: ['0.12345678901234567890123456789']
 
-          - program: '[., tojson]'
+          - program: '[., tojson] == if have_decnum then [12345678909876543212345,"12345678909876543212345"] else [12345678909876543000000,"12345678909876543000000"] end'
             input: '12345678909876543212345'
-            output: ['[12345678909876543212345,"12345678909876543212345"]']
+            output: ['true']
+
+          - program: '[1234567890987654321,-1234567890987654321 | tojson] == if have_decnum then ["1234567890987654321","-1234567890987654321"] else ["1234567890987654400","-1234567890987654400"] end'
+            input: 'null'
+            output: ['true']
 
           - program: '. < 0.12345678901234567890123456788'
             input: '0.12345678901234567890123456789'
             output: ['false']
 
-          - program: 'map([., . == 1]) | tojson'
+          - program: 'map([., . == 1]) | tojson == if have_decnum then "[[1,true],[1.000,true],[1.0,true],[1.00,true]]" else "[[1,true],[1,true],[1,true],[1,true]]" end'
             input: '[1, 1.000, 1.0, 100e-2]'
-            output: ['"[[1,true],[1.000,true],[1.0,true],[1.00,true]]"']
+            output: ['true']
 
-          - program: '. as $big | [$big, $big + 1] | map(. > 10000000000000000000000000000000)'
+          - program: '. as $big | [$big, $big + 1] | map(. > 10000000000000000000000000000000) | . == if have_decnum then [true, false] else [false, false] end'
             input: '10000000000000000000000000000001'
-            output: ['[true, false]']
+            output: ['true']
 
       - title: "Object Identifier-Index: `.foo`, `.foo.bar`"
         body: |
@@ -568,7 +576,7 @@ sections:
           .bar`, produces both the "foo" fields and "bar" fields as
           separate outputs.
 
-          The `,` operator is one way to contruct generators.
+          The `,` operator is one way to construct generators.
 
         examples:
           - program: '.foo, .bar'
@@ -1004,15 +1012,15 @@ sections:
 
           The key difference between `map(f)` and `map_values(f)` is
           that the former simply forms an array from all the values of
-          `($x|f)` for each value, $x, in the input array or object,
+          `($x|f)` for each value, `$x`, in the input array or object,
           but `map_values(f)` only uses `first($x|f)`.
 
-          Specifically, for object inputs, `map_value(f)` constructs
+          Specifically, for object inputs, `map_values(f)` constructs
           the output object by examining in turn the value of
-          `first(.[$k]|f)` for each key, $k, of the input.  If this
+          `first(.[$k]|f)` for each key, `$k`, of the input.  If this
           expression produces no values, then the corresponding key
           will be dropped; otherwise, the output object will have that
-          value at the key, $k.
+          value at the key, `$k`.
 
           Here are some examples to clarify the behavior of `map` and
           `map_values` when applied to arrays. These examples assume the
@@ -1295,7 +1303,7 @@ sections:
             input: '[1,[[],{"a":2}]]'
             output: ['[[0],[1,1,"a"]]']
 
-      - title: "`add`"
+      - title: "`add`, `add(generator)`"
         body: |
 
           The filter `add` takes as input an array, and produces as
@@ -1306,6 +1314,9 @@ sections:
 
           If the input is an empty array, `add` returns `null`.
 
+          `add(generator)` operates on the given generator rather than
+          the input.
+
         examples:
           - program: add
             input: '["a","b","c"]'
@@ -1316,6 +1327,9 @@ sections:
           - program: add
             input: '[]'
             output: ["null"]
+          - program: add(.[].a)
+            input: '[{"a":3}, {"a":5}, {"b":6}]'
+            output: ['8']
 
       - title: "`any`, `any(condition)`, `any(generator; condition)`"
         body: |
@@ -1463,6 +1477,18 @@ sections:
             input: '[1, "1"]'
             output: ['1', '1']
 
+      - title: "`toboolean`"
+        body: |
+
+          The `toboolean` function parses its input as a boolean. It
+          will convert correctly-formatted strings to their boolean
+          equivalent, leave booleans alone, and give an error on all other input.
+
+        examples:
+          - program: '.[] | toboolean'
+            input: '["true", "false", true, false]'
+            output: ['true', 'false', 'true', 'false']
+
       - title: "`tostring`"
         body: |
 
@@ -1772,6 +1798,36 @@ sections:
             input: '["fo", "foo", "barfoo", "foobar", "foob"]'
             output: ['["fo","","bar","foobar","foob"]']
 
+      - title: "`trimstr(str)`"
+        body: |
+
+          Outputs its input with the given string removed at both ends, if it
+          starts or ends with it.
+
+        examples:
+          - program: '[.[]|trimstr("foo")]'
+            input: '["fo", "foo", "barfoo", "foobarfoo", "foob"]'
+            output: ['["fo","","bar","bar","b"]']
+
+      - title: "`trim`, `ltrim`, `rtrim`"
+        body: |
+
+          `trim` trims both leading and trailing whitespace.
+
+          `ltrim` trims only leading (left side) whitespace.
+
+          `rtrim` trims only trailing (right side) whitespace.
+
+          Whitespace characters are the usual `" "`, `"\n"` `"\t"`, `"\r"`
+          and also all characters in the Unicode character database with the
+          whitespace property. Note that what considers whitespace might
+          change in the future.
+
+        examples:
+          - program: 'trim, ltrim, rtrim'
+            input: '" abc "'
+            output: ['"abc"', '"abc "', '" abc"']
+
       - title: "`explode`"
         body: |
 
@@ -1973,6 +2029,19 @@ sections:
             output:
               - '[{"a":{"b":2}}]'
 
+      - title: "`have_literal_numbers`"
+        body: |
+
+          This builtin returns true if jq's build configuration
+          includes support for preservation of input number literals.
+
+      - title: "`have_decnum`"
+        body: |
+
+          This builtin returns true if jq was built with "decnum",
+          which is the current literal number preserving numeric
+          backend implementation for jq.
+
       - title: "`$JQ_BUILD_CONFIGURATION`"
         body: |
 
@@ -1983,7 +2052,7 @@ sections:
           future to include the version strings for the build
           tooling used.
 
-          Note that this can be overriden in the command-line
+          Note that this can be overridden in the command-line
           with `--arg` and related options.
 
       - title: "`$ENV`, `env`"
@@ -2098,6 +2167,11 @@ sections:
             Applies percent-encoding, by mapping all reserved URI
             characters to a `%XX` sequence.
 
+          * `@urid`:
+
+            The inverse of `@uri`, applies percent-decoding, by mapping
+            all `%XX` sequences to their corresponding URI characters.
+
           * `@csv`:
 
             The input must be an array, and it is rendered as CSV
@@ -2210,7 +2284,7 @@ sections:
 
           The `strptime(fmt)` builtin parses input strings matching the
           `fmt` argument.  The output is in the "broken down time"
-          representation consumed by `gmtime` and output by `mktime`.
+          representation consumed by `mktime` and output by `gmtime`.
 
           The `strftime(fmt)` builtin formats a time (GMT) with the
           given format.  The `strflocaltime` does the same, but using
@@ -2242,13 +2316,13 @@ sections:
 
           jq provides a few SQL-style operators.
 
-          * INDEX(stream; index_expression):
+          * `INDEX(stream; index_expression)`:
 
             This builtin produces an object whose keys are computed by
             the given index expression applied to each value from the
             given stream.
 
-          * JOIN($idx; stream; idx_expr; join_expr):
+          * `JOIN($idx; stream; idx_expr; join_expr)`:
 
             This builtin joins the values from the given stream to the
             given index.  The index's keys are computed by applying the
@@ -2257,22 +2331,22 @@ sections:
             value from the index is fed to the given join expression to
             produce each result.
 
-          * JOIN($idx; stream; idx_expr):
+          * `JOIN($idx; stream; idx_expr)`:
 
             Same as `JOIN($idx; stream; idx_expr; .)`.
 
-          * JOIN($idx; idx_expr):
+          * `JOIN($idx; idx_expr)`:
 
             This builtin joins the input `.` to the given index, applying
             the given index expression to `.` to compute the index key.
             The join operation is as described above.
 
-          * IN(s):
+          * `IN(s)`:
 
             This builtin outputs `true` if `.` appears in the given
             stream, otherwise it outputs `false`.
 
-          * IN(source; s):
+          * `IN(source; s)`:
 
             This builtin outputs `true` if any value in the source stream
             appears in the second stream, otherwise it outputs `false`.
@@ -2491,7 +2565,7 @@ sections:
               label $out | ... break $out ...
 
           The `break $label_name` expression will cause the program to
-          to act as though the nearest (to the left) `label $label_name`
+          act as though the nearest (to the left) `label $label_name`
           produced `empty`.
 
           The relationship between the `break` and corresponding `label`
@@ -2649,12 +2723,17 @@ sections:
           that match the regex in accordance with the flags, if any
           have been specified.  If there is no match, the stream is empty.
           To capture all the matches for each input string, use the idiom
-          `[ expr ]`, e.g. `[ scan(regex) ]`.
+          `[ expr ]`, e.g. `[ scan(regex) ]`.  If the regex contains capturing
+          groups, the filter emits a stream of arrays, each of which contains
+          the captured strings.
 
         examples:
           - program: 'scan("c")'
             input: '"abcdefabc"'
             output: ['"c"', '"c"']
+          - program: 'scan("(a+)(b+)")'
+            input: '"abaabbaaabbb"'
+            output: ['["a","b"]', '["aa","bb"]', '["aaa","bbb"]']
 
       - title: "`split(regex; flags)`"
         body: |
@@ -2680,6 +2759,9 @@ sections:
           - program: 'splits(", *")'
             input: '"ab,cd,   ef, gh"'
             output: ['"ab"','"cd"','"ef"','"gh"']
+          - program: 'splits(",? *"; "n")'
+            input: '"ab,cd ef,  gh"'
+            output: ['"ab"','"cd"','"ef"','"gh"']
 
       - title: "`sub(regex; tostring)`, `sub(regex; tostring; flags)`"
         body: |
@@ -2794,7 +2876,7 @@ sections:
               {"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
+          We use a variable, `$names`, to store the realnames object, so that we
           can refer to it later when looking up author usernames:
 
               .realnames as $names | .posts[] | {title, author: $names[.author]}
@@ -2989,16 +3071,26 @@ sections:
             input: '[1,2,3]'
             output: ['false']
 
-      - title: "`limit(n; exp)`"
+      - title: "`limit(n; expr)`"
         body: |
 
-          The `limit` function extracts up to `n` outputs from `exp`.
+          The `limit` function extracts up to `n` outputs from `expr`.
 
         examples:
-          - program: '[limit(3;.[])]'
+          - program: '[limit(3; .[])]'
             input: '[0,1,2,3,4,5,6,7,8,9]'
             output: ['[0,1,2]']
 
+      - title: "`skip(n; expr)`"
+        body: |
+
+          The `skip` function skips the first `n` outputs from `expr`.
+
+        examples:
+          - program: '[skip(3; .[])]'
+            input: '[0,1,2,3,4,5,6,7,8,9]'
+            output: ['[3,4,5,6,7,8,9]']
+
       - title: "`first(expr)`, `last(expr)`, `nth(n; expr)`"
         body: |
 
@@ -3009,9 +3101,12 @@ sections:
           Note that `nth(n; expr)` doesn't support negative values of `n`.
 
         examples:
-          - program: '[first(range(.)), last(range(.)), nth(./2; range(.))]'
+          - program: '[first(range(.)), last(range(.)), nth(5; range(.))]'
             input: '10'
             output: ['[0,9,5]']
+          - program: '[first(empty), last(empty), nth(5; empty)]'
+            input: 'null'
+            output: ['[]']
 
       - title: "`first`, `last`, `nth(n)`"
         body: |
@@ -3160,9 +3255,8 @@ sections:
                     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));
+                        else empty end;
+                    if init == upto then empty elif by == 0 then init else init|_range end;
                 range(0; 10; 3)'
             input: 'null'
             output: ['0', '3', '6', '9']
@@ -3197,7 +3291,7 @@ sections:
       One-input C math functions: `acos` `acosh` `asin` `asinh` `atan`
       `atanh` `cbrt` `ceil` `cos` `cosh` `erf` `erfc` `exp` `exp10`
       `exp2` `expm1` `fabs` `floor` `gamma` `j0` `j1` `lgamma` `log`
-      `log10` `log1p` `log2` `logb` `nearbyint` `pow10` `rint` `round`
+      `log10` `log1p` `log2` `logb` `nearbyint` `rint` `round`
       `significand` `sin` `sinh` `sqrt` `tan` `tanh` `tgamma` `trunc`
       `y0` `y1`.
 
@@ -3239,7 +3333,7 @@ sections:
 
           Outputs one new input.
 
-          Note that when using `input` it is generally be necessary to
+          Note that when using `input` it is generally necessary to
           invoke jq with the `-n` command-line option, otherwise
           the first entity will be lost.
 
@@ -3316,8 +3410,8 @@ sections:
 
       Several builtins are provided to make handling streams easier.
 
-      The examples below use the streamed form of `[0,[1]]`, which is
-      `[[0],0],[[1,0],1],[[1,0]],[[1]]`.
+      The examples below use the streamed form of `["a",["b"]]`, which is
+      `[[0],"a"],[[1,0],"b"],[[1,0]],[[1]]`.
 
       Streaming forms include `[<path>, <leaf-value>]` (to indicate any
       scalar value, empty array, or empty object), and `[<path>]` (to
@@ -3334,9 +3428,9 @@ sections:
           given streaming expression.
 
         examples:
-          - program: 'truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]])'
+          - program: 'truncate_stream([[0],"a"],[[1,0],"b"],[[1,0]],[[1]])'
             input: '1'
-            output: ['[[0],2]', '[[0]]']
+            output: ['[[0],"b"]', '[[0]]']
 
       - title: "`fromstream(stream_expression)`"
         body: |
@@ -3345,9 +3439,9 @@ sections:
           outputs.
 
         examples:
-          - program: 'fromstream(1|truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]]))'
+          - program: 'fromstream(1|truncate_stream([[0],"a"],[[1,0],"b"],[[1,0]],[[1]]))'
             input: 'null'
-            output: ['[2]']
+            output: ['["b"]']
 
       - title: "`tostream`"
         body: |
@@ -3537,6 +3631,68 @@ sections:
               (.posts[] | select(.author == "stedolan") | .comments) |=
                   . + ["terrible."]
 
+  - title: Comments
+
+    body: |
+
+      You can write comments in your jq filters using `#`.
+
+      A `#` character (not part of a string) starts a comment.
+      All characters from `#` to the end of the line are ignored.
+
+      If the end of the line is preceded by an odd number of backslash
+      characters, the following line is also considered part of the
+      comment and is ignored.
+
+      For example, the following code outputs `[1,3,4,7]`
+
+          [
+            1,
+            # foo \
+            2,
+            # bar \\
+            3,
+            4, # baz \\\
+            5, \
+            6,
+            7
+            # comment \
+              comment \
+              comment
+          ]
+
+      Backslash continuing the comment on the next line can be useful
+      when writing the "shebang" for a jq script:
+
+          #!/bin/sh --
+          # total - Output the sum of the given arguments (or stdin)
+          # usage: total [numbers...]
+          # \
+          exec jq --args -MRnf -- "$0" "$@"
+
+          $ARGS.positional |
+          reduce (
+            if . == []
+              then inputs
+              else .[]
+            end |
+            . as $dot |
+            try tonumber catch false |
+            if not or isnan then
+              @json "total: Invalid number \($dot).\n" | halt_error(1)
+            end
+          ) as $n (0; . + $n)
+
+      The `exec` line is considered a comment by jq, so it is ignored.
+      But it is not ignored by `sh`, since in `sh` a backslash at the
+      end of the line does not continue the comment.
+      With this trick, when the script is invoked as `total 1 2`,
+      `/bin/sh -- /path/to/total 1 2` will be run, and `sh` will then
+      run `exec jq --args -MRnf -- /path/to/total 1 2` replacing itself
+      with a `jq` interpreter invoked with the specified options (`-M`,
+      `-R`, `-n`, `--args`), that evaluates the current file (`$0`),
+      with the arguments (`$@`) that were passed to `sh`.
+
   - title: Modules
     body: |
 
@@ -3547,7 +3703,7 @@ sections:
       path (see below).  The `import` and `include` directives allow the
       importer to alter this path.
 
-      Paths in the a search path are subject to various substitutions.
+      Paths in the search path are subject to various substitutions.
 
       For paths starting with `~/`, the user's home directory is
       substituted for `~`.
@@ -3581,7 +3737,8 @@ sections:
       For example, with `-L$HOME/.jq` a module `foo` can be found in
       `$HOME/.jq/foo.jq` and `$HOME/.jq/foo/foo.jq`.
 
-      If `$HOME/.jq` is a file, it is sourced into the main program.
+      If `.jq` exists in the user's home directory, and is a file (not a
+      directory), it is automatically sourced into the main program.
 
     entries:
       - title: "`import RelativePathString as NAME [<metadata>];`"

package/deps/jq/docs/content/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](../).*
-
 body: |
 
   A jq program is a "filter": it takes an input, and produces an

package/deps/jq/docs/content/manual/v1.4/manual.yml

@@ -1,11 +1,6 @@
 ---
 headline: jq 1.4 Manual
 
-history: |
-
-  *The manual for the development version of jq can be found
-  [here](../).*
-
 body: |
 
   A jq program is a "filter": it takes an input, and produces an

package/deps/jq/docs/content/manual/v1.5/manual.yml

@@ -1,11 +1,6 @@
 ---
 headline: jq 1.5 Manual
 
-history: |
-
-  *The manual for the development version of jq can be found
-  [here](../).*
-
 body: |
 
   A jq program is a "filter": it takes an input, and produces an
@@ -1768,7 +1763,7 @@ sections:
 
           The `strptime(fmt)` builtin parses input strings matching the
           `fmt` argument.  The output is in the "broken down time"
-          representation consumed by `gmtime` and output by `mktime`.
+          representation consumed by `mktime` and output by `gmtime`.
 
           The `strftime(fmt)` builtin formats a time with the given
           format.
@@ -1958,7 +1953,7 @@ sections:
               label $out | ... break $out ...
 
           The `break $label_name` expression will cause the program to
-          to act as though the nearest (to the left) `label $label_name`
+          act as though the nearest (to the left) `label $label_name`
           produced `empty`.
 
           The relationship between the `break` and corresponding `label`
@@ -2821,7 +2816,7 @@ sections:
       path (see below).  The `import` and `include` directives allow the
       importer to alter this path.
 
-      Paths in the a search path are subject to various substitutions.
+      Paths in the search path are subject to various substitutions.
 
       For paths starting with "~/", the user's home directory is
       substituted for "~".

package/deps/jq/docs/content/manual/v1.6/manual.yml

@@ -1,11 +1,6 @@
 ---
 headline: jq 1.6 Manual
 
-history: |
-
-  *The manual for the development version of jq can be found
-  [here](../).*
-
 body: |
 
   A jq program is a "filter": it takes an input, and produces an
@@ -1978,7 +1973,7 @@ sections:
 
           The `strptime(fmt)` builtin parses input strings matching the
           `fmt` argument.  The output is in the "broken down time"
-          representation consumed by `gmtime` and output by `mktime`.
+          representation consumed by `mktime` and output by `gmtime`.
 
           The `strftime(fmt)` builtin formats a time (GMT) with the
           given format.  The `strflocaltime` does the same, but using
@@ -2217,7 +2212,7 @@ sections:
               label $out | ... break $out ...
 
           The `break $label_name` expression will cause the program to
-          to act as though the nearest (to the left) `label $label_name`
+          act as though the nearest (to the left) `label $label_name`
           produced `empty`.
 
           The relationship between the `break` and corresponding `label`
@@ -3216,7 +3211,7 @@ sections:
       path (see below).  The `import` and `include` directives allow the
       importer to alter this path.
 
-      Paths in the a search path are subject to various substitutions.
+      Paths in the search path are subject to various substitutions.
 
       For paths starting with "~/", the user's home directory is
       substituted for "~".