From 9ba7d7b2ff7ac1617569a111ff3ede5451c4b221 Mon Sep 17 00:00:00 2001
From: John Kerl <kerl.john.r@gmail.com>
Date: Tue, 22 Feb 2022 00:33:35 -0500
Subject: [PATCH] Doc updates for funct keyword (#961)

---
 docs/src/reference-dsl-variables.md      | 35 ++++++++++++++++++++++++
 docs/src/reference-dsl-variables.md.in   | 35 ++++++++++++++++++++++++
 docs/src/reference-main-data-types.md    |  8 ++++--
 docs/src/reference-main-data-types.md.in |  8 ++++--
 4 files changed, 82 insertions(+), 4 deletions(-)

diff --git a/docs/src/reference-dsl-variables.md b/docs/src/reference-dsl-variables.md
index 0a034a3bc..ee52179d1 100644
--- a/docs/src/reference-dsl-variables.md
+++ b/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:
diff --git a/docs/src/reference-dsl-variables.md.in b/docs/src/reference-dsl-variables.md.in
index 0aaf4b5ba..2972e51b6 100644
--- a/docs/src/reference-dsl-variables.md.in
+++ b/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:
diff --git a/docs/src/reference-main-data-types.md b/docs/src/reference-main-data-types.md
index 3c74f928b..7505acb81 100644
--- a/docs/src/reference-main-data-types.md
+++ b/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).
diff --git a/docs/src/reference-main-data-types.md.in b/docs/src/reference-main-data-types.md.in
index d3e7e4268..2a06268da 100644
--- a/docs/src/reference-main-data-types.md.in
+++ b/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).