@@@ major overhaul, new primitives

[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

/*----- 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_PASS@
 *
 * @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
#define MC_PASS		MC_ACT(;)


/* @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); })

/* @BEFORE(tag, stmt_0) stmt_1@
 *
 * Execute @stmt_0@ and then @stmt_1@.
 */
#define BEFORE(tag, stmt)						\
			MC_ACT({ stmt MC_GOTO(tag##__body); })		\
  MC_LABEL(tag##__body)

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

/* @WRAP(tag, before, onend, onbreak) stmt@
 *
 * Execute the @before@ statement, followed by @stmt@.  If @stmt@ invokes
 * @break@, then @onbreak@ is immediately executed; if @stmt@ 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 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)

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

/* @DOWHILE(tag, cond) stmt@
 *
 * Repeatedly execute @stmt@ until @cond@ evaluates to zero.  Execute @stmt@
 * at least once.  The @break@ and @continue@ statements work within @stmt@
 * as one would expect.
 */
#define DOWHILE(tag, cond)						\
			MC_GOTO(tag##__body)				\
			while (cond)					\
  MC_LABEL(tag##__body)

/* @DECL(tag, decl) stmt@
 *
 * Execute @stmt@ with @decl@ in scope.  If @stmt@ completes or invokes
 * @break@ or @continue@ then control continues with the statement following
 * @DECL@.  Internally, this uses @for@, so it only works in C99 or later, or
 * C++.
 */
#if __STDC_VERSION__ >= 199901 || defined(__cplusplus)
#  define DECL(tag, decl)						\
			for (decl;;)					\
			  MC_GOTO(tag##__body)				\
  MC_LABEL(tag##__end)	  MC_ACT({ break; })				\
			  for (;;)					\
			    MC_GOTO(tag##__end)				\
  MC_LABEL(tag##__body)
#endif

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

#ifdef __cplusplus
  }
#endif

#endif