.\" 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-FUN 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
  #include <fun.h>

  function add(\fIx\fB, \fIy\fB)
  {
     return \fIx\fB + \fIy\fB
  }

  BEGIN {
    \fIfn\fB = bind(3, add)

    print call(\fIfn\fB, 4) \fI// prints 7\fB
  }
.ft R

See the documentation for
.B mapcar
and
.B mappend
in the
.I cppawk-cons
manual page for more examples of
.B bind
as well as
.BR fun .

.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.