@@@ remote works?

[mLib] / utils / control.h

/* -*-c-*-
 *
 * Control operators, after Simon Tatham
 *
 * (c) 2022 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of the mLib utilities library.
 *
 * mLib is free software: you can redistribute it and/or modify it under
 * the terms of the GNU Library General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or (at
 * your option) any later version.
 *
 * mLib is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
 * License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with mLib.  If not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
 * USA.
 */

#ifndef MLIB_CONTROL_H
#define MLIB_CONTROL_H

#ifdef __cplusplus
  extern "C" {
#endif

/*----- Notes on the control operator machinery ---------------------------*
 *
 * These macros owe an obvious and immense debt to Simon Tatham's article
 * `Metaprogramming custom control structures in C', available from
 * https://www.chiark.greenend.org.uk/~sgtatham/mp/.  The basic tricks are
 * all Tatham's, as are most of the provided operators.  The focus on
 * @MC_ACT@ as a significant primitive is probably my main original
 * contribution.
 */

/*----- Header files ------------------------------------------------------*/

#ifndef MLIB_MACROS_H
#  include "macros.h"
#endif

/*----- Macros provided ---------------------------------------------------*/

/* @MCTRL__LABEL(tag)@ *
 *
 * Expand to a plausibly unique label based on the current line number and
 * the @tag@.
 */
#define MCTRL__LABEL(tag) GLUE(_mctrl__##tag##__, __LINE__)

/* @MC_ACT(stmt)@
 *
 * @MC_ACT@ is the main `trick' for constructing these flow-control
 * operators.  It wraps up a statement as what we call an `action'.  Actions
 * can be concatenated together to form a valid statement head, i.e., a
 * sequence of actions can be followed by a statement, called the `body', to
 * form a single syntactic statement.  The body can be simply `;', so an
 * action can be treated as a simple statement.  However, if an action
 * sequence is executed, only the first statement is executed.
 *
 * Actions can be labelled, e.g., using @MC_LABEL@, just like statements.  If
 * control is passed to a label, e.g., by @MC_GOTO@, then the statement
 * within the following action (only) is executed; the normal flow of control
 * will then be to the statement following the containing action sequence and
 * its body.
 */
#define MC_ACT(stmt)	if (1) { stmt; } else

/* @MC_LABEL(tag)@
 * @MC_GOTO(tag);@
 *
 * @MC_LABEL@ just establishes a label which can be invoked (only) from the
 * same top-level macro; and @MC_GOTO@ transfers control to it.
 *
 * The @MC_GOTO@ macro is special in that it can be used either as a plain
 * statement, followed by a semicolon in the usual way, or as a prefix
 * action in its own right, in place of @MC_ACT@.
 */
#define MC_LABEL(tag)	MCTRL__LABEL(tag):
#define MC_GOTO(tag)	MC_ACT(goto MCTRL__LABEL(tag))

/* @MC_TARGET(tag, stmt) body@
 * @MC_GOTARGET(tag);@
 *
 * Executing @TARGET@ statement executes the @body@, as if the @TARGET@
 * weren't there.  Executing a @GOTARGET@ transfers control to the @stmt@
 * (but not normally the @body@).  In either case, the normal flow of control
 * is then to the following statement.
 */
#define MC_TARGET(tag, stmt)						\
			MC_GOTO(tag##__body)				\
  MC_LABEL(tag##__tgt)	MC_ACT(stmt)					\
  MC_LABEL(tag##__body)
#define MC_GOTARGET(tag) do MC_GOTO(tag##__tgt); while (0)

/* @MC_BEFORE(tag, stmt) body@
 *
 * Execute @stmt@ and then @body@.
 */
#define MC_BEFORE(tag, stmt)						\
			MC_ACT(stmt; MC_GOTO(tag##__body))		\
  MC_LABEL(tag##__body)

/* @MC_AFTER(tag, stmt) body@
 *
 * Execute @body@ and then @stmt@.  If @body@ invokes @break@ then control
 * immediately transfers to the statement following @MC_AFTER@.  If @body
 * invokes @continue@, then control returns to @stmt@.
 */
#define MC_AFTER(tag, stmt)						\
			MC_GOTO(tag##__body)				\
  MC_LABEL(tag##__end)	MC_ACT(stmt)					\
			for (;;)					\
			  MC_GOTO(tag##__end)				\
  MC_LABEL(tag##__body)

/* @MC_DOWHILE(tag, cond) body@
 *
 * Repeatedly execute @body@ until @cond@ evaluates to zero.  The @body@ is
 * executed once before @cond@ is checked the first time.  The @break@ and
 * @continue@ statements work within @body@ as one would expect.
 */
#define MC_DOWHILE(tag, cond)						\
			MC_GOTO(tag##__body)				\
			while (cond)					\
  MC_LABEL(tag##__body)

/* @MC_ALLOWELSE(tag) apodosis_body [else haeresis_body]@
 * @MC_GOELSE(tag);@
 *
 * Executing @MC_ALLOWELSE@ executes @apodosis_body@, but not
 * @haeresis_body@.  If @MC_GOELSE(tag)@ is executed, then control continues
 * from @haeresis_body@.
 */
#define MC_ALLOWELSE(tag)						\
			MC_GOTO(tag##__body)				\
  MC_LABEL(tag##__else)	if (0)						\
  MC_LABEL(tag##__body)
#define MC_GOELSE(tag)	do MC_GOTO(tag##__else); while (0)

/* @MC_WRAP(tag, before, onend, onbreak) body@
 *
 * Execute the @before@ statement, followed by @body@.  If @body@ invokes
 * @break@, then @onbreak@ is immediately executed; if @body@ completes
 * normally, or invokes @continue@ then @onend@ is immediately executed.
 * Any @break@ and @continue@ in the @before@, @onend@, and @onbreak@
 * statements behave as one would expect from their context.
 */
#define MC_WRAP(tag, before, onend, onbreak)				\
			MC_ACT(before; MC_GOTO(tag##__body))		\
  MC_LABEL(tag##__end)	MC_ACT(onend)					\
  MC_LABEL(tag##__brk)	MC_ACT(onbreak)					\
			for (;;)					\
			  MC_GOTO(tag##__brk)				\
			  for (;;)					\
			    MC_GOTO(tag##__end)				\
  MC_LABEL(tag##__body)

/* @MC_FINALLY(tag, cleanup) body@
 *
 * Execute @cleanup@ when @body@ completes or ends with @break@.  In the
 * latter case, propagate the @break@ to the enclosing context -- for which
 * it must be syntactically appropriate.
 *
 * The @cleanup@ code is duplicated.  If it arrange to have private long-term
 * state, e.g, by declaring @static@ variables, then the two copies will not
 * share the same state, so probably don't do this.
 */
#define MC_FINALLY(tag, cleanup)					\
	MP_WRAP(tag##__final, { ; }, cleanup, { cleanup break; })

/* @MC_DECL(tag, decl) body@
 *
 * Execute @body@ with @decl@ in scope.  If @body@ completes or invokes
 * @continue@ then control continues with the statement following @MC_DECL@;
 * if it invokes @break@ then it will be restarted without leaving the scope
 * of @decl@.  Internally, this uses @for@, so it only works in C99 or later,
 * or C++.
 */
#if __STDC_VERSION__ >= 199901 || defined(__cplusplus)
#  define MC_DECL(tag, decl)						\
			for (decl;;)					\
			  MC_GOTO(tag##__body)				\
  MC_LABEL(tag##__exit)	  MC_ACT(break)					\
			  for (;;)					\
			    MC_GOTO(tag##__exit)			\
  MC_LABEL(tag##__body)
#endif

/* @MC_LOOPELSE(tag, head) loop_body [else else_body]@
 *
 * Python-like looping with optional @else@ clause.  @head loop_body@ must be
 * a syntactically valid @for@, @while@, or @MC_DOWHILE@ loop; if the loop
 * exits because of @break@ then control continues in the usual way;
 * otherwise, the @else_body@ (if any) is executed.
 */
#define MC_LOOPELSE(tag, head)						\
	MC_TARGET(tag##__exit, { ; })					\
	MC_ALLOWELSE(tag##__else)					\
	MC_AFTER(tag##__after, { MC_GOELSE(tag##__else); })		\
	head								\
	  MC_WRAP(tag##__body, { ; }, { ; }, { MC_GOTARGET(tag##__exit); })

/* @MC_LOOPBETWEEN(tag, setup, cond, step) loop_body [else else_body]@
 *
 * This is essentially a @for@ loop with a twist.  The @setup@, @cond@, and
 * @step@ arguments are the parts of the @for@ head clause; because of the
 * limitations of the C macro syntax, they're separated by commas rather than
 * semicolons.
 *
 * The twist is that, once the @loop_body@ has finished, the @step@
 * expression evaluated, and the @cond@ evaluated and determined to be
 * nonzero, the @else_body@ (if any) is executed before re-entering the
 * @loop_body@.  This makes it a useful place to insert any kind of
 * interstitial material, e.g., printing commas between list items.
 *
 * The @cond@ is textually duplicated.  You'll get some code bloat if the
 * condition is very complex.  If it somehow arranges to have private
 * long-term state (e.g., as a result of declaring static variables inside
 * GCC statement expressions), then the two copies will not share this state,
 * so probably don't do this.
 *
 * Note that by the time that the @else_body@ is executed, the decision has
 * already been made that another iteration will be performed, and, in
 * particular, the @step@ has occurred.  The @else_body@ is therefore looking
 * at the next item to be processed, not the item that has just finished
 * being processed.
 */
#define MC_LOOPBETWEEN(tag, setup, cond, step)				\
	for (setup;;)							\
	  if (!(cond)) break; else					\
	  MC_TARGET(tag##__exit, { break; })				\
	  for (;;)							\
	    MC_WRAP(tag##__tailwrap, { ; },				\
				     { ; },				\
				     { MC_GOTARGET(tag##__exit); })	\
	    MC_ALLOWELSE(tag##__tail)					\
	    MC_WRAP(tag##__bodywrap, { ; },				\
				     { if ((step), !(cond))		\
					 MC_GOTARGET(tag##__exit);	\
				       else				\
					 MC_GOELSE(tag##__tail); },	\
				     { MC_GOTARGET(tag##__exit); })

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif