Improve manual in various ways (inputs, sort_by, foreach sections, etc.) (#2744)

- Add error/0 and mentions null input behavior (close #2231)
- Explain value iterator suffix syntax .foo[] (close #1047)
- Mention array slicing is also zero-based (close #2094)
- Add examples of input and inputs filters (close #2216, close #2470)
- Improve sort_by about multiple values (close #2103, close #2467, close #2474)
- Improve foreach section and simplify examples (close #1148, close #2169)
- Fix recurse/1 document on how it is identical using recurse/2 (close #2036, close #2412)
- Add non-string examples of index/1, rindex/1 (close #1422)
- Simplify the example of truncate_stream/1 (close #1736)

tests/jq.test

@@ -1232,6 +1232,14 @@ null
 [null,true,{"a":1}]
 []
 
+[1,error,2]
+null
+[1,2]
+
+[1,error(null),2]
+0
+[1,2]
+
 try error("\($__loc__)") catch .
 null
 "{\"file\":\"<top-level>\",\"line\":1}"

tests/man.test

@@ -86,6 +86,12 @@ null
 .[]
 []
 
+.foo[]
+{"foo":[1,2,3]}
+1
+2
+3
+
 .[]
 {"a": 1, "b": 1}
 1
@@ -133,7 +139,7 @@ null
 {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
 {"stedolan": ["JQ Primer", "More JQ"]}
 
-..|.a?
+.. | .a?
 [[{"a":1}]]
 1
 
@@ -316,6 +322,14 @@ null
 null
 [1,2,3]
 
+try error catch .
+"error message"
+"error message"
+
+try error("invalid value: \(.)") catch .
+42
+"invalid value: 42"
+
 try error("\($__loc__)") catch .
 null
 "{\"file\":\"<top-level>\",\"line\":1}"
@@ -443,8 +457,12 @@ sort
 [null,3,6,8]
 
 sort_by(.foo)
-[{"foo":4, "bar":10}, {"foo":3, "bar":100}, {"foo":2, "bar":1}]
-[{"foo":2, "bar":1}, {"foo":3, "bar":100}, {"foo":4, "bar":10}]
+[{"foo":4, "bar":10}, {"foo":3, "bar":10}, {"foo":2, "bar":1}]
+[{"foo":2, "bar":1}, {"foo":3, "bar":10}, {"foo":4, "bar":10}]
+
+sort_by(.foo, .bar)
+[{"foo":4, "bar":10}, {"foo":3, "bar":20}, {"foo":2, "bar":1}, {"foo":3, "bar":10}]
+[{"foo":2, "bar":1}, {"foo":3, "bar":10}, {"foo":3, "bar":20}, {"foo":4, "bar":10}]
 
 group_by(.foo)
 [{"foo":1, "bar":10}, {"foo":3, "bar":100}, {"foo":1, "bar":1}]
@@ -510,10 +528,26 @@ index(", ")
 "a,b, cd, efg, hijk"
 3
 
+index(1)
+[0,1,2,1,3,1,4]
+1
+
+index([1,2])
+[0,1,2,3,1,4,2,5,1,2,6,7]
+1
+
 rindex(", ")
 "a,b, cd, efg, hijk"
 12
 
+rindex(1)
+[0,1,2,1,3,1,4]
+5
+
+rindex([1,2])
+[0,1,2,3,1,4,2,5,1,2,6,7]
+8
+
 inside("foobar")
 "bar"
 true
@@ -799,14 +833,18 @@ def addvalue(f): f as $x | map(. + $x); addvalue(.[0])
 [[1,2],[10,20]]
 [[1,2,1,2], [10,20,1,2]]
 
-reduce .[] as $item (0; . + $item)
-[10,2,5,3]
-20
-
 isempty(empty)
 null
 true
 
+isempty(.[])
+[]
+true
+
+isempty(.[])
+[1,2,3]
+false
+
 [limit(3;.[])]
 [0,1,2,3,4,5,6,7,8,9]
 [0,1,2]
@@ -819,9 +857,39 @@ true
 10
 [0,9,5]
 
-[foreach .[] as $item ([[],[]]; if $item == null then [[],.[0]] else [(.[0] + [$item]),[]] end; if $item == null then .[1] else empty end)]
-[1,2,3,4,null,"a","b",null]
-[[1,2,3,4],["a","b"]]
+reduce .[] as $item (0; . + $item)
+[1,2,3,4,5]
+15
+
+reduce .[] as [$i,$j] (0; . + $i * $j)
+[[1,2],[3,4],[5,6]]
+44
+
+reduce .[] as {$x,$y} (null; .x += $x | .y += [$y])
+[{"x":"a","y":1},{"x":"b","y":2},{"x":"c","y":3}]
+{"x":"abc","y":[1,2,3]}
+
+foreach .[] as $item (0; . + $item)
+[1,2,3,4,5]
+1
+3
+6
+10
+15
+
+foreach .[] as $item (0; . + $item; [$item, . * 2])
+[1,2,3,4,5]
+[1,2]
+[2,6]
+[3,12]
+[4,20]
+[5,30]
+
+foreach .[] as $item (0; . + 1; {index: ., $item})
+["foo", "bar", "baz"]
+{"index":1,"item":"foo"}
+{"index":2,"item":"bar"}
+{"index":3,"item":"baz"}
 
 def range(init; upto; by): 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)); range(0; 10; 3)
 null
@@ -834,9 +902,10 @@ def while(cond; update): def _while: if cond then ., (update | _while) else empt
 1
 [1,2,4,8,16,32,64]
 
-[1|truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]])]
+truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]])
 1
-[[[0],2],[[0]]]
+[[0],2]
+[[0]]
 
 fromstream(1|truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]]))
 null