New man page: cppawk-iter.

1 files changed, 1554 insertions, 0 deletions

diff --git a/cppawk-iter.1 b/cppawk-iter.1
new file mode 100644
index 0000000..6618a90
--- /dev/null
+++ b/cppawk-iter.1
@@ -0,0 +1,1554 @@
+.\" 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 "18 April 2022" "cppawk Libraries" "Iteration"
+
+.SH NAME
+iter \- powerful, user-extensible iteration language for Awk
+
+.SH SYNOPSIS
+
+.ft B
+  #include <iter.h>
+
+  \fI// Simple, single-variable iteration\fP
+
+  doarray (\fIkey\fP, \fIvalue\fP, \fIarr\fP)       \fI// iterate over Awk assoc array\fP
+    \fIstatement\fP
+
+  dostring (\fIidx\fP, \fIchr\fP, \fIstr\fP)        \fI// iterate over string\fP
+    \fIstatement\fP
+
+  dofields (\fIidx\fP, \fIval\fP)             \fI// iterate over $1, $2, ..\fP
+    \fIstatement\fP
+
+  \fI// Multi-clause parallel and nested iteration\fP
+
+  loop (\fIclause1\fP, \fIclause2\fP, ...)    \fI// Parallel iteration\fP
+    \fIstatement\fP
+
+  loop_nest (\fIclause1\fP,             \fI// Nested iteration\fP
+             \fIclause2\fP,
+             parallel (\fIclause3\fP,
+                       \fIclause4\fP, ...),
+             ...)
+    \fIstatement\fP
+
+  \fI// Clauses for loop/loop_iter\fP
+
+  \fI// numeric stepping clauses\fP
+  range (\fIidx\fP, \fIfrom\fP, \fIto\fP)
+  range_step (\fIidx\fP, \fIfrom\fP, \fIto\fP, \fIstep\fP)
+  from (\fIidx\fP, \fIfrom\fP)
+  from_step (\fIidx\fP, \fIfrom\fP, \fIstep\fP)
+
+  \fI// general stepping clause\fP
+  first_then (\fIvar\fP, \fIfirst\fP, \fIthen\fP)
+
+  \fI// container traversal\fP
+  str (\fIidx\fP, \fIch\fP, \fIstr\fP)
+  list (\fIiter\fP, \fIvar\fP, \fIlist\fP)
+  fields (\fIvar\fP)
+  keys (\fIkey\fP, \fIarray\fP)
+
+  \fI// collect items into lists\fP
+  collect (\fIvar\fP, \fIexpr\fP)
+  collect_plus (\fIvar\fP, \fIexpr\fP)
+
+  \fI// calculating clauses\fP
+  summing (\fIvar\fP, \fIexpr\fP)
+  maximizing (\fIvar\fP, \fIexpr\fP)
+  minimizing (\fIvar\fP, \fIexpr\fP)
+  argmax (\fImaxvar\fP, \fIargvar\fP, \fIexpr\fP)
+  argmin (\fIminvar\fP, \fIargvar\fP, \fIexpr\fP)
+
+  \fI// termination control clauses\fP
+  while (\fIexpr\fP)
+  until (\fIexpr\fP)
+
+  \fI// parallel grouping combinator\fP
+  \fI// clause1, clause2, ... are parallel even in a loop_nest.\fP
+  parallel (\fIclause1\fP, \fIclause2\fP, ...)
+
+  \fI// conditional combinator:\fP
+  \fI// dependent clause steps/tests only whenever test is true\fP
+  if (\fItest\fP, \fIclause\fP)
+
+.ft R
+
+.SH OVERVIEW
+.bk
+The
+.B <iter.h>
+header provides constructs for expressing iteration. For simple loops that
+occur often \(em iterating over an array, string or the positional
+fields \(em several dedicated constructs are provided:
+.BR doarray ,
+.B dostring
+and
+.BR dofields .
+The separate
+.B <cons.h>
+header also provides simple iteration, for lists.
+
+In addition,
+.B <iter.h>
+provides a powerful general iteration facility which allows multiple
+variables to be iterated in parallel or nested loops, stepping over
+various kinds of spaces, with special clauses for calculation,
+collecting lists, or controlling termination.
+
+Furthermore, a new clauses may easily be defined by the application
+programmer, simply by defining six macros according to easy-to-follow
+rules.
+
+Clauses are susceptible to macro expansion: new clauses can be defined
+by writing macros that expand to existing clauses.
+
+In all of the iteration constructs of
+.B <iter.h>
+the variables which are supplied by the application are subject to assignment;
+the constructs do not bind these variables.  It is up to the application to
+control the scope of these variables.
+
+In general, immediately after the termination of these looping constructs,
+the variables explicitly specified by the application code remain visible,
+and continue to hold the values they had immediately prior to loop termination.
+
+.SH SIMPLE ITERATION
+.bk
+.SS Macro \fIdoarray\fP
+.bk
+.B Syntax:
+
+.ft B
+  doarray (\fIkey\fP, \fIvalue\fP, \fIarr\fP)
+    \fIstatement\fP
+.ft R
+
+.B Description:
+
+The
+.B doarray
+macro executes the
+.I statement
+for every element of the associative array
+.IR arr .
+Prior to each iteration, the variables
+.I key
+and
+.I value
+are set to the next key and value to be visited.
+
+Awk associative arrays are not required to maintain order; thus
+.B doarray
+does not traverse
+.I arr
+in any required order.
+
+.B Example:
+
+.ft B
+  \fI// assuming a is prepared like this:\fP
+  split("a:b:c", \fIa\fP, /:/)
+
+  \fI// possible output is\fP
+  \fI// 3 c\fP
+  \fI// 1 a\fP
+  \fI// 2 b\fP
+  doarray (\fIk\fP, \fIv\fP, \fIa\fP)
+    print \fIk\fP, \fIv\fP
+.ft R
+
+.SS Macro \fIdostring\fP
+.bk
+.B Syntax:
+
+.ft B
+  dostring (\fIidx\fP, \fIchr\fP, \fIstr\fP)
+    \fIstatement\fP
+.ft R
+
+.B Description:
+
+The
+.B dostring
+macro evaluates
+.I statement
+for all successive substrings of length 1 of string
+.IR str .
+The variable
+.I idx
+steps from 1 up to the length of
+.IR str ,
+and the
+.I chr
+variable takes on string values of length 1. On the first iteration,
+.I chr
+contains the first character of
+.IR str ,
+then on the second iteration the second character and so forth.
+
+The
+.I str
+expression is evaluated only once.
+
+.B Example:
+
+.ft B
+  \fI// output is:\fP
+  \fI// 1 a\fP
+  \fI// 2 b\fP
+  \fI// 3 c\fP
+  dostring (\fIi\fP, \fIch\fP, "abc")
+    print \fIi\fP, \fIch\fP
+.ft R
+
+.SS Macro \fIdofields\fP
+.bk
+.B Syntax:
+
+.ft B
+  dofields (\fIidx\fP, \fIval\fP)
+    \fIstatement\fP
+.ft R
+
+.B Description:
+
+The
+.B dofields
+macro iterates over the Awk positional fields, executing
+.I statement
+for each iteration. The
+.I idx
+variable is initialized to 1. Before every iteration,
+.I idx
+is compared compared to the current value of
+.BR NR .
+The iteration proceeds if
+.I i
+.B <=
+.B NR
+is true. After the execution of
+.IR statement ,
+.I idx
+is incremented by one.
+
+Before each iteration,
+.I val
+is set to the value of the positional field indicated by
+.IR idx ,
+namely \fB$\fP\fIidx\fP.
+
+.B Example:
+
+.ft B
+  \fI// set fields, assuming default FS\fP
+  $0 = "the quick brown fox"
+
+  \fI// output is:\fP
+  \fI// 1 the\fP
+  \fI// 2 quick\fP
+  \fI// 3 brown\fP
+  \fI// 4 fox\fP
+  dofields (i, v)
+    print \fIi\fP, \fIv\fP
+.ft P
+
+.SH THE LOOP MACRO
+.bk
+.SH Macro \fIloop\fP
+.bk
+.B Syntax:
+
+.ft B
+  loop (\fIclause1\fP, \fIclause2\fP, ...)
+    \fIstatement\fP
+.ft R
+
+.B Description:
+The
+.B loop
+macro repeatedly executes
+.I statement
+under the control of one or more clauses:
+.IR clause1 ,
+.iR clause2 ,
+...
+
+Each clause contributes to the initial loop conditions, termination
+testing, and actions of the loop. Under
+.B loop
+the clauses act in parallel. The same clauses may be combined into
+a nested loop using the
+.B loop_nest
+macro. The term
+.I parallel
+here doesn't refer to concurrent processing with threads or processors,
+but to the lock-step performance of loop iteration steps.
+
+Each clause communicates to
+.B loop the following:
+.IP initialization
+What variable are to be be prepared with what initial values.
+.IP termination
+What conditions will terminate the loop. Prior to each iteration,
+the termination test from every clause is interrogated. The loop
+.I statement
+executes only if all clauses indicate continued execution. If at least
+one clause calls for termination, the loop ends.
+.IP preparation
+Whenever all clauses indicate that the loop continues, each clause
+has the opportunity to make some preparation prior to the execution of
+the loop, such as calculating the values of some variables.
+.IP stepping
+After the execution of each statement, each clause has the opportunity
+to perform some increment step.
+.IP finalization
+When the loop terminates, some clauses execute some special code to
+bring about a needed final state in their variables, or for some
+other reason.
+.PP
+
+The Awk
+.B break
+and
+.B continue
+statements are usable inside
+.B loop
+and behave like they do inside the
+.B for
+construct. The
+.B break
+statement terminates the loop, and
+.B continue
+terminates the
+.I statement
+only, proceeding to the increment step which prepares for the next
+iteration.
+
+.B Example:
+
+.ft B
+  \fI// step variable i from 1 to 5 by 1,\fB
+  \fI// and variable j from 100 to 500 in steps of 100.\fB
+
+  \fI// output is:\fB
+  \fI// 1 100\fB
+  \fI// 2 200\fB
+  \fI// 3 300\fB
+  \fI// 4 400\fB
+  \fI// 5 500\fB
+
+  loop (range (\fIi\fB, 1, 5),
+        range_step (\fIj\fB, 100, 500, 100))
+  {
+    print \fIi\fB, \fIj\fB
+  }
+.ft R
+
+More example are given in the documentation of the clauses.
+
+.SH Macro \fIloop_nest\fP
+.bk
+.B Syntax:
+
+.ft B
+  loop_nest (\fIclause1\fP, \fIclause2\fP, ...)
+    \fIstatement\fP
+.ft R
+
+.B Description:
+The
+.B loop_nest
+macro has a syntax resembling that of
+.BR loop .
+Unlike
+.BR loop ,
+it generates a nested loop: the logic of the clauses is arranged
+into loop nestings. Each clause controls its own loop, in which
+the loops of subsequent clauses are nested. In effect, the
+.B loop_nest
+syntax is a shorthand for writing:
+
+.ft B
+  loop (\fIclause1\fP)
+    loop (\fIclause2\fP)
+      loop (\fIclause3\fP)
+        ...
+          loop (\fIclauseN\fP)
+            \fIstatement\fP
+.ft R
+
+There is a special clause called
+.B parallel
+which is useful inside a
+.BR loop_nest .
+Detailed documentation for it is given in its own section. The
+.B parallel
+clause combines multiple clauses into a single clause, in such a way
+that those clauses are executed in parallel regardless of which loop
+macro is used. Therefore the following equivalence also holds:
+
+Note: consistently with the semantics of
+.B loop_nest
+being that of the above shorthand, the
+.B break
+and
+.B continue
+statements affect only the innermost loop corresponding to the last clause,
+.IR clauseN .
+The
+.B break
+statement only breaks out of that loop, and
+.B continue
+only skips to the iteration part of that loop.
+
+Note: the semantics of all clauses such as termination control clauses and list
+collection clauses must also be understood in terms of the nesting.
+For instance if a collect clause is nested inside another loop which
+repeats three times, then that collection will be repeated three times:
+the collection variable will be initialized three times, collection
+will be performed three times. Only the items collected by the last of
+the three repetitions of the collect loop will be retained. Or, if instead
+of collect, maximize is used to calculate a maximum value, then three
+maxima will be calculated over the three invocations of the maximizing
+loop, only the effect of the last of which will be retained in the
+variable which receives the maximum value.
+
+.ft B
+  loop (\fIclause1\fP, \fIclause2\fP, ..., \fIclause\fP)
+    \fIstatement\fP
+.ft R
+
+may be achieved using
+
+.ft B
+  loop_nest (parallel (\fIclause1\fP, \fIclause2\fP, ..., \fIclauseN\fP))
+    \fIstatement\fP
+.ft R
+
+.B Example:
+
+.ft B
+  #include <iter.h>
+  #include <cons.h>
+
+  BEGIN {
+    loop_nest (list(it, let, list("a", "b", "c")),
+               range(x, 1, 3))
+      print let "-" x
+  }
+
+  Output:
+
+  a-1
+  a-2
+  a-3
+  b-1
+  b-2
+  b-3
+  c-1
+  c-2
+  c-3
+.ft R
+
+.SH LOOP CLAUSES: NUMERIC AND GENERAL STEPPING
+.bk
+.SS Loop clauses \fIrange\fP and \fIrange_step\fP
+.bk
+.B Syntax:
+
+.ft B
+  range (\fIidx\fP, \fIfrom\fP, \fIto\fP)
+  range_step (\fIidx\fP, \fIfrom\fP, \fIto\fP, \fIstep\fP)
+.ft R
+
+.B Description:
+
+The
+.B range
+loop clause initializes the
+.I idx
+variable to the value of the
+.I from
+expression. Prior to each loop iteration, the expression
+.BI idx " <= (to)
+is tested. If it is false, the loop terminates.
+After each execution of
+.IR statement ,
+.I idx
+is incremented by 1.
+The
+.I to
+expression is reevaluated at the beginning of each iteration,
+so its value may change.
+
+The
+.B range_step
+clause is a variation of
+.B range
+which allows the amount added to
+.I idx
+to be specified as the
+.I step
+expression. The
+.I step
+expression is evaluated after each iteration, so its
+value may change. That value is added to
+.I idx .
+
+Note:
+.B loop
+clauses may not have optional arguments; it is not possible
+to write a single loop clause which takes an optional step
+size that defaults to 1.
+
+.SS Loop clauses \fIfrom\fP and \fIfrom_step\fP
+.bk
+.B Syntax:
+
+.ft B
+  from (\fIidx\fP, \fIfrom\fP)
+  from_step (\fIidx\fP, \fIfrom\fP, \fIstep\fP)
+.ft R
+
+.B Description:
+
+The
+.B from
+clause is similar to
+.BI range ,
+except that the
+.I to
+expression is missing. The clause performs no termination test;
+it initializes
+.I idx
+to the
+.I from
+value and then executes indefinitely, forever incrementing
+.B idx
+by one. In order for the loop to terminate, another clause must
+be present which requests termination, or else
+.B break
+must be used to terminate the loop abruptly.
+
+The
+.B from_step
+clause is a variant of
+.B from
+which allows the amount added to
+.I idx
+at the increment step to be determined by the value of the
+.I step
+expression, which is reevaluated each time.
+
+.SH LOOP CLAUSES: CONTAINER TRAVERSAL
+.bk
+.SS Loop clause \fIstr\fP
+.bk
+.B Syntax:
+
+.ft B
+  str (\fIidx\fP, \fIch\fP, \fIstr\fP)
+.ft P
+
+.B Description:
+
+The
+.B str
+loop clause iterates over a string. The
+.I str
+expression is evaluated once to produce a string. The
+.I idx
+variable steps from 1 to up to the length of the string.
+If the string is empty, the loop terminates without
+any iterations taking place.
+Prior to each iteration, the
+.I ch
+variable is set to a one-character-long substring of the
+string starting at the
+.I idx
+position.
+
+.SS Loop clause \fIlist\fP
+.bk
+.B Syntax:
+
+.ft B
+  list (\fIiter\fP, \fIvar\fP, \fIlist\fP)
+.ft R
+
+.B Description:
+
+The
+.B list
+loop clause iterates over the elements of a list.
+Note:
+the inclusion of the
+.B <iter.h>
+header does not make visible list manipulation libraries such as
+.BR <cons.h> ,
+
+The
+.I iter
+variable is initialized to
+.IR list .
+Prior to each iteration,
+.I iter
+is tested for termination as if using the
+.B endp
+function. If
+.I iter
+refers to a nonempty list, and thus iteration may continue, then
+.I var
+is set to the first item in
+.IR iter ,
+.BI car( iter ) \fR,\fP
+prior to the execution of the loop
+.IR statement .
+
+After each iteration,
+.B iter
+is replaced with
+.BI cdr( iter ) \fR.\fP
+
+.SS Loop clause \fIfields\fP
+.bk
+.B Syntax:
+
+.ft B
+  fields (\fIvar\fP)
+.ft R
+
+.B Description:
+
+The
+.B fields
+loop clause iterates over the Awk positional fields. An internal
+counter is initialized to 1. Iteration proceeds if this counter is
+less than or equal to the current value of
+.BR NF .
+The counter is incremented by 1 after each iteration.
+
+Prior to the execution of the loop
+.IR statement ,
+.I var
+is set to the field indicated by the internal counter.
+
+.SS Loop clause \fIkeys\fP
+.bk
+.B Syntax:
+
+.ft B
+  keys (\fIkey\fP, \fIarray\fP)
+.ft R
+
+.B Description:
+
+The
+.B keys
+loop clause iterates over the keys (indices) of an Awk associative
+array named by the
+.I array
+parameter. The
+.I key
+variable is set to each index in turn. The keys are not visited in
+any specific, required order.
+
+.SH LOOP CLAUSES: COLLECTION INTO LISTS
+.bk
+.SS Loop clauses \fIcollect\fP and \fIcollect_plus\fP
+.bk
+.B Syntax:
+
+.ft B
+  collect (\fIvar\fP, \fIexpr\fP)
+  collect_plus (\fIvar\fP, \fIexpr\fP)
+.ft R
+
+.B Description:
+
+The
+.B collect
+clause initializes
+.I var
+to an empty bag object as if by using the
+.B list_init
+macro from
+.BR <cons.h> .
+The clause provides no termination test; if the only clauses in a
+.B loop
+are
+.B collect
+clauses, then it will not terminate. Prior each execution of the
+.IR statement ,
+the
+.B collect
+clause evaluates
+.I expr
+and replaces
+.B var
+with a new bag which contains that value, as if by the expression
+.IB var " = list_add(" var ", " expr ) \fR.\fP
+When the loop terminates,
+.I var
+is replaced with a list formed from the bag which it used to hold,
+as if by
+.IB var " = list_end(" var ) \fR.\fP
+The effect is that
+.I var
+ends up with a list of the values of
+.I expr
+that were sampled before each iteration of the loop.
+
+The
+.B collect_plus
+clause is almost exactly the same as
+.B collect
+except in regard to the final behavior. When the loop terminates,
+.B collect_plus
+collects the value of
+.I expr
+one more time prior to the conversion to list.
+The effect is that
+.I var
+ends up with a list of all the values of
+.I expr
+that were sampled before each iteration of the loop, as well
+as one more sample of
+.I expr
+taken after loop termination.
+
+.SH LOOP CLAUSES: CALCULATION
+.bk
+.SS Loop clause \fIsumming\fP
+.bk
+.B Syntax:
+
+.ft B
+  summing (\fIvar\fP, \fIexpr\fP)
+.ft R
+
+.B Description:
+
+The
+.B summing
+clause calculates the sum of the values of
+.I expr
+over the course of the loop.
+The clause contains no provision for termination; if the only
+clause in a
+.B loop
+is
+.B summing
+then it will not terminate.
+
+The
+.B summing
+clause initializes
+.B var
+to zero. Prior to each execution of the loop's
+.IR statement ,
+.I expr
+is evaluated and its value added to to
+.IR var .
+
+The effect is that after the loop terminates,
+.I var
+ends up with the sum of the samples of the value of
+.I expr
+from before each iteration of the loop.
+
+.SS Loop clauses \fIminimizing\fP and \fImaximizing\fP
+.bk
+.B Syntax:
+
+.ft B
+  maximizing (\fIvar\fP, \fIexpr\fP)
+  minimizing (\fIvar\fP, \fIexpr\fP)
+.ft R
+
+.B Description:
+
+The
+.B minimizing
+and
+.B maximizing
+clauses initialize
+.I var
+to the value
+.IR nil  .
+(See the
+.B cppawk-cons
+manual page for
+.BR <cons.h> ).
+
+Prior to each execution of the loop
+.IR statement ,
+.I var
+is updated as follows.
+If
+.I var
+is
+.BR nil ,
+then it receives the value of
+.IR expr ,
+thereby establishing that value as the hitherto calculated minimum or
+maximum. If
+.I var
+is not already
+.BR nil ,
+then
+.B minimize
+updates it with the value of
+.I expr
+if that value is smaller than
+.IR var ,
+and similarly,
+.B maximize
+replaces
+.I var
+with the value of
+.I expr
+if that value is greater than
+.IR var .
+
+Neither
+.B minimize
+nor
+.B maximize
+bring about loop termination.
+
+The effect of these clauses it to calculate the minimum or
+maximum observed of value of
+.I expr
+as sampled before each execution of the loop statement.
+If the loop never executes the
+.IR statement ,
+then
+.I var
+retains the
+.B nil
+value indicating that no minimum or maximum had been found.
+
+.SS Loop clauses \fIargmax\fP and \fIargmin\fP
+.bk
+.B Syntax:
+
+.ft B
+  argmax (\fImaxvar\fP, \fIargvar\fP, \fIexpr\fP)
+  argmin (\fIminvar\fP, \fIargvar\fP, \fIexpr\fP)
+.ft R
+
+.B Description:
+
+The
+.B argmax
+and
+.B argmin
+clauses calculate the value of a variable
+.I argvar
+which maximize or minimizes the value of
+.IR expr .
+
+This maximum or minimum value appears in
+.I maxvar
+or
+.IR minvar
+respectively.
+
+The purpose of the
+.I argvar
+argument is to name the variable that is being maximized
+or minimized. It is expected that the
+.I expr
+expression contains
+.I argvar
+and thus its value is dependent on
+.IR argvar .
+
+Like
+.B minimize
+and
+.BR maximize ,
+these clauses never bring about loop termination.
+
+First,
+.I minvar
+or
+.I maxvar
+is initialized to the
+.B nil
+value.
+(See the
+.B cppawk-cons
+manual page for
+.BR <cons.h> ).
+
+If the loop
+.I statement
+never executes, then these variables retain the
+.B nil
+value to indicate that no argument maximum or minimum was calculated.
+
+Prior to each execution of
+.IR statement ,
+.I expr
+is evaluated. If it is the first iteration, then
+.I maxvar
+or
+.I minvar
+is set to the value of
+.IR argvar .
+If it is the second or subsequent iteration, then
+.B argmax
+sets
+.I maxvar
+to the value of
+.I argvar
+if
+.I expr
+is higher than the previously seen maximum value of
+.IR expr .
+Likewise,
+.B argmin
+sets
+.I minvar
+to the value of
+.I argvar
+if
+.I expr
+is lower than the previously seen minimum value of
+.IR expr .
+
+.B Example:
+
+Find the values of
+.I x
+where the expression
+.BI sin( x ") * cos(" x )
+has a maximum and minimum value, over the
+.I x
+range 0 to 3.14159 examined in
+increments of 0.001.
+
+Note that the variable used as
+.IR argvar ,
+namely
+.I x
+is made to vary by the use of a
+.I range_step
+clause. For
+.B argmax
+and
+.B argmin
+to be useful, the argument variable has to vary from one iteration
+to the next, and the
+.I expr
+has to be a function of that variable.
+
+.ft B
+  #include <iter.h>
+
+  BEGIN {
+    loop (range_step  (\fIx\fP, 0, 3.14159, 0.001),
+          argmax      (\fImx\fP, \fIx\fP, sin(\fIx\fP) * cos(\fIx\fP)),
+          argmin      (\fImi\fP, \fIx\fP, sin(\fIx\fP) * cos(\fIx\fP)))
+      ; // empty
+
+    print "max x =", \fImx\fP
+    print "min x =", \fImi\fP
+  }
+.ft R
+
+Output:
+
+.ft B
+  max x = 0.785
+  min x = 2.356
+.ft R
+
+.SH LOOP CLAUSES: TERMINATION CONTROL
+.bk
+.SS Loop clauses \fIwhile\fP and \fIuntil\fP
+.bk
+.B Syntax:
+
+.ft B
+  while (\fIexpr\fP)
+  until (\fIexpr\fP)
+.ft R
+
+.B Description:
+
+The
+.B while
+and
+.B until
+clauses provide a termination test to the loop.
+
+Prior to each iteration,
+.I expr
+is evaluated.
+
+Under the
+.B while
+clause, if
+.I expr
+is false. the loop terminates.
+
+Under the
+.B until
+clause, if
+.I expr
+is true, the loop terminates.
+
+Loop terminations are short circuited among parallel clauses.
+So that is to say, if an earlier clause indicates loop
+termination, then the termination tests of later clauses are not performed.
+Moreover, the preparation actions of
+.B no
+clause are performed when the loop terminates; only if it has
+been confirmed that the
+.I statement
+is going to be executed, due to the termination tests from all
+clauses reporting false, are the preparation actions executed.
+Therefore, in any iteration, later termination tests can rely on earlier
+termination tests having executed. For instance, if the success of an earlier
+termination test implies that a certain variable is safe to use in certain way,
+then a later termination test may use it in that way. Likewise, loop
+preparations may rely on all termination tests having executed.
+
+All tests in loop, including
+.B while
+and
+.B until
+are top-of-loop tests: tests carried out before every iteration,
+including the first.  A bottom-of-loop test is one which is carried out after
+each iteration, which is logically equivalent to a top-of-loop test which is
+unconditionally true before the first iteration, and then turns into a
+.I "bona fide"
+test. A bottom-of-loop testing version of
+.B while
+or
+.B until
+isn't provided in
+.B <iter.h>
+but can be developed as an application-defined clause. It may also
+be simulated with the help of the first_then clause, according
+to this pattern:
+
+.ft B
+  loop_for (first_then (\fIfirst_iter\fP, 1, 0),
+            while (\fIfirst_iter\fP || \fIother_condition\fP))
+    statement
+.ft R
+
+Here, the
+.B first_iter
+flag is initialized to 1, and then after the first iteration steps to 0.
+Therefore the
+.B while
+clause's test is always true before the first iteration, and
+.I other_condition
+isn't tested.
+
+.SH LOOP CLAUSES: COMBINATORS
+.bk
+.SS Loop clause \fIparallel\fP
+.bk
+.B Syntax:
+
+.ft B
+  parallel (\fIclause1\fP, \fIclause2\fP, ...)
+.ft R
+
+.B Description:
+
+The
+.B parallel
+construct may be used in the
+.B loop_nest
+macro, to indicate groups of clauses that should not be nested
+but treated in parallel.
+
+The
+.B parallel
+clause takes one or more arguments which are loop clauses.
+It arranges for the argument clauses to be performed
+in parallel, just like the way clauses are treated by the
+.B loop
+construct.
+
+For instance, the structure:
+
+.ft B
+  loop_nest (\fIclause1\fP,
+             parallel (\fIclause2\fP, \fIclause3\fP),
+             \fIclause4\fP)
+    \fIstatement\fP
+.ft R
+
+may be understood as equivalent to:
+
+.ft B
+  loop (\fIclause1\fP)
+    loop (\fIclause2\fP, \fIclause3\fP)
+      loop (\fIclause4\fP)
+        \fIstatement\fP
+.ft R
+
+.S Loop clause \fIif\fP
+.bk
+.B Syntax:
+
+.ft B
+  if (\fItest\fP, \fIclause\fP)
+.ft R
+
+.B Description:
+
+The
+.B if
+clause activates or deactivates the contained
+.I clause
+based on the value of the
+.I test
+expression.
+
+Firstly, the initializations of
+.I clause
+are performed unconditionally, as if it were not embedded in
+.BR if .
+
+Prior to every iteration, if the
+.I test
+expression is false, then
+.IR clause 's
+tests are not performed, and are assumed to be true. Thus while
+.I test
+is true,
+.I clause
+is prevented from being able to terminate the loop.
+
+Secondly, prior to the execution of the loop
+.IR statement ,
+.I test
+is evaluated again. If the expression is false, then the
+preparation actions of
+.I clause
+are skipped.
+
+Lastly, prior to the execution of the iteration step actions.
+expression is false, then the step actions of
+.I clause
+are skipped.
+
+Effectively, the
+.I clause
+is suspended while the
+.I test
+expression is false.
+
+.B Example:
+
+Print a row number before the first element of every row. While
+this specific program can be coded much more succinctly, the goal
+is to demonstrate how the
+.B first_then
+clause is activated by the the condition
+.IB i " % 10 =="
+.BR 1 .
+
+.ft B
+  #include <iter.h>
+
+  function row(\fIpg\fP)
+  {
+    if (\fIpg\fP > 1)
+      print
+    printf "r%03d", \fIpg\fP
+    return \fIpg\fP
+  }
+
+  BEGIN {
+    loop (range(\fIi\fP, 1, 100),
+          if (\fIi\fP % 10 == 1, first_then(\fIpg\fP, row(1), row(\fIpg\fP + 1))))
+      printf " %3d", \fIi\fP
+  }
+.ft R
+
+.B Output:
+
+.ft B
+  r001   1   2   3   4   5   6   7   8   9  10
+  r002  11  12  13  14  15  16  17  18  19  20
+  r003  21  22  23  24  25  26  27  28  29  30
+  r004  31  32  33  34  35  36  37  38  39  40
+  r005  41  42  43  44  45  46  47  48  49  50
+  r006  51  52  53  54  55  56  57  58  59  60
+  r007  61  62  63  64  65  66  67  68  69  70
+  r008  71  72  73  74  75  76  77  78  79  80
+  r009  81  82  83  84  85  86  87  88  89  90
+  r010  91  92  93  94  95  96  97  98  99 100
+.ft R
+
+.SH USER-DEFINED CLAUSES
+.bk
+It is possible to define new clauses for the
+.B loop
+macro, in application code.
+
+.SS Definition via Macro
+
+One method by which a user defined
+.B loop
+clause is possible is by writing it as a macro.
+This is because clauses look like macro invocations
+and are susceptible to expansion.
+
+.B Example:
+
+Introduce a
+.BI repeat( n )
+clause that repeats
+.I n
+times, where
+.I n
+is an expression.
+
+.ft B
+  #define repeat(n) range(repeat_counter_ ## __LINE__, 1, (n))
+.ft R
+
+.SS Primary Definition
+
+An entirely new loop clause is developed by writing six macros,
+one of which is required only if the
+.I egawk
+(Enhanced GNU Awk) implementation of Awk is being used.
+The macros have names which are derived from the name of the clause.
+
+For example, to implement a clause called
+.BR myclause ,
+the following macros must be written:
+.BR __temp_myclause ,
+.BR __init_myclause ,
+.BR __test_myclause ,
+.BR __prep_myclause ,
+.B __fini_myclause
+and
+.BR __step_myclause .
+The
+.BR __temp_myclause
+macro is not used unless the Awk implementation is
+.I egawk .
+
+All six macros must accept exactly the same arguments, and those
+will be the arguments that the clause will accept. They are described
+next:
+
+.IP \fB__temp_\fP
+The
+.I temp
+macro must expand to a comma-terminated list of temporary variable names which
+are needed by the clause. If the clause needs no hidden temporary variables,
+then this must expand to a terminating comma. Under the
+.I egawk
+implementation, these variables will be accumulated into a
+.B @let
+construct which precedes the loop, so that they are introduced as lexical
+variables visible only inside the loop.
+
+.IP \fB__init_\fP
+The
+.I init
+macro must expand to an expression which performs variable initializations.
+If the clause requires no initializations, its expansion must be the
+numeric token
+.BR 1 .
+
+.IP \fB__test_\fP
+The
+.I test
+macro must expand to an expression whose value is true if, and only if, the
+clause wishes the loop to terminate. If the clause does not terminate the
+loop, the expansion of this macro must be the numeric token
+.BR 1 .
+
+.IP \fB__prep_\fP
+The
+.I prep
+macro must expand to an expression that the clause needs to evaluate
+prior to the execution of the loop's iteration statement. This is evaluated
+only if all clauses have indicated that the loop isn't terminating,
+and hence the statement is going to be executed.
+
+.IP \fB__fini_\fP
+The
+.I fini
+macro must expand to an expression that the clause needs to evaluate
+in the situation when the loop terminates. If any termination test from
+any clause of a
+.B loop
+indicates that the loop must terminate, then the loop
+.I statement
+will not be executed any more; instead, the
+.I fini
+expressions of all the clauses will be evaluated, and then the loop
+ends. If a clause does not have any
+.I fini
+action, then this macro must expand to the token
+.BR 1 .
+
+.IP \fB__step_\fP
+The
+.I step
+macro must expand to an expression which is evaluated after every
+execution of the loop
+.I statement ,
+in order to prepare new values of loop variables for the next iteration.
+Here is where numeric step variables are incremented and so forth.
+If the clause doesn't step, then this must expand to
+.BR 1 .
+
+.SS Example: \fBnull\fP clause
+
+Suppose we wish to define a clause called
+.B null
+which takes no arguments and does nothing. A loop which contains
+only this clause iterates forever. If the clause is added to any
+.BR loop ,
+the semantics remains unchanged. The entire implementation is
+this:
+
+.ft B
+  #include <iter.h>
+
+  #define __temp_null ,
+  #define __init_null 1
+  #define __test_null 1
+  #define __prep_null 1
+  #define __fini_null 1
+  #define __step_null 1
+
+  BEGIN {
+    loop (range (i, 1, 5),
+          null) // does nothing
+      print i
+  }
+.ft R
+
+.SS Example: alpha-numeric stepping.
+.bk
+Suppose we have a function
+.BI nxstr( s ", " u )
+which behaves as follows, on these example inputs:
+
+.ft B
+  nxstr("000", "999") -> "001"
+  nxstr("007", "777") -> "010"
+  nxstr("abc", "zzz") -> "abd"
+  nxstr("xxx", "yyy") -> "xxy"
+  nxstr("xxy", "yyy") -> "xya"
+  nxstr("yyx", "yyy") -> "yyy"
+  nxstr("yyy", "yyy") -> 0
+.ft R
+
+The function
+.BI nxstr
+implements a relation that could could be called "alpha-numeric step",
+where the second argument indicates limiting characters.
+
+A precise specification follows.
+Firstly, both
+.I s
+and
+.I u
+are alphanumeric strings of equal length, consisting of nothing but
+digits or the 26 letters of the English alphabet, in either upper or lower
+case. Furthermore, for every character in
+.IR s ,
+the corresponding character in
+.I u
+is in the same category: digit, lower case or upper case, and
+that corresponding character has a rank at least as high.
+For instance, where
+.I s
+has the character
+.B p ,
+.I u
+may have the characters
+.BR p ,
+.BR q ,
+.BR r ...
+but not
+.B o
+because
+.B o
+has a lower rank, and not
+.B X
+or
+.B 7
+because they are in a different category.
+
+The
+.I u
+argument gives an upper limit. If
+.I s
+is identical to
+.I u
+then
+.B nxstr
+returns 0. Otherwise
+.B nxstr
+returns the next alphanumeric string derived from
+.I s
+as follows: if the last character is equal to the corresponding one in
+.I s
+then it is reset to the leading element of the category, otherwise
+it is replaced by its successor. In the case when the character is reset, the
+procedure is repeated with the character to the left, to increment the next
+digit. If that one is reset, then again, to the left and so forth.
+
+We would like to implement a loop clause which steps a variable
+.I s
+through a range of strings, as in
+.BI alpha_range( s ", \(dqaa0\(dq, \(dqcc9\(dq" )
+to step through the strings "aa0", "aa1", ... "aa9", "ab0", ... "ab9", ... "cc0", ... "cc9".
+
+.ft B
+  #include <iter.h>
+
+  \fI// ... implementation of nxstr goes here ...\fP
+
+  #define __temp_alpha_range(\fIs\fP, \fIfrom\fP, \fIto\fP) 1
+  #define __init_alpha_range(\fIs\fP, \fIfrom\fP, \fIto\fP) \fIs\fP = \fIfrom\fP
+  #define __test_alpha_range(\fIs\fP, \fIfrom\fP, \fIto\fP) \fIs\fP
+  #define __prep_alpha_range(\fIs\fP, \fIfrom\fP, \fIto\fP) 1
+  #define __fini_alpha_range(\fIs\fP, \fIfrom\fP, \fIto\fP) 1
+  #define __step_alpha_range(\fIs\fP, \fIfrom\fP, \fIto\fP) \fIs\fP = nxstr(\fIs\fP, \fIto\fP)
+
+  BEGIN {
+    loop (alpha_range (\fIx\fP, "aa0", "cc9"))
+      print \fIx\fP
+  }
+.ft R
+
+A working implementation of
+.B nxstr
+follows:
+
+.ft B
+  // "register nextchar"
+  function rn(x, y,
+              c)
+  {
+    nextchar[x] = y
+    if (y in nextchar) {
+      resetchar[x] = y
+      for (c = y; nextchar[c] != y; c = nextchar[c])
+        resetchar[c] = y
+    }
+  }
+
+  BEGIN {
+    rn("0", "1"); rn("1", "2"); rn("2", "3"); rn("3", "4");
+    rn("4", "5"); rn("5", "6"); rn("6", "7"); rn("7", "8");
+    rn("8", "9"); rn("9", "0");
+
+    rn("a", "b"); rn("b", "c"); rn("c", "d"); rn("d", "e");
+    rn("e", "f"); rn("f", "g"); rn("g", "h"); rn("h", "i");
+    rn("i", "j"); rn("j", "k"); rn("k", "l"); rn("l", "m");
+    rn("m", "n"); rn("n", "o"); rn("o", "p"); rn("p", "q");
+    rn("q", "r"); rn("r", "s"); rn("s", "t"); rn("t", "u");
+    rn("u", "v"); rn("v", "w"); rn("w", "x"); rn("x", "y");
+    rn("y", "z"); rn("z", "a");
+
+    rn("A", "B"); rn("B", "C"); rn("C", "D"); rn("D", "E");
+    rn("E", "F"); rn("F", "G"); rn("G", "H"); rn("H", "I");
+    rn("I", "J"); rn("J", "K"); rn("K", "L"); rn("L", "M");
+    rn("M", "N"); rn("N", "O"); rn("O", "P"); rn("P", "Q");
+    rn("Q", "R"); rn("R", "S"); rn("S", "T"); rn("T", "U");
+    rn("U", "V"); rn("V", "W"); rn("W", "X"); rn("X", "Y");
+    rn("Y", "Z"); rn("Z", "A");
+  }
+
+  function nxstr(str, upto,
+                 l, sdig, udig, nxdig)
+  {
+    if (str == upto)
+      return 0
+
+    len = length(str)
+
+    for (; len > 0; --len) {
+      sdig = substr(str, len, 1)
+      udig = substr(upto, len, 1)
+
+      if (sdig == udig)
+        nxdig = resetchar[sdig]
+      else
+        nxdig = nextchar[sdig]
+
+      str = substr(str, 1, len - 1) nxdig substr(str, len + 1)
+
+      if (sdig != udig)
+         break
+    }
+
+    return str
+  }
+.ft R
+
+.SH "SEE ALSO"
+
+cppawk(1)
+
+.SH BUGS
+
+The
+.B parallel
+clause cannot be used in
+.BR loop ,
+which prevents it from being useful in macro implementations of
+clauses. This is because it relies on a macro that is also being used
+in the expansion of
+.B loop .
+This issue is discussed in the BUGS section of the main
+.B cppawk
+man page.
+
+.SH AUTHOR
+Kaz Kylheku <kaz@kylheku.com>
+
+.SH COPYRIGHT
+Copyright 2022, BSD2 License.