From 950e414be670f26f149c85408d265458e8c9c347 Mon Sep 17 00:00:00 2001 From: William Langford Date: Thu, 30 Mar 2017 22:29:30 -0400 Subject: Update docs --- download/index.html | 2 +- manual/index.html | 1065 ++++++++++++++++++++++++++++++++---------------- manual/v1.5/index.html | 8 +- sitemap.xml | 22 +- 4 files changed, 741 insertions(+), 356 deletions(-) diff --git a/download/index.html b/download/index.html index 35e7b67a..c44d1238 100644 --- a/download/index.html +++ b/download/index.html @@ -85,7 +85,7 @@
  • -

    For Arch users, a PKGBUILD is in the AUR. Refer to the ArchWiki for how to install from AUR.

    +

    jq 1.5 is in the official Arch repository. Install using sudo pacman -Sy jq.

  • diff --git a/manual/index.html b/manual/index.html index f692ecc5..974178db 100644 --- a/manual/index.html +++ b/manual/index.html @@ -164,7 +164,7 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us

  • --seq:

    -

    Use the application/json-seq MIME type scheme for separating JSON texts in jq’s input and output. This means that an ASCII RS (record separator) character is printed before each value on output and an ASCII LF (line feed) is printed after every output. Input JSON texts that fail to parse are ignored (but warned about), discarding all subsequent input until the next RS. This more also parses the output of jq without the --seq option.

    +

    Use the application/json-seq MIME type scheme for separating JSON texts in jq’s input and output. This means that an ASCII RS (record separator) character is printed before each value on output and an ASCII LF (line feed) is printed after every output. Input JSON texts that fail to parse are ignored (but warned about), discarding all subsequent input until the next RS. This mode also parses the output of jq without the --seq option.

  • @@ -263,12 +263,16 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us

    -e / --exit-status:

    Sets the exit status of jq to 0 if the last output values was neither false nor null, 1 if the last output value was either false or null, or 4 if no valid result was ever produced. Normally jq exits with 2 if there was any usage problem or system error, 3 if there was a jq program compile error, or 0 if the jq program ran.

    + +

    Another way to set the exit status is with the halt_error builtin function.

  • --arg name value:

    This option passes a value to the jq program as a predefined variable. If you run jq with --arg foo bar, then $foo is available in the program and has the value "bar". Note that value will be treated as a string, so --arg foo 123 will bind $foo to "123".

    + +

    Named arguments are also available to the jq program as $ARGS.named.

  • @@ -291,6 +295,18 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us

    (This option is like --slurpfile, but when the file has just one text, then that is used, else an array of texts is used as in --slurpfile.)

    • +
  • +

    --args:

    + +

    Remaining arguments are positional string arguments. These are available to the jq program as $ARGS.positional[].

    +
    • + +
  • +

    --jsonargs:

    + +

    Remaining arguments are positional JSON text arguments. These are available to the jq program as $ARGS.positional[].

    +
    • +

  • --run-tests [filename]:

    @@ -307,15 +323,15 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us

    Basic filters

    -
    +

    -. +Identity: .

    -

    The absolute simplest (and least interesting) filter is .. This is a filter that takes its input and produces it unchanged as output.

    +

    The absolute simplest filter is . . This is a filter that takes its input and produces it unchanged as output. That is, this is the identity operator.

    Since jq by default pretty-prints all output, this trivial program can be a useful way of formatting JSON output from, say, curl.

    @@ -348,20 +364,24 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us
    -
    +

    -.foo, .foo.bar +Object Identifier-Index: .foo, .foo.bar

    The simplest useful 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.

    -

    If the key contains special characters, you need to surround it with double quotes like this: ."foo$".

    -

    A filter of the form .foo.bar is equivalent to .foo|.bar.

    +

    This syntax only works for simple, identifier-like keys, that is, keys that are all made of alphanumeric characters and underscore, and which do not start with a digit.

    + +

    If the key contains special characters, you need to surround it with double quotes like this: ."foo$", or else .["foo$"].

    + +

    For example .["foo::bar"] and .["foo.bar"] work while .foo::bar does not, and .foo.bar means .["foo"].["bar"].

    +
    @@ -419,10 +439,10 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us
    -
    +

    -.foo? +Optional Object Identifier-Index: .foo?

    @@ -500,23 +520,31 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us
    -
    +

    -.[<string>], .[2], .[10:15] +Generic Object Index: .[<string>]

    -

    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.

    +

    You can also look up fields of an object using syntax like .["foo"] (.foo above is a shorthand version of this, but only for identifier-like strings).

    -

    The .[10:15] syntax can be used to return a subarray of an array or substring of a string. The array returned by .[10:15] 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).

    -

    The .[2] 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, and so on.

    + +
    + +
    +

    + +Array Index: .[2] -

    The .foo syntax only works for simply keys i.e. keys that are all alphanumeric characters. .[<string>] works with keys that contain special characters such as colons and dots. For example .["foo::bar"] and .["foo.bar"] work while .foo::bar and .foo.bar would not.

    + +

    + +

    When the index value is an integer, .[<value>] can index arrays. Arrays are zero-based, so .[2] returns the third element.

    -

    The ? “operator” can also be used with the slice operator, as in .[10:15]?, which outputs values where the inputs are slice-able.

    +

    Negative indices are allowed, with -1 referring to the last element, -2 referring to the next to last element, and so on.

    @@ -557,49 +585,74 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us - - + + - +
    jq '.[2:4]'
    Input["a","b","c","d","e"]
    jq '.[-2]'
    Input[1,2,3]
    Output["c", "d"]2
    + + + +
    + +
    +

    + +Array/String Slice: .[10:15] + + +

    + +

    The .[10:15] syntax can be used to return a subarray of an array or substring of a string. The array returned by .[10:15] 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).

    + + + +
    + + + + Examples + +
    + - + - +
    jq '.[2:4]'
    Input"abcdefghi"
    Input["a","b","c","d","e"]
    Output"cd"["c", "d"]
    - - + + - +
    jq '.[:3]'
    Input["a","b","c","d","e"]
    jq '.[2:4]'
    Input"abcdefghi"
    Output["a", "b", "c"]"cd"
    - + @@ -607,21 +660,21 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us - +
    jq '.[-2:]'
    jq '.[:3]'
    Input["a","b","c","d","e"]
    Output["d", "e"]["a", "b", "c"]
    - - + + - +
    jq '.[-2]'
    Input[1,2,3]
    jq '.[-2:]'
    Input["a","b","c","d","e"]
    Output2["d", "e"]
    @@ -631,10 +684,10 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us
    -
    +

    -.[] +Array/Object Value Iterator: .[]

    @@ -647,11 +700,11 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us
    - + Examples -
    +
    @@ -726,25 +779,26 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us -
    +

    -, +Comma: ,

    -

    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 .foo, .bar, produces both the “foo” fields and “bar” fields as separate outputs.

    +

    If two filters are separated by a comma, then the same input will be fed into both and the two filters’ output value streams will be concatenated in order: first, all of the outputs produced by the left expression, and then all of the outputs produced by the right. For instance, filter .foo, +.bar, produces both the “foo” fields and “bar” fields as separate outputs.

    jq '.[]'
    @@ -821,10 +875,10 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us -
    +

    -| +Pipe: |

    @@ -833,15 +887,19 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us

    If the one on the left produces multiple results, the one on the right will be run for each of those results. So, the expression .[] | .foo retrieves the “foo” field of each element of the input array.

    +

    Note that .a.b.c is the same as .a | .b | .c.

    + +

    Note too that . is the input value at the particular stage in a “pipeline”, specifically: where the . expression appears. Thus .a | . | .b is the same as .a.b, as the . in the middle refers to whatever value .a produced.

    +
    jq '.foo, .bar'
    @@ -869,6 +927,45 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us +
    +

    + +Parenthesis + + +

    + +

    Parenthesis work as a grouping operator just as in any typical programming language.

    + + + +
    + + + + Example + +
    + +
    jq '.[] | .name'
    + + + + + + + + + + + +
    jq '(. + 2) * 5'
    Input1
    Output15
    + +
    +
    + +
    +
    @@ -879,10 +976,10 @@ defined. When using the Windows command shell (cmd.exe) it’s best to us

    Booleans, null, strings and numbers are written the same way as in javascript. 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.

    -
    +

    -Array construction - [] +Array construction: []

    @@ -897,11 +994,11 @@ Array construction - []
    - + Example -
    +
    @@ -922,25 +1019,27 @@ Array construction - [] -
    +

    -Objects - {} +Object Construction: {}

    Like JSON, {} is for constructing objects (aka dictionaries or hashes), as in: {"a": 42, "b": 17}.

    -

    If the keys are “sensible” (all alphabetic characters), then the quotes can be left off. The value can be any expression (although you may need to wrap it in parentheses if it’s a complicated one), which gets applied to the {} expression’s input (remember, all filters have an input and an output).

    +

    If the keys are “identifier-like”, then the quotes can be left off, as in {a:42, b:17}. Keys generated by expressions need to be parenthesized, e.g., {("a"+"b"):59}.

    + +

    The value can be any expression (although you may need to wrap it in parentheses if it’s a complicated one), which gets applied to the {} expression’s input (remember, all filters have an input and an output).

    {foo: .bar}
    -

    will produce the JSON object {"foo": 42} if given the JSON object {"bar":42, "baz":43}. You can use this to select particular fields of an object: if the input is an object with “user”, “title”, “id”, and “content” fields and you just want “user” and “title”, you can write

    +

    will produce the JSON object {"foo": 42} if given the JSON object {"bar":42, "baz":43} as its input. You can use this to select particular fields of an object: if the input is an object with “user”, “title”, “id”, and “content” fields and you just want “user” and “title”, you can write

    {user: .user, title: .title}
    -

    Because that’s so common, there’s a shortcut syntax: {user, title}.

    +

    Because that is so common, there’s a shortcut syntax for it: {user, title}.

    If one of the expressions produces multiple results, multiple dictionaries will be produced. If the input’s

    @@ -967,11 +1066,11 @@ Objects - {}
    jq '[.user, .projects[]]'
    @@ -1013,6 +1112,47 @@ Objects - {} +
    +

    + +Recursive Descent: .. + + +

    + +

    Recursively descends ., producing every value. This is the same as the zero-argument recurse builtin (see below). This is intended to resemble the XPath // operator. Note that ..a does not work; use ..|.a instead. In the example below we use ..|.a? to find all the values of object keys “a” in any object found “below” ..

    + +

    This is particularly useful in conjunction with path(EXP) (also see below) and the ? operator.

    + + + +
    + + + + Example + +
    + +
    jq '{user, title: .titles[]}'
    + + + + + + + + + + + +
    jq '..|.a?'
    Input[[{"a":1}]]
    Output1
    + +
    +
    + +
    +
    @@ -1021,10 +1161,10 @@ Objects - {}

    Some jq operator (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.

    -
    +

    -Addition - + +Addition: +

    @@ -1055,11 +1195,11 @@ Addition - +
    - + Examples -
    +
    @@ -1136,10 +1276,10 @@ Addition - + -
    +

    -Subtraction - - +Subtraction: -

    @@ -1150,11 +1290,11 @@ Subtraction - -
    jq '.a + 1'
    @@ -1189,10 +1329,10 @@ Subtraction - - -
    +

    -Multiplication, division, modulo - *, /, and % +Multiplication, division, modulo: *, /, and %

    @@ -1209,11 +1349,11 @@ Multiplication, division, modulo - *, /, and % - + Examples -
    +
    jq '4 - .a'
    @@ -1315,11 +1455,11 @@ Multiplication, division, modulo - *, /, and % - + Example -
    +
    jq '10 / . * 3'
    @@ -1375,11 +1515,11 @@ Multiplication, division, modulo - *, /, and % - + Example -
    +
    jq '.[] | length'
    @@ -1420,11 +1560,11 @@ Multiplication, division, modulo - *, /, and % - + Examples -
    +
    jq 'utf8bytelength'
    @@ -1475,11 +1615,11 @@ Multiplication, division, modulo - *, /, and % - + Examples -
    +
    jq 'keys'
    @@ -1522,17 +1662,17 @@ Multiplication, division, modulo - *, /, and % -

    The builtin function in returns the input key is in the given object, or the input index corresponds to an element in the given array. It is, essentially, an inversed version of has.

    +

    The builtin function in returns whether or not the input key is in the given object, or the input index corresponds to an element in the given array. It is, essentially, an inversed version of has.

    jq 'map(has("foo"))'
    @@ -1582,7 +1722,7 @@ Multiplication, division, modulo - *, /, and % -

    For any filter x, map(x) 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.

    +

    For any filter x, map(x) will run that filter for each element of the input array, and return the outputs in a new array. map(.+1) will increment each element of an array of numbers.

    Similarly, map_values(x) will run that filter for each element, but it will return an object when an object is passed.

    @@ -1592,11 +1732,11 @@ Multiplication, division, modulo - *, /, and % - + Examples -
    +
    jq '.[] | in({"foo": 42})'
    @@ -1639,7 +1779,7 @@ Multiplication, division, modulo - *, /, and % -

    Outputs array representations of the given path expression in .. The outputs are arrays of strings (keys in objects0 and/or numbers (array indices.

    +

    Outputs array representations of the given path expression in .. The outputs are arrays of strings (object keys) and/or numbers (array indices).

    Path expressions are jq expressions like .a, but also .[]. There are two types of path expressions: ones that can match exactly, and ones that cannot. For example, .a.b.c is an exact match path expression, while .a[].b is not.

    @@ -1653,11 +1793,11 @@ Multiplication, division, modulo - *, /, and % - + Examples -
    +
    jq 'map(.+1)'
    @@ -1706,11 +1846,11 @@ Multiplication, division, modulo - *, /, and % - + Examples -
    +
    jq 'path(.a[0].b)'
    @@ -1759,11 +1899,11 @@ Multiplication, division, modulo - *, /, and % - + Examples -
    +
    jq 'del(.foo)'
    @@ -1812,11 +1952,11 @@ Multiplication, division, modulo - *, /, and % - + Examples -
    +
    jq 'getpath(["a","b"])'
    @@ -1865,6 +2005,45 @@ Multiplication, division, modulo - *, /, and % +
    +

    + +delpaths(PATHS) + + +

    + +

    The builtin function delpaths sets the PATHS in .. PATHS must be an array of paths, where each path is an array of strings and numbers.

    + + + +
    + + + + Example + +
    + +
    jq 'setpath(["a","b"]; 1)'
    + + + + + + + + + + + +
    jq 'delpaths([["a","b"]])'
    Input{"a":{"b":1},"x":{"y":2}}
    Output{"a":{},"x":{"y":2}}
    + +
    +
    + +
    +

    @@ -1882,11 +2061,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    - + Examples -
    +
    @@ -1951,11 +2130,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'to_entries'
    @@ -2004,11 +2183,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'map(select(. >= 2))'
    @@ -2045,11 +2224,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq '.[]|numbers'
    @@ -2099,7 +2278,39 @@ map(foo) | from_entries, useful for doing some operation to all keys and -

    Produces an error, just like .a applied to values other than null and objects would, but with the given message as the error’s value.

    +

    Produces an error, just like .a applied to values other than null and objects would, but with the given message as the error’s value. Errors can be caught with try/catch; see below.

    + + + + + +
    +

    + +halt + + +

    + +

    Stops the jq program with no further outputs. jq will exit with exit status 0.

    + + + +
    + +
    +

    + +halt_error, halt_error(exit_code) + + +

    + +

    Stops the jq program with no further outputs. The input will be printed on stderr as raw output (i.e., strings will not have double quotes) with no decoration, not even a newline.

    + +

    The given exit_code (defaulting to 5) will be jq’s exit status.

    + +

    For example, "Error: somthing went wrong\n"|halt_error(1).

    @@ -2119,11 +2330,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq '1, empty, 2'
    @@ -2162,11 +2373,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'try error("\($__loc__)") catch .'
    @@ -2217,11 +2428,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq '[paths]'
    @@ -2290,11 +2501,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'add'
    @@ -2363,11 +2574,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'any'
    @@ -2432,11 +2643,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'all'
    @@ -2519,11 +2730,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'flatten'
    @@ -2635,11 +2846,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'range(2;4)'
    @@ -2674,11 +2885,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'floor'
    @@ -2713,11 +2924,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'sqrt'
    @@ -2759,11 +2970,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq '.[] | tonumber'
    @@ -2812,11 +3023,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq '.[] | tostring'
    @@ -2855,11 +3066,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'map(type)'
    @@ -2944,11 +3155,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq '.[] | (infinite * .) < 0'
    @@ -2999,11 +3210,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'sort'
    @@ -3040,11 +3251,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'group_by(.foo)'
    @@ -3095,11 +3306,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'min'
    @@ -3162,11 +3373,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'unique'
    @@ -3201,11 +3412,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'reverse'
    @@ -3296,11 +3507,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'contains("bar")'
    @@ -3363,11 +3574,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'indices(", ")'
    @@ -3416,11 +3627,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'index(", ")'
    @@ -3511,11 +3722,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    jq 'inside("foobar")'