Introduce function definition, and add more examples.

jq.html.markdown

@@ -443,7 +443,19 @@ jq -n '{ values: ({ a: 1, b: 2, c: 3 }[] | . * 2) }'
 
 
 # Conditional `if ... then ... else ... end` in jq is an expression, so
-# both the `then` part and the `else` part are required.
+# both the `then` part and the `else` part are required. In jq, only
+# two values, `null` and `false`, are false; all other values are true.
+#
+jq -n 'if 1 > 2 | not and 1 <= 2 then "Makes sense" else "WAT?!" end'
+
+# Output
+# "Makes sense"
+
+# Notice that `not` is a built-in function that takes zero arguments,
+# that's why it's used as a filter to negate its input value.
+# We'll talk about functions soon.
+
+# Another example using a conditional:
 #
 jq -n '1, 2, 3, 4, 5 | if . % 2 != 0 then . else empty end'
 
@@ -749,6 +761,26 @@ jq -rn 'range(2; 4) as $i
 # 3 * 5 = 15
 
 
+# It's sometimes useful to bind the initial input to a variable at the
+# start of a program, so that you can refer to it later down the pipeline.
+#
+jq -rn "$(cat <<'EOF'
+    {lookup:  {a: 1, b: 2, c: 3},
+     bonuses: {a: 5, b: 2, c: 9}
+    }
+    | . as $doc
+    | .bonuses
+    | to_entries[]
+    | "\(.key)'s total is \($doc.lookup[.key] + .value)"
+EOF
+)"
+
+# Output:
+# a's total is 6
+# b's total is 4
+# c's total is 12
+
+
 # In jq, values can be assigned to an array index or object key via the
 # assignment operator, `=`. The same current input is given to both sides
 # of the assignment operator, and the assignment itself evaluates to the
@@ -799,9 +831,43 @@ jq -n '{a: 1, b: {c: 2}, d: [3, 4, 5]} | del(.b.c, .d[1]) | .b.x = 6'
 #   ]
 # }
 
-# FIXME: Cover more topics
-# - function definition
-# - ...
+
+# Other than using jq's built-in functions, you can define your own.
+# In fact, many built-in functions are defined using jq (see the link
+# to jq's built-in functions at the end of the doc).
+#
+jq -n '
+    def my_select(expr): if expr then . else empty end;
+    def my_map(expr): [.[] | expr];
+    def sum: reduce .[] as $x (0; . + $x);
+    def my_range($from; $to):
+        if $from >= $to then
+            empty
+        else
+            $from, my_range($from + 1; $to)
+        end
+    ;
+    [my_range(1; 6)] | my_map(my_select(. % 2 != 0)) | sum
+'
+
+# Output:
+# 9
+
+# Some notes about function definitons:
+#
+# - Functions are usually defined at the beginning, so that they are available
+#   to the rest of the jq program.
+#
+# - Each function definion should end with a `;` (semicolon).
+#
+# - It's also possible to define a function within another, though it's not shown here.
+#
+# - Function parameters are separated by `;` (semicolor). This is consistent with
+#   passing multiple arguments when calling a function.
+#
+# - `def f($a; $b): ...;` is a shorthand for: `def f(a; b): a as $a | b as $b | ...`
+#
+
 ```
 
 ## Further Reading