Add examples for input & inputs to manual

[yertto]

Some example usages of input & inputs to add to the manual.

eg. given:
seq 4

1
2
3
4

seq 4 | jq -c '[input]'

[2]
[4]

seq 4 | jq -c '[., input]'

[1,2]
[3,4]

seq 4 | jq -c '[inputs]'

[2,3,4]

seq 4 | jq -c '[., inputs]'

[1,2,3,4]

seq 6 | jq -c '[., input], [input], [inputs]'

[1,2]
[3]
[4,5,6]

[wader]

Maybe should also mention how -n affects first input, input and inputs? i think that confuses people. I did a PR some time ago to make it a bit clearer #2395

[itchyny]

Proposed examples are a bit complexing to be written in this manual, and impractical in my honest opinion, I would rather prefer command line examples with -n, just like #2216. E.x. echo '1 2' | jq -n 'input + input' or seq 5 | jq -n -c '[inputs]', or without -n, echo '1 2' | jq '. + input'.

[emanuele6]

I don't recommend using ., inputs as a substitute for using -n.

If you use jq -Rn 'inputs | tonumber' for example, jq will stop running at the first error raised by tonumber/0 as you would expect.

But if you use jq -R '., inputs | tonumber', jq will simply raise an error for that input, print out a warning, and carry on to the next input.

bash-5.1$ printf %s\\n 1 2 hello 3 hi | jq -Rn 'inputs | tonumber'
1
2
jq: error (at <stdin>:3): Invalid numeric literal at EOF at line 1, column 5 (while parsing 'hello')

bash-5.1$ printf %s\\n 1 2 hello 3 hi | jq -R '., inputs | tonumber'
1
2
jq: error (at <stdin>:3): Invalid numeric literal at EOF at line 1, column 5 (while parsing 'hello')
3
jq: error (at <stdin>:5): Invalid numeric literal at EOF at line 1, column 2 (while parsing 'hi')

They are not exactly the same; and in most cases you probably don't want the behaviour of ., inputs when an uncaught error is raised.

[nicowilliams]

I have at times thought about having jq detect (by scanning the final block representation before assembling the bytecode) if the program uses input or inputs, and if so assume -n. I'm not sure what would break if we did that now versus how much confusion we'd save. It might be worthwhile.

[emanuele6]

input/0 and inputs/0 are useful also when you are not using -n.
For example, if you want to handle inputs in groups of 2 or more, it is often easier to use

jq '. + input?'
jq '[ ., input?, input? ]'

instead of

jq -n '[ limits(2; inputs) ] | select(length != 0) | add'
jq -n '[ limits(3; inputs) ] | select(length != 0)'

[nicowilliams]

input/0 and inputs/0 are useful also when you are not using -n. For example, if you want to handle inputs in groups of 2 or more, it is often easier to use

jq '. + input?'
jq '[ ., input?, input? ]'

instead of

jq -n '[ limits(2; inputs) ] | select(length != 0) | add'
jq -n '[ limits(3; inputs) ] | select(length != 0)'

Why not jq -n 'input + input?' and jq -n '[input, input?, input?]' -- almost just as pithy, uses -n, does not use limits/2 or select/1.

[emanuele6]

Why not jq -n 'input + input?' and jq -n '[input, input?, input?]' -- almost just as pithy, uses -n, does not use limits/2 or select/1.

@nicowilliams
That is not the same thing:

$ jq '. + input?' <<< '1 2 3 4 5'
3
7
$ jq -n 'input + input?' <<< '1 2 3 4 5'
3

$ jq -c '[ ., input?, input? ]' <<< '"a" "b" "c" "d" "e" "f" "g" "h"'
["a","b","c"]
["d","e","f"]
["g","h"]
$ jq -cn '[ input, input?, input? ]' <<< '"a" "b" "c" "d" "e" "f" "g" "h"'
["a","b","c"]

[emanuele6]

Oh, I meant to write

jq -n 'repeat([ limit(2; inputs) ]) | select(length != 0) | add'
jq -n 'repeat([ limit(3; inputs) ]) | select(length != 0)'

In my -n examples, but they are wrong because they loop forever..

---

You would have to use something like:

jq -n 'repeat(input)? | . + input?'
jq -n 'repeat(input)? | [ ., input?, input? ]'

EDIT: after writing those I realised I have basically written jq -n 'inputs | . + input?'; lol.

[nicowilliams]

Can we have examples using input and inputs in the manual and not fail the mantests? We don't call jq_set_input_cb() in jq_testsuite().