path: root/cppawk-narg.1

CPPAWK-NARG(1)                           Variadic Macros                           CPPAWK-NARG(1)

NAME
       narg - macros for writing variable argument macros

SYNOPSIS
         #include <narg.h>

         #define narg(...)
         #define splice(args)
         #define varexpand(first_mac, rest_mac, ...)
         #define variexpand(first_mac, rest_mac, ...)
         #define variaexpand(first_mac, rest_mac, arg, ...)
         #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 macros in the <narg.h> header are varexpand and variexpand.

              These  macros are 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.  The variexpand macro is a variation on this, explained af-
              ter a complete description of varexpand is given.

              To understand varexpand it helps to understand the Lisp  reduce  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, nil)
                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__))

       variexpand
              The  variexpand  macro is very similar to varexpand.  The difference is that varex-
              pand passes an extra argument to both of the first_mac and  rest_mac  macros.  This
              argument  is  a decimal integer token indicating the master argument position being
              expanded.

              For instance, suppose we wish to have a macro with the following properties:

                series(a) -> a1
                series(a, b) -> a1 + b2
                series(a, b, c) -> a1 + b2 + c3

              Note that the numbers do not appear as arguments. The variexpand macro will  supply
              them:

                #define series_first(x, i) x ## i
                #define series_next(prev, x, i) prev + x ## i
                #define series(...) variexpand(series_first, series_next, \
                                               __VA_ARGS__)

              Here,  series_first  is always called with i  = 1, and series_next is called with i
              taking on the values 2, 3, ... .  The value of i indicates the  one-based  argument
              position of x in the series macro.

              One use for this is the generation of better temporary variables.  The C preproces-
              sor doesn't have a facility for generating temporary variable names. An unsatisfac-
              tory  substitute  is  the  use of some private namespace prefix like __x pasted to-
              gether with the expansion of the __LINE__ macro. However, macros can occur  in  the
              same  line  of code, or as arguments of a larger multi-line macro during the expan-
              sion of which __LINE__ is pinned to the same value.  If a large, multi-clause macro
              is based on variexpand, it can pass the argument number to its child clauses, which
              can combine it with __LINE__ and a prefix to generate unique variables.

       variaexpand
              One more macro in the varexpand family is variaexpand.

              Like variexpand, variaexpand also passes the argument number to its child  clauses.
              In  addition  to the argument number, it passes one more argument: a fixed argument
              specified in the variexpand invocation.

              For instance, suppose we wish to have a macro with the following properties:

                series(m, a) -> m(a1)
                series(m, a, b) -> m(a1) + m(b2)
                series(m, a, b, c) -> m(a1) + m(b2) + m(c3)

              In our expansion, we want the argument numbers to be put into  correspondence  with
              the arguments, and the argument x to be distributed into the terms:

                #define series_first(x, i, a) a(x ## i)
                #define series_next(prev, x, i, a) prev + a(x ## i)
                #define series(a, ...) variaexpand(series_first, \
                                                   series_next, \
                                                   a, __VA_ARGS__)

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.

       Both  narg()  and  narg(x) expand to 1. This is a "feature" of the preprocessor: the empty
       argument list is indistinguishable from an empty argument, because preprocessor  arguments
       are not required to be non-empty sequences of tokens. For instance if mac is a macro which
       may be called with two arguments, then mac(,) is a valid call, which passes two empty  ar-
       guments.  Consequently,  if  the comma is deleted from the syntax, then there is one empty
       argument.  The number of arguments is the number of commas plus one. This is why  narg  is
       specified  as  taking  one or more arguments: it is not possible for any macro to be given
       fewer arguments than one.

AUTHOR
       Kaz Kylheku <kaz@kylheku.com>

COPYRIGHT
       Copyright 2022, BSD2 License.

cppawk Libraries                          19 April 2022                            CPPAWK-NARG(1)