path: root/cppawk-narg.1

CPPAWK-NARG(1)                              Case Macro                             CPPAWK-NARG(1)

NAME
       narg - macros for writing variable argument macros

SYNOPSIS
         #include <narg.h>

         #define narg(...P)
         #define splice(args)
         #define varexpand(first_mac, rest_mac, ...)
         #define revarg(...)

DESCRIPTION
       The <narg.h> header provides several macros which are useful to macro writers.  In partic-
       ular, these macros make it easy to develop variable argument macros which take one or more
       argument, and have complex expansions.

       In this manual, the -> (arrow) notation means "expands to". For instance

         foo(bar) -> 42  // the macro call foo(bar) expands to 42

       A description of each macro follows:

       narg   This  macro takes one or more arguments, and expands to a decimal integer which in-
              dicates how many arguments there are.

                narg(x) -> 1
                narg(x, y) -> 2
                narg(x, y, z) -> 3

              The narg macro can be called with up to 32 (thirty-two) arguments. If it is  called
              with  between 33 to 48 arguments, it expands to an unspecified token sequence which
              generates a syntax error in Awk. The token sequence begins with an  identifier  and
              therefore  may  appear as the right operand of the token-pasting ## operator, oppo-
              site to an identifier token.

              If more than 48 arguments are given, the behavior is unspecified.

       splice The splice macro provides a shim for inserting  a  parenthesized  argument  into  a
              macro expansion, such that the argument turns into individual arguments. Suppose we
              have a macro like this:

                 #define vmac(a, b, ...) ...

              For some reason, we need to write fixed a macro like this:

                 #define fmac(x, y, args) vmac(x, y, ???)

              where the args argument is a parenthesized list of arguments that must  become  the
              ...   argument  of the vmac macro. That is to say, fmac is to be invoked like this,
              with the indicated expansion:

                 fmac(1, 2, (3, 4, 5)) -> vmac(1, 2, 3, 4, 5)

              The splice macro solves the question of what to write into the  position  indicated
              by the ??? question marks to achieve this:

                 #define fmac(x, y, args) vmac(x, y, splice(args))

              Example: produce the following macro:

                csum((a, b, c), (x, y))   -> (sqrt(sumsq(a, b, c)) +
                                              sqrt(sumsq(x, y)))

              This is a trick example: splice is not required at all:

                #define csum(left, right) (sqrt(sumsq left) + \
                                           sqrt(sumsq right))

              The splice macro is not required because the parenthesized arguments constitute the
              entire argument list of sumsq.  However, suppose the requirement is this, requiring
              the  parenthesized  arguments to be inserted into an argument list containing other
              arguments:

                csum(t, (a, b, c), (x, y))  -> (sqrt(sumsq(t, a, b, c)) +
                                                sqrt(sumsq(t, x, y)))

              Now we need:

                #define csum(parm, left, right) (sqrt(sumsq(parm, \
                                                            splice(left)) + \
                                                      sumsq(parm, \
                                                            splice(right))))

       revarg This macro expands to a comma-separated list of its arguments, which appear in  re-
              verse.

                 revarg(1) -> 1
                 revarg(1, 2) -> 2, 1
                 revarg(1, 2, 3) -> 3, 2, 1

              Like  narg,  the  revarg  macro can be called with up to 32 arguments, beyond which
              there is some overflow detection up to 48 arguments, followed by unspecified behav-
              ior for 49 or more arguments.

       varexpand
              The most complex macro in the <narg.h> header is varexpand.

              This  macro  is  used  for writing variadic macros with complex expansions, using a
              compact specification.

              The varexpand macro uses "higher order macro" programming: it has  arguments  which
              are themselves macros.  To understand varexpand it helps to understand the Lisp re-
              duce function, or the similar fold function found in functional  languages.  Recall
              that the prototype of the varexpand macro is this:

                #define varexpand(first_mac, rest_mac, ...)

              To  use  varexpand you must first write two macros: a one-argument macro whose name
              is passed as the first_mac argument, and two argument  macro  to  be  used  as  the
              rest_mac argument.

              Most  variadic  macros  written  with varexpand will pass through their __VA_ARGS__
              list as the ...  parameter; however, the splice macro can also  be  used  to  place
              parenthesized argument lists into that position

              Up  to  32 variadic arguments are accepted by varexpand beyond which there is over-
              flow detection up to 48 arguments, followed by unspecified behavior for 49 or  more
              arguments.

              Example: suppose we want to write a macro with an expansion like this:

                add(1) -> 1
                add(1, 2) -> 1 + 2
                add(1, 2, 3) -> 1 + 2 + 3

              First,  we must write a macro for handling the base case of the induction, which is
              used for the leftmost argument. The expansion is trivial:

                #define add_first(x) x

              The second macro is more complex. It takes two arguments. The left argument is  the
              accumulated  expansion  so far, of all the arguments previous to that argument. The
              right argument is the next argument to be added to the expansion.

                #define add_next(acc, x) acc + x

              For instance, if the arguments 1, 2 have already been expanded to 1  +  2  and  the
              next  argument is 3, then acc takes on the tokens 1 + 2, and x takes on 3. Thus the
              expansion is:

                add_next(1 + 2, 3) -> 1 + 2 + 3

              With these two macros, we can then write add like this:

                #define add(...) varexpand(add_first, add_next, __VA_ARGS__)

              More complex example: suppose we want an inline sum-of-squares  macro  which  works
              like this:

                sumsq(x)       -> ((x)*(x))
                sumsq(x, y, z) -> ((x)*(x) + (y)*(y) + (z)*(z))

              Note  the  detail that there are outer parentheses around the entire expansion, but
              the individual terms are not parenthesized, only the products. We write the  helper
              macros like this:

                #define sumsq_first(x)   (x)*(x)
                #define sumsq_next(a, x) a + sumsq_first(x)

              Note  that  sumsq_next reuses sumsq_first to avoid repeating the (x)*(x) term. Then
              we complete the implementation:

                #define sumsq(...) (varexpand(sumsq_first, \
                                              sumsq_next,\
                                              __VA_ARGS__))

              The outer parentheses are written around the varexpand call. In general,  varexpand
              can  be  just  a  small component of a larger macro expansion, and can be used more
              than one time in a macro expansion.

              Example: rlist macro which generates a  left-associative  nested  expression,  like
              this:

                rlist(1)        -> cons(1, Inil)
                rlist(1, 2)     -> cons(2, cons(1, nil))
                rlist(1, 2, 3)  -> cons(3, cons(2, cons(1, nil)))

              Implementation:

                #define rlist_first(x)    cons(x, nil)
                #define rlist_next(a, x)  cons(x, a)

                #define rlist(...)        varexpand(rlist_first, rlist_next, \
                                                    __VA_ARGS__)

              What  if  we  want  the consing to produce the list in order via right association,
              rather than in reverse? So that is to say:

                list(1, 2, 3)   -> cons(1, cons(2, cons(3, nil)))

              Here we simply take advantage of the revarg macro to reverse the arguments:

                #define list(...)         rlist(revarg(__VA_ARG__))

BUGS
       As noted in the DESCRIPTION, the narg, revarg and varexpand macros are limited to handling
       32 variadic arguments, beyond which there is a 16 argument safety margin with error detec-
       tion, followed by unspecified behavior.

       The C preprocessor doesn't support macro recursion, which forbids  some  complex  uses  of
       varexpand  whereby  the first_mac and next_mac macros themselves make use of varexpand.  A
       possible workaround is to clone the implementation of varexpand to  produce  an  identical
       macro  called  varexpand2.   This then allows for two "recursion" levels, whereby each one
       uses the macro under a different name.

AUTHOR
       Kaz Kylheku <kaz@kylheku.com>

COPYRIGHT
       Copyright 2022, BSD2 License.

cppawk Libraries                          29 March 2022                            CPPAWK-NARG(1)