@@@ tvec wip

[mLib] / utils / control.3

.\" -*-nroff-*-
.TH control 3 "23 April 2023" "Straylight/Edgeware" "mLib utilities library"
.SH NAME
control \- control structure metaprogramming
.\" @MC_BEFORE
.\" @MC_AFTER
.\" @MC_WRAP
.\" @MC_FINALLY
.\" @MC_DOWHILE
.\" @MC_DECL
.\" @MC_LOOPELSE
.\" @MC_LOOPBETWEEN
.\" @MC_ALLOWELSE
.\" @MC_GOELSE
.\" @MC_TARGET
.\" @MC_GOTARGET
.\" @MC_ACT
.\" @MC_LABEL
.\" @MC_GOTO
.SH SYNOPSIS
.nf
.B "#include <mLib/control.h>"

.BI MC_BEFORE( tag ", " stmts ") " body
.BI MC_AFTER( tag ", " stmts ") " body
.BI MC_WRAP( tag ", " before_stmt ", " onend_stmt ", " onbreak_stmt ") " body
.BI MC_DOWHILE( tag ", " cond ") " body
.BI MC_DECL( tag ", " decl ") " body
.BI MC_LOOPELSE( tag ", " head ") " loop_body " \fR[\fBelse " else_body \fR]

.BI MC_TARGET( tag ", " stmt ") " body
.BI MC_GOTARGET( tag );
.BI MC_ALLOWELSE( tag ") " main_body " \fR[\fBelse " else_body \fR]
.BI MC_GOELSE( tag );

.BI MC_ACT( stmt )
.BI MC_LABEL( tag )
.BI MC_GOTO( tag )
.fi
.SH DESCRIPTION
The header file
.B <mLib/control.h>
defines a number of macros which are useful when defining new
control structures for C.  They are inspired by Simon Tatham's article
.IR "Metaprogramming custom control structures in C",
though these macros differ from Tatham's in a few respects.
.SS "Common features"
Each of these macros takes a
.I tag
argument.  A
.I tag
is lexically like an identifier, except that it may begin with a digit,
so, for example, plain integers are acceptable tags.  Each use of an
action macro by a user-level macro must have a distinct
.IR tag .
If you're writing a new prefix action macro written in terms of these
existing actions, your macro should receive a
.I tag
from its caller, and pass this tag, along with a distinctive component
of its own, down to any prefix actions that it calls; the
.IR tag s
from each layer should be separated by a pair of underscores.
.PP
Some of these macros work by wrapping a loop around the
.I body
statement.  This interferes with the way that `free'
.B break
and
.B continue
statements within the
.I body
behave: we say that these statements are
.I captured
by the macro.
A
.B break
or
.B continue
statement is `free' if it doesn't appear lexically within a loop or
(for
.B break)
.B switch
statement that is part of the
.IR body .
So
.IP
.B "if (!x) break;"
.PP
contains a free
.B break
statement, while
.IP
.nf
.ft B
for (i = 0; i < n; i++)
\h'4n'if (interestingp(i)) break;
.ft
.fi
.PP
does not.
.PP
Some of these macros take special care to give you control over what
happens when a captured
.B break
is executed.  Alas, proper handling of
.B continue
doesn't seem possible.  Free
.B break
and
.B continue
statements
.I within
arguments to these macros are never captured.
.SS "Prefix action macros"
.B MC_BEFORE
macro is the simplest to understand.  Executing
.IP
.BI MC_BEFORE( tag ", " stmt ") " body
.PP
has the same effect as executing
.I stmt
followed by
.IR body ,
except that the whole thing is syntactically a single statement, so, for
example, it doesn't need to be enclosed in braces to be the body of a
.B for
loop.
.B MC_BEFORE
does not capture free
.B break
or
.B continue
statements.
.PP
Executing
.IP
.BI MC_AFTER( tag ", " stmt ") " body
.PP
has
.I nearly
the same effect as executing
.I stmt
followed by
.IR body .
Again, the whole thing is syntactically a single statement.  However,
.B MC_AFTER
captures free
.B break
and
.B continue
statements within the
.IR body .
A free
.B break
or
.B continue
abruptly ends execution of the
.IR body ,
immediately transferring control to the
.IR stmt .
.PP
Executing
.IP
.BI MC_WRAP( tag ", " before ", " onend ", " onbreak ") " body
.PP
has
.I nearly
the same effect as executing
.IR before ,
.IR body ,
and then
.IR onend .
If the
.I body
executes a free
.B break
statement, then control abruptly continues with the
.I onbreak
statement, and
.I onend
is not executed.  Currently, if the
.I body
executes a free
.B continue
statement, then control abruptly continues with the
.I onend
statement, but this behaviour is a bug and may be fixed in the future.
.PP
.\" @@@ mc_finally
.PP
Executing
.IP
.BI MC_DOWHILE( tag ", " cond ") " body
.PP
has exactly the same effect as
.BI "do " body " while (" cond ); \fR,
the only difference being that the
.I body
appears in tail position rather than sandwiched in the middle.
.PP
Executing
.BI MC_DECL( tag ", " decl ") " body
has the same effect as
.BI "{ " decl "; " body " }" \fR,
except that free
.B break
and
.B continue
statements are captured.  Currently, a free
.B continue
statement will simply abruptly terminate execution of the
.IR body ,
while a free
.B break
statement abruptly
.I restarts
executing the
.I body
without leaving the scope of the
.IR decl ;
but these behaviours are bugs and may be fixed in the future.
.PP
The
.B MC_DECL
macro makes use of the fact that a
.B for
statement can introduce a declaration into its body's scope in C99 and
C++; the macro is not available in C89.
.PP
Executing
.IP
.nf
.BI MC_LOOPELSE( head ", " tag ") "
.RI \h'4n' loop_body
.RB [ else
.RI \h'4n' else_body ]
.fi
.PP
results in Python-like loop behaviour.  The
.I head
must be a valid loop head with one of the forms
.IP
.BI "while (" cond ")"
.br
.BI "for (" decl "; " cond "; " next_expr ")"
.br
.BI "MC_DOWHILE(" tag ", " cond ")"
.PP
The resulting loop executes the same as
.IP
.nf
.I head
.RI \h'4n' loop_body
.fi
.PP
If the loop ends abruptly, as a result of
.BR break ,
then control is passed to the statement following the loop in the usual
way.  However, if the loop completes naturally, and the optional
.B else
clause is present, then the
.I else_body
is executed.  A free
.B continue
statement within the
.I loop_body
behaves normally.  Free
.B break
and
.B continue
statements within the
.I else_body
are not captured.
.PP
.\" @@@ loopbetween
.SS "Lower-level machinery"
Executing
.IP
.BI MC_TARGET( tag ", " stmt ") " body
.PP
has exactly the same effect as simply executing
.IR body .
Executing
.B MC_GOTARGET
immediately transfers control to
.IR stmt ,
with control continuing with the following statement, skipping the
.IR body .
Free
.B break
or
.B continue
statements in
.I body
are not captured.
.PP
This is most commonly useful in loops in order to arrange the correct
behaviour of a free
.B break
within the loop body.  See the example below, which shows the definition
of
.BR MC_LOOPELSE .
.PP
Executing
.IP
.BI MC_ALLOWELSE( tag ") " main_body " \fR[\fBelse " else_body \fR]
.PP
has exactly the same effect as just
.IR main_body .
Executing
.IP
.BI MC_GOELSE( tag );
.PP
transfers control immediately to
.I else_body
(if present); control then naturally transfers to the following
statement as usual.  Free
.B break
or
.B continue
statements in either of
.I main_body
or
.I else_body
are not captured.
.PP
Note that
.B MC_ALLOWELSE
works by secretly inserting an
.B if
statement head before the
.IR main_body ,
so things will likely to wrong if
.I main_body
is itself an
.B if
statement: if
.I main_body
lacks an
.B else
clause, then an
.B else
intended to match
.B MC_ALLOWELSE
will be mis-associated; and even if
.I main_body
.I does
have an
.B else
clause, the resulting program text is likely to provoke a compiler
warning about `dangling
.BR else '.
.PP
Using these tools, it's relatively straightforward to define a macro
like
.BR MC_LOOPELSE ,
described above:
.IP
.nf
.ft B
#define MC_LOOPELSE(tag, head) \e
\h'4n'MC_TARGET(tag##__exit, { ; }) \e
\h'4n'MC_ALLOWELSE(tag##__else) \e
\h'4n'MC_AFTER(tag##__after, { MC_GOELSE(tag##__else); }) \e
\h'4n'head \e
\h'8n'MC_WRAP(tag##__body, { ; }, { ; }, \e
\h'8n+\w'MC_WRAP(tag##__body, ''{ MC_GOTARGET(tag##__exit); })
.ft R
.fi
.PP
The main `trick' for these control-flow macros is
.BR MC_ACT ,
which wraps up a statement as an
.IR action .
An action is a valid
.IR  "statement head" ,
like
.B if
or
.BR while :
i.e., it must be completed by following it with a
.I body
statement.  Executing
.IP
.BI MC_ACT( stmt ") " body
.PP
has the same effect as simply executing
.IR stmt ;
the
.I body
is usually ignored.  Note that
.B ;
is a valid statement which does nothing, so
.BI MC_ACT( stmt );
is also a valid statement with the same effect as
.IR stmt .
The only way to cause
.I body
to be executed is to attach a label to it and transfer control using
.BR goto .
.PP
Executing
.IP
.BI MC_LABEL( tag ") " body
.PP
has the same effect as
.IR body .
Executing
.IP
.BI MC_GOTO( tag )
.PP
immediately transfers control to the
.IR body .
Note that
.B MC_GOTO
is syntactically an action
(i.e., it's wrapped in
.BR MC_ACT ).
The
.IR tag s
here are scoped to the top-level source line, like all
.IR tag s
in this macro package.
.PP
All of the control-flow macros in this package are mainly constructed from
.BR MC_ACT ,
.BR MC_LABEL ,
and
.BR MC_GOTO ,
sometimes with one or two other statement heads thrown into the mix.
For example,
.B MC_AFTER
is defined as
.IP
.nf
.ft B
#define MC_AFTER(tag, stmt) \e
\h'28n'MC_GOTO(tag##__body) \e
\h'4n'MC_LABEL(tag##__end) \e
\h'28n'MC_ACT(stmt) \e
\h'28n'for (;;) \e
\h'32n'MC_GOTO(tag##__end) \e
\h'4n'MC_LABEL(tag##__body)
.ft R
.fi
.PP
(The unusual layout is conventional, to make the overall structure of
the code clear despite visual interference from the labels.)
The
.I body
appears at the end, labelled as
.IB tag __body \fR.
Control enters at the start, and is immediately transferred to the
.I body ;
but the
.I body
is enclosed in a
.B for
loop, so when the
.I body
completes, the loop restarts, transferring control to
.IB tag __end
and the
.IR stmt .
Since it is enclosed in
.BR MC_ACT ,
once
.I stmt
completes, control transfers to the following statement.
.SH BUGS
Some macros cause free
.B break
and/or
.B continue
statements to behave in unexpected ways.
.PP
The need for tagging is ugly, and the restriction on having two
user-facing control-flow macros on the same line is objectionable.  The
latter could be avoided by using nonstandard features such as GCC's
.B __COUNTER__
macro, but adopting that would do programmers a disservice by
introducing a hazard for those trying to port code to other compilers
which lack any such feature.
.SH "SEE ALSO"
.BR mLib (3),
.BR macros (3).
.PP
Simon Tatham,
.IR "Metaprogramming custom control structures in C",
.BR "https://www.chiark.greenend.org.uk/~sgtatham/mp/" .
.SH "AUTHOR"
Mark Wooding, <mdw@distorted.org.uk>