Doc updates for funct keyword (#961)

docs/src/reference-dsl-variables.md

@@ -766,6 +766,41 @@ func f(map m, int i): bool {
 }
 </pre>
 
+The `funct` keyword, for _function type_, indicates that a variable, argument, or return value is a function -- either a [function literal](reference-dsl-user-defined-functions.md#function-literals) or a (named) [user-defined function](reference-dsl-user-defined-functions.md).
+
+<pre class="pre-non-highlight-non-pair">
+$ cat funct-example.mlr
+func makefunc(): funct {
+  return func(x,y) {
+    return 10*x + y
+  }
+}
+
+func callfunc(funct f, num x, num y): num {
+  return f(x, y)
+}
+</pre>
+
+<pre class="pre-non-highlight-non-pair">
+$ rlwrap mlr repl
+Miller 6.0.0-dev REPL for darwin/amd64/go1.17
+Docs: https://miller.readthedocs.io
+Type ':h' or ':help' for online help; ':q' or ':quit' to quit.
+
+[mlr] :load funct-example.mlr
+
+[mlr] f = makefunc()
+
+[mlr] f
+function-literal-000001
+
+[mlr] f(2,3)
+23
+
+[mlr] callfunc(f, 3, 5)
+35
+</pre>
+
 ## Aggregate variable assignments
 
 There are three remaining kinds of variable assignment using out-of-stream variables, the last two of which use the `$*` syntax:

docs/src/reference-dsl-variables.md.in

@@ -421,6 +421,41 @@ func f(map m, int i): bool {
 }
 GENMD-EOF
 
+The `funct` keyword, for _function type_, indicates that a variable, argument, or return value is a function -- either a [function literal](reference-dsl-user-defined-functions.md#function-literals) or a (named) [user-defined function](reference-dsl-user-defined-functions.md).
+
+GENMD-CARDIFY
+$ cat funct-example.mlr
+func makefunc(): funct {
+  return func(x,y) {
+    return 10*x + y
+  }
+}
+
+func callfunc(funct f, num x, num y): num {
+  return f(x, y)
+}
+GENMD-EOF
+
+GENMD-CARDIFY
+$ rlwrap mlr repl
+Miller 6.0.0-dev REPL for darwin/amd64/go1.17
+Docs: https://miller.readthedocs.io
+Type ':h' or ':help' for online help; ':q' or ':quit' to quit.
+
+[mlr] :load funct-example.mlr
+
+[mlr] f = makefunc()
+
+[mlr] f
+function-literal-000001
+
+[mlr] f(2,3)
+23
+
+[mlr] callfunc(f, 3, 5)
+35
+GENMD-EOF
+
 ## Aggregate variable assignments
 
 There are three remaining kinds of variable assignment using out-of-stream variables, the last two of which use the `$*` syntax:

docs/src/reference-main-data-types.md

@@ -32,9 +32,13 @@ Miller's types are:
     * **absent-null**: Such as on reads of unset right-hand sides, or fall-through non-explicit return values from user-defined functions. See the [null-data page](reference-main-null-data.md).
     * **JSON-null**: For `null` in JSON files; also used in [gapped auto-extend of arrays](reference-main-arrays.md#auto-extend-and-null-gaps). See the [null-data page](reference-main-null-data.md).
     * **error** -- for various results which cannot be computed, often when the input to a [built-in function](reference-dsl-builtin-functions.md) is of the wrong type. For example, doing [strlen](reference-dsl-builtin-functions.md#strlen) or [substr](reference-dsl-builtin-functions.md#substr) on a non-string, [sec2gmt](reference-dsl-builtin-functions.md#sec2gmt) on a non-integer, etc.
+* Functions:
+    * As described in the [page on function literals](reference-dsl-user-defined-functions.md#function-literals), you can define unnamed functions and assign them to variables, or pass them to functions.
+    * These can also be (named) [user-defined functions](reference-dsl-user-defined-functions.md).
+    * Use-cases include [custom sorting](reference-dsl-builtin-functions.md#sort), along with higher-order-functions such as [`select`](reference-dsl-builtin-functions.md#select), [`apply`](reference-dsl-builtin-functions.md#apply), [`reduce`](reference-dsl-builtin-functions.md#reduce), and [`fold`](reference-dsl-builtin-functions.md#fold).
 
-See also the list of [type-checking
-functions](reference-dsl-builtin-functions.md#type-checkin -functions) for the
+See also the list of
+[type-checking functions](reference-dsl-builtin-functions.md#type-checkin -functions) for the
 [Miller programming language](miller-programming-language.md).
 
 See also [Differences from other programming languages](reference-dsl-differences.md).

docs/src/reference-main-data-types.md.in

@@ -16,9 +16,13 @@ Miller's types are:
     * **absent-null**: Such as on reads of unset right-hand sides, or fall-through non-explicit return values from user-defined functions. See the [null-data page](reference-main-null-data.md).
     * **JSON-null**: For `null` in JSON files; also used in [gapped auto-extend of arrays](reference-main-arrays.md#auto-extend-and-null-gaps). See the [null-data page](reference-main-null-data.md).
     * **error** -- for various results which cannot be computed, often when the input to a [built-in function](reference-dsl-builtin-functions.md) is of the wrong type. For example, doing [strlen](reference-dsl-builtin-functions.md#strlen) or [substr](reference-dsl-builtin-functions.md#substr) on a non-string, [sec2gmt](reference-dsl-builtin-functions.md#sec2gmt) on a non-integer, etc.
+* Functions:
+    * As described in the [page on function literals](reference-dsl-user-defined-functions.md#function-literals), you can define unnamed functions and assign them to variables, or pass them to functions.
+    * These can also be (named) [user-defined functions](reference-dsl-user-defined-functions.md).
+    * Use-cases include [custom sorting](reference-dsl-builtin-functions.md#sort), along with higher-order-functions such as [`select`](reference-dsl-builtin-functions.md#select), [`apply`](reference-dsl-builtin-functions.md#apply), [`reduce`](reference-dsl-builtin-functions.md#reduce), and [`fold`](reference-dsl-builtin-functions.md#fold).
 
-See also the list of [type-checking
-functions](reference-dsl-builtin-functions.md#type-checkin -functions) for the
+See also the list of
+[type-checking functions](reference-dsl-builtin-functions.md#type-checkin -functions) for the
 [Miller programming language](miller-programming-language.md).
 
 See also [Differences from other programming languages](reference-dsl-differences.md).