From 6fc18d14f45ad4606378d974026b61721424a2d1 Mon Sep 17 00:00:00 2001 From: Nicolas Williams Date: Thu, 12 Dec 2013 22:32:30 -0600 Subject: [PATCH] Update site --- download/index.html | 4 +- manual/index.html | 611 ++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 561 insertions(+), 54 deletions(-) diff --git a/download/index.html b/download/index.html index 1b806c0..8841271 100644 --- a/download/index.html +++ b/download/index.html @@ -102,11 +102,11 @@

You can build it using the usual ./configure && make && sudo make install rigmarole.

-

If you’re interested in using the latest development version, try:

+

If you’re interested in using the lastest development version, try:

git clone https://github.com/stedolan/jq.git
 cd jq
-autoreconf
+autoreconf -i
 ./configure
 make
 sudo make install
diff --git a/manual/index.html b/manual/index.html index dfdbcb9..9ec0b06 100644 --- a/manual/index.html +++ b/manual/index.html @@ -119,7 +119,7 @@ "Subtraction - `-`" : "Subtraction", - "Multiplication, division - `*` and `/`" : "Multiplicationdivisionand", + "Multiplication, division, modulo - `*`, `/`, and `%`" : "Multiplicationdivisionmoduloand", "`length`" : "length", @@ -139,6 +139,10 @@ "`range`" : "range", + "`floor`" : "floor", + + "`sqrt`" : "sqrt", + "`tonumber`" : "tonumber", "`tostring`" : "tostring", @@ -157,10 +161,26 @@ "`contains`" : "contains", + "`startswith`" : "startswith", + + "`endswith`" : "endswith", + + "`ltrimstr`" : "ltrimstr", + + "`rtrimstr`" : "rtrimstr", + + "`explode`" : "explode", + + "`implode`" : "implode", + + "`split`" : "split", + "`recurse`" : "recurse", "String interpolation - `\\(foo)`" : "Stringinterpolationfoo", + "Convert to/from JSON" : "ConverttofromJSON", + "Format strings and escaping" : "Formatstringsandescaping", "Builtin operators and functions" : "Builtinoperatorsandfunctions" @@ -195,7 +215,7 @@ "`|=`" : "", - "`+=`, `-=`, `*=`, `/=`, `//=`" : "", + "`+=`, `-=`, `*=`, `/=`, `%=`, `//=`" : "", "Complex assignments" : "Complexassignments", @@ -254,6 +274,12 @@ simpler:

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.

