2 .TH control 3 "23 April 2023" "Straylight/Edgeware" "mLib utilities library"
4 control \- control structure metaprogramming
22 .B "#include <mLib/control.h>"
24 .BI MC_BEFORE( tag ", " stmts ") " body
25 .BI MC_AFTER( tag ", " stmts ") " body
26 .BI MC_WRAP( tag ", " before_stmt ", " onend_stmt ", " onbreak_stmt ") " body
27 .BI MC_DOWHILE( tag ", " cond ") " body
28 .BI MC_DECL( tag ", " decl ") " body
29 .BI MC_LOOPELSE( tag ", " head ") " loop_body " \fR[\fBelse " else_body \fR]
31 .BI MC_TARGET( tag ", " stmt ") " body
32 .BI MC_GOTARGET( tag );
33 .BI MC_ALLOWELSE( tag ") " main_body " \fR[\fBelse " else_body \fR]
43 defines a number of macros which are useful when defining new
44 control structures for C. They are inspired by Simon Tatham's article
45 .IR "Metaprogramming custom control structures in C",
46 though these macros differ from Tatham's in a few respects.
48 Each of these macros takes a
52 is lexically like an identifier, except that it may begin with a digit,
53 so, for example, plain integers are acceptable tags. Each use of an
54 action macro by a user-level macro must have a distinct
56 If you're writing a new prefix action macro written in terms of these
57 existing actions, your macro should receive a
59 from its caller, and pass this tag, along with a distinctive component
60 of its own, down to any prefix actions that it calls; the
62 from each layer should be separated by a pair of underscores.
64 Some of these macros work by wrapping a loop around the
66 statement. This interferes with the way that `free'
72 behave: we say that these statements are
79 statement is `free' if it doesn't appear lexically within a loop or
83 statement that is part of the
95 for (i = 0; i < n; i++)
96 \h'4n'if (interestingp(i)) break;
102 Some of these macros take special care to give you control over what
103 happens when a captured
105 is executed. Alas, proper handling of
107 doesn't seem possible. Free
113 arguments to these macros are never captured.
114 .SS "Prefix action macros"
116 macro is the simplest to understand. Executing
118 .BI MC_BEFORE( tag ", " stmt ") " body
120 has the same effect as executing
124 except that the whole thing is syntactically a single statement, so, for
125 example, it doesn't need to be enclosed in braces to be the body of a
129 does not capture free
137 .BI MC_AFTER( tag ", " stmt ") " body
141 the same effect as executing
145 Again, the whole thing is syntactically a single statement. However,
151 statements within the
157 abruptly ends execution of the
159 immediately transferring control to the
164 .BI MC_WRAP( tag ", " before ", " onend ", " onbreak ") " body
168 the same effect as executing
177 statement, then control abruptly continues with the
181 is not executed. Currently, if the
185 statement, then control abruptly continues with the
187 statement, but this behaviour is a bug and may be fixed in the future.
193 .BI MC_DOWHILE( tag ", " cond ") " body
195 has exactly the same effect as
196 .BI "do " body " while (" cond ); \fR,
197 the only difference being that the
199 appears in tail position rather than sandwiched in the middle.
202 .BI MC_DECL( tag ", " decl ") " body
203 has the same effect as
204 .BI "{ " decl "; " body " }" \fR,
209 statements are captured. Currently, a free
211 statement will simply abruptly terminate execution of the
219 without leaving the scope of the
221 but these behaviours are bugs and may be fixed in the future.
225 macro makes use of the fact that a
227 statement can introduce a declaration into its body's scope in C99 and
228 C++; the macro is not available in C89.
233 .BI MC_LOOPELSE( head ", " tag ") "
236 .RI \h'4n' else_body ]
239 results in Python-like loop behaviour. The
241 must be a valid loop head with one of the forms
243 .BI "while (" cond ")"
245 .BI "for (" decl "; " cond "; " next_expr ")"
247 .BI "MC_DOWHILE(" tag ", " cond ")"
249 The resulting loop executes the same as
256 If the loop ends abruptly, as a result of
258 then control is passed to the statement following the loop in the usual
259 way. However, if the loop completes naturally, and the optional
261 clause is present, then the
267 behaves normally. Free
271 statements within the
276 .SS "Lower-level machinery"
279 .BI MC_TARGET( tag ", " stmt ") " body
281 has exactly the same effect as simply executing
285 immediately transfers control to
287 with control continuing with the following statement, skipping the
297 This is most commonly useful in loops in order to arrange the correct
300 within the loop body. See the example below, which shows the definition
306 .BI MC_ALLOWELSE( tag ") " main_body " \fR[\fBelse " else_body \fR]
308 has exactly the same effect as just
312 .BI MC_GOELSE( tag );
314 transfers control immediately to
316 (if present); control then naturally transfers to the following
317 statement as usual. Free
321 statements in either of
329 works by secretly inserting an
331 statement head before the
333 so things will likely to wrong if
345 will be mis-associated; and even if
350 clause, the resulting program text is likely to provoke a compiler
351 warning about `dangling
354 Using these tools, it's relatively straightforward to define a macro
361 #define MC_LOOPELSE(tag, head) \e
362 \h'4n'MC_TARGET(tag##__exit, { ; }) \e
363 \h'4n'MC_ALLOWELSE(tag##__else) \e
364 \h'4n'MC_AFTER(tag##__after, { MC_GOELSE(tag##__else); }) \e
366 \h'8n'MC_WRAP(tag##__body, { ; }, { ; }, \e
367 \h'8n+\w'MC_WRAP(tag##__body, ''{ MC_GOTARGET(tag##__exit); })
371 The main `trick' for these control-flow macros is
373 which wraps up a statement as an
376 .IR "statement head" ,
381 i.e., it must be completed by following it with a
385 .BI MC_ACT( stmt ") " body
387 has the same effect as simply executing
391 is usually ignored. Note that
393 is a valid statement which does nothing, so
395 is also a valid statement with the same effect as
397 The only way to cause
399 to be executed is to attach a label to it and transfer control using
404 .BI MC_LABEL( tag ") " body
406 has the same effect as
412 immediately transfers control to the
416 is syntactically an action
417 (i.e., it's wrapped in
421 here are scoped to the top-level source line, like all
423 in this macro package.
425 All of the control-flow macros in this package are mainly constructed from
430 sometimes with one or two other statement heads thrown into the mix.
437 #define MC_AFTER(tag, stmt) \e
438 \h'28n'MC_GOTO(tag##__body) \e
439 \h'4n'MC_LABEL(tag##__end) \e
440 \h'28n'MC_ACT(stmt) \e
442 \h'32n'MC_GOTO(tag##__end) \e
443 \h'4n'MC_LABEL(tag##__body)
447 (The unusual layout is conventional, to make the overall structure of
448 the code clear despite visual interference from the labels.)
451 appears at the end, labelled as
453 Control enters at the start, and is immediately transferred to the
461 completes, the loop restarts, transferring control to
465 Since it is enclosed in
469 completes, control transfers to the following statement.
471 Some macros cause free
475 statements to behave in unexpected ways.
477 The need for tagging is ugly, and the restriction on having two
478 user-facing control-flow macros on the same line is objectionable. The
479 latter could be avoided by using nonstandard features such as GCC's
481 macro, but adopting that would do programmers a disservice by
482 introducing a hazard for those trying to port code to other compilers
483 which lack any such feature.
489 .IR "Metaprogramming custom control structures in C",
490 .BR "https://www.chiark.greenend.org.uk/~sgtatham/mp/" .
492 Mark Wooding, <mdw@distorted.org.uk>