New man page: cppawk-fun.

2 files changed, 134 insertions, 0 deletions

diff --git a/README.md b/README.md
index 4b6588d..3a4b02e 100644
--- a/README.md
+++ b/README.md
@@ -139,6 +139,13 @@ There are currently
     combining Lisp lists and Awk arrays such as `group_by`.
     Documented by the [`cppawk-cons` man page](../tree/cppawk-cons.1).
 
+*   `<fun.h>`: three macros for indirect functions, with a simple
+    partial application mechanism for binding the leftmost argument.
+    This requires GNU Awk 4.0 or higher, which features indirect
+    function calls. Note: there are bugs in GNU Awk's indirect function
+    calls feature that are present right through 5.1.1.
+    Documented by the [`cppawk-fun` man page](../tree/cppawk-fun.1).
+
 Several unreleased headers are in the development queue:
 
 *   `<field.h>`: utilities for manipulating fields.
diff --git a/cppawk-fun.1 b/cppawk-fun.1
new file mode 100644
index 0000000..a1a143c
--- /dev/null
+++ b/cppawk-fun.1
@@ -0,0 +1,127 @@
+.\" cppawk: C preprocessor wrapper around awk
+.\" Copyright 2022 Kaz Kylheku <kaz@kylheku.com>
+.\"
+.\" BSD-2 License
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright notice,
+.\"    this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright notice,
+.\"    this list of conditions and the following disclaimer in the documentation
+.\"    and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.de bk
+.IP " "
+.PP
+..
+.TH CPPAWK-ITER 1 "19 April 2022" "cppawk Libraries" "Indirect Functions"
+
+.SH NAME
+fun \- indirect function macros for cppawk (requiring GNU Awk)
+
+.SH SYNOPSIS
+
+.ft B
+  #include <fun.h>
+
+  fun(\fIfname\fP)                      \fI// create indirect function\fP
+  bind(\fIfname\fP, \fIenv\fP)                \fI// create fun, binding left arg\fP
+  call(\fIfun\fP, ...)                  \fI// call indirect function\fP
+.ft R
+
+.SH DESCRIPTION
+.bk
+The
+.B <fun.h>
+header provides some abstraction over GNU Awk's indirect functions.
+"Native" GNU Awk indirect functions are character strings which hold
+a function name. These can be invoked using the
+.B @
+operator. The macros in this header deal with two function representations:
+a function is either the native GNU Awk one (name string) or else
+a cons cell which holds the name string in the
+.I car
+field and a bound argument in the
+.I cdr
+field.
+
+The
+.B fun
+macro takes an identifier as its argument and produces a function.
+This function may be invoked using the
+.B call
+macro, whose first argument is a function, and the remaining arguments
+are passed to that function.
+
+The
+.B bind
+macro creates an indirect function whose first parameter is bound to the
+value of
+.BR bind 's
+.I env
+argument. When this function is invoked using
+.B call
+the
+.I env
+value will be passed as the leftmost argument of the function; the
+arguments specified in
+.B call
+will be the remaining arguments.
+
+.B Example
+
+.ft B
+   
+ 
+.ft R
+.SH "SEE ALSO"
+
+cppawk(1), cppawk-cons(1)
+
+.SH BUGS
+
+A function name which starts with capital
+.B C
+looks like a cons cell. So that is to say
+.BI fun( CreateProcess )
+will misbehave by yielding the unboxed string
+.BR \(dqCreateProcess\(dq .
+Then
+.B call
+tests this unboxed string object with
+.B consp
+which falsely identifies it as a cons cell, mistaking the
+.B C
+for the type code of a boxed object.
+This issue could be addressed by having
+.B fun
+return a boxed string; but then unboxing has to be done
+to call the function using the GNU Awk
+.B @
+operator.
+
+The GNU Awk indirect function implementation has been around since GNU Awk 4.0,
+but serious bugs in the implementation were not fixed until after 5.1.1
+release. As of Gawk 5.1.1, indirection did not work correctly on built-in
+functions as, and nesting of indirect function calls was broken, as in
+.BI @ foo (@ bar ( arg, ...))\fR.\fP
+
+.SH AUTHOR
+Kaz Kylheku <kaz@kylheku.com>
+
+.SH COPYRIGHT
+Copyright 2022, BSD2 License.