+
  • +

    --online-input/-I:

    + +

    When the top-level input value is an array produce its elements instead of the array. This allows on-line processing of potentially very large top-level arrays’ elements.

    +
    • +

  • --raw-input/-R:

    @@ -284,17 +310,47 @@ simpler:

    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.

    • +
  • +

    --unbuffered

    + +

    Flush the output after each JSON object is printed (useful if you’re piping a slow data source into jq and piping jq’s output elsewhere).

    +
    • + +
  • +

    --sort-keys / -S:

    + +

    Output the fields of each object with the keys in sorted order.

    +
    • +

  • --raw-output / -r:

    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.

    • +
  • +

    -f filename / --from-file filename:

    + +

    Read filter from the file rather than from a command line, like awk’s -f option. You can also use ’#’ to make comments.

    +
    • + +
  • +

    -e / --exit-status:

    + +

    Sets the exit status of jq to 10 if the last output values was false, 11 if the last output value was null, or 0 if the last output value was valid. Normally jq exits with 0, or 1 if there was any usage problem or other error.

    +
    • +

  • --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".

    • + +
  • +

    --argfile name filename:

    + +

    This option passes the first value from the named file as a value to the jq program as a predefined variable. If you run jq with --argfile foo bar, then $foo is available in the program and has the value resulting from parsing the content of the file named bar.

    +
    • @@ -347,7 +403,9 @@ simpler:

    .foo

    -

    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.

    +

    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$".

    @@ -389,6 +447,21 @@ simpler:

    + + + + + + + + + + + + + +
    jq '."foo"'
    Input{"foo": 42}
    Output42
    +
    @@ -401,7 +474,7 @@ simpler:

    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.

    -

    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, 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 .[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).

    @@ -456,6 +529,21 @@ simpler:

    + + + + + + + + + + + + + + +
    jq '.[2:4]'
    Input"abcdefghi"
    Output"cd"
    @@ -1029,19 +1117,23 @@ simpler:

    -
    +

    -

    Multiplication, division - * and /

    +

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

    These operators only work on numbers, and do the expected.

    +

    Multiplying a string by a number produces the concatenation of that string that many times.

    + +

    Dividing a string by another splits the first using the second as separators.

    +
    - Example + Examples
    @@ -1061,6 +1153,21 @@ simpler:

    + + + + + + + + + + + + + +
    jq '. / ", "'
    Input"a, b,c,d, e"
    Output["a","b,c,d","e"]
    +
    @@ -1589,6 +1696,80 @@ map(foo) | from_entries, useful for doing some operation to all keys and +
    +

    +

    floor

    + +

    +

    The floor function returns the floor of its numeric input.

    + + +
    + + + + Example + +
    + + + + + + + + + + + + + + + +
    jq 'floor'
    Input3.14159
    Output3
    + +
    +
    + +
    + +
    +

    +

    sqrt

    + +

    +

    The sqrt function returns the square root of its numeric input.

    + + +
    + + + + Example + +
    + + + + + + + + + + + + + + + +
    jq 'sqrt'
    Input9
    Output3
    + +
    +
    + +
    +

    tonumber

    @@ -1599,11 +1780,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    - + Example -
    +
    @@ -1643,11 +1824,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    @@ -1694,11 +1875,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    @@ -1751,11 +1932,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    @@ -1805,11 +1986,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    @@ -1842,11 +2023,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    @@ -1894,11 +2075,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    @@ -1931,11 +2112,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    @@ -1968,11 +2149,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    @@ -2055,6 +2236,265 @@ map(foo) | from_entries, useful for doing some operation to all keys and +
    +

    +

    startswith

    + +

    +

    Outputs true if . starts with the given string argument.

    + + +
    + + + + Example + +
    + + +
    + + + + + + + + + + + + +
    jq '[.[]|startswith("foo")]'
    Input["fo", "foo", "barfoo", "foobar", "barfoob"]
    Output[false, true, false, true, false]
    + +
    +
    + +

    + +
    +

    +

    endswith

    + +

    +

    Outputs true if . ends with the given string argument.

    + + +
    + + + + Example + +
    + + + + + + + + + + + + + + + +
    jq '[.[]|endswith("foo")]'
    Input["foobar", "barfoo"]
    Output[false, true, true, false, false]
    + +
    +
    + +
    + +
    +

    +

    ltrimstr

    + +

    +

    Outputs its input with the given prefix string removed, if it starts with it.

    + + +
    + + + + Example + +
    + + + + + + + + + + + + + + + +
    jq '[.[]|ltrimstr("foo")]'
    Input["fo", "foo", "barfoo", "foobar", "afoo"]
    Output["fo","","barfoo","bar","afoo"]
    + +
    +
    + +
    + +
    +

    +

    rtrimstr

    + +

    +

    Outputs its input with the given suffix string removed, if it starts with it.

    + + +
    + + + + Example + +
    + + + + + + + + + + + + + + + +
    jq '[.[]|rtrimstr("foo")]'
    Input["fo", "foo", "barfoo", "foobar", "foob"]
    Output["fo","","bar","foobar","foob"]
    + +
    +
    + +
    + +
    +

    +

    explode

    + +

    +

    Converts an input string into an array of the string’s codepoint numbers.

    + + +
    + + + + Example + +
    + + + + + + + + + + + + + + + +
    jq 'explode'
    Input"foobar"
    Output[102,111,111,98,97,114]
    + +
    +
    + +
    + +
    +

    +

    implode

    + +

    +

    The inverse of explode.

    + + +
    + + + + Example + +
    + + + + + + + + + + + + + + + +
    jq 'implode'
    Input[65, 66, 67]
    Output"ABC"
    + +
    +
    + +
    + +
    +

    +

    split

    + +

    +

    Splits an input string on the separator argument.

    + + +
    + + + + Example + +
    + + + + + + + + + + + + + + + +
    jq 'split(", ")'
    Input"a, b,c,d, e"
    Output["a","b,c,d","e"]
    + +
    +
    + +
    +

    recurse

    @@ -2077,11 +2517,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    - + Example -
    +
    @@ -2135,11 +2575,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    @@ -2162,6 +2602,73 @@ map(foo) | from_entries, useful for doing some operation to all keys and +
    +

    +

    Convert to/from JSON

    + +

    +

    The tojson and fromjson builtins dump values as JSON texts or parse JSON texts into values, respectively. The tojson builtin differs from tostring in that tostring returns strings unmodified, while tojson encodes strings as JSON strings.

    + + +
    + + + + Examples + +
    + + +
    + + + + + + + + + + + + +
    jq '[.[]|tostring]'
    Input[1, "foo", ["foo"]]
    Output["1","foo","[\"foo\"]"]
    + + + + + + + + + + + + + + +
    jq '[.[]|tojson]'
    Input[1, "foo", ["foo"]]
    Output["1","\"foo\"","[\"foo\"]"]
    + + + + + + + + + + + + + + +
    jq '[.[]|tojson|fromjson]'
    Input[1, "foo", ["foo"]]
    Output[1,"foo",["foo"]]
    + +
    +
    + +

    +

    Format strings and escaping

    @@ -2226,11 +2733,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    - + Examples -
    +
    @@ -2286,11 +2793,11 @@ map(foo) | from_entries, useful for doing some operation to all keys and
    @@ -2341,7 +2848,7 @@ map(foo) | from_entries, useful for doing some operation to all keys and

    if A then B else C end will act the same as B if A produces a value other than false or null, but act the same as C otherwise.

    -

    Checking for false or null is a simpler notion of “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 +

    Checking for false or null is a simpler notion of “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 | length) > 0 then A else B end instead.

    If the condition A produces multiple results, it is considered “true” if any of those results is not false or null. If it produces zero results, it’s considered false.

    @@ -2351,11 +2858,11 @@ B end instead.

    @@ -2396,11 +2903,11 @@ end'
    @@ -2440,11 +2947,11 @@ not.

    @@ -2552,11 +3059,11 @@ not.

    @@ -2615,7 +3122,7 @@ not.

    For instance, calculating the average value of an array of numbers requires a few variables in most languages - at least one to hold the array, perhaps one for each element or for a loop counter. In jq, it’s simply add / length - the add expression is given the array and 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 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 array-averaging example:

    +

    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 array-averaging example:

    length as $array_length | add / $array_length
    @@ -2652,11 +3159,11 @@ not.

    @@ -2703,11 +3210,11 @@ not.

    @@ -2763,11 +3270,11 @@ not.

    @@ -2834,7 +3341,7 @@ not.

    -

    +=, -=, *=, /=, //=

    +

    +=, -=, *=, /=, %=, //=

    jq has a few operators of the form a op= b, which are all equivalent to a |= . op b. So, += 1 can be used to increment values.

    @@ -2842,11 +3349,11 @@ not.

    -- 2.40.0