From: mdw <mdw>
Date: Tue, 27 Jul 1999 18:30:14 +0000 (+0000)
Subject: Improve documentation and layout for @CONF_BEGIN@ and friends.  Remove
X-Git-Tag: 1.1.0~5
X-Git-Url: https://git.distorted.org.uk/~mdw/fwd/commitdiff_plain/022008acb24995e5df9cfebec4b8428d14de91d8

Improve documentation and layout for @CONF_BEGIN@ and friends.  Remove
irritating warning about unused label by introducing a spurious `goto'.
---

diff --git a/conf.h b/conf.h
index 1704587..6183048 100644
--- a/conf.h
+++ b/conf.h
@@ -1,6 +1,6 @@
 /* -*-c-*-
  *
- * $Id: conf.h,v 1.2 1999/07/26 23:28:39 mdw Exp $
+ * $Id: conf.h,v 1.3 1999/07/27 18:30:14 mdw Exp $
  *
  * Configuration parsing
  *
@@ -29,6 +29,10 @@
 /*----- Revision history --------------------------------------------------* 
  *
  * $Log: conf.h,v $
+ * Revision 1.3  1999/07/27 18:30:14  mdw
+ * Improve documentation and layout for @CONF_BEGIN@ and friends.  Remove
+ * irritating warning about unused label by introducing a spurious `goto'.
+ *
  * Revision 1.2  1999/07/26 23:28:39  mdw
  * Major reconstruction work for new design.
  *
@@ -125,13 +129,21 @@ extern int conf_enum(scanner */*sc*/, const char */*list*/,
 
 extern int conf_prefix(scanner */*sc*/, const char */*p*/);
 
-/* --- @CONF_BEGIN@, @CONF_ACCEPT@, @CONF_END@ --- *
+/* --- @CONF_BEGIN@, @CONF_END@ --- *
  *
  * Arguments:	@sc@ = scanner to read from
  *		@prefix@ = prefix to scan for
  *		@desc@ = description of what we're parsing
  *
- * Use:		Bracket an options parsing routine.
+ * Use:		Bracket an options parsing routine.  The current token is
+ *		checked to see whether it matches the prefix.  If so, it is
+ *		removed and the following token examined.  If that's a `.'
+ *		then it's removed.  If it's a `{' then the enclosed
+ *		option-parsing code is executed in a loop until a matching
+ *		'}' is found.  If the options parser doesn't accept an
+ *		option, the behaviour is dependent on whether a prefix was
+ *		seen: if so, an error is reported; otherwse a zero return is
+ *		made.
  */
 
 #define CS_PLAIN 0
@@ -143,6 +155,9 @@ extern int conf_prefix(scanner */*sc*/, const char */*p*/);
   scanner *_conf_sc = (sc);						\
   const char *_conf_desc = (desc);					\
   int _conf_state = CS_PLAIN;						\
+									\
+  /* --- Read the initial prefix --- */					\
+									\
   if (_conf_sc->t == CTOK_WORD &&					\
       strcmp(_conf_sc->d.buf, (prefix)) == 0) {				\
     token(_conf_sc);							\
@@ -154,15 +169,22 @@ extern int conf_prefix(scanner */*sc*/, const char */*p*/);
       _conf_state = CS_BRACE;						\
     }									\
   }									\
+									\
+  /* --- Ensure the next token is a word --- */				\
+									\
   if (_conf_sc->t != CTOK_WORD)						\
     error(_conf_sc, "parse error, expected option keyword");		\
   do {
 
-#define CONF_ACCEPT goto _conf_accept
-#define CONF_REJECT goto _conf_reject
-#define CONF_QUAL (_conf_state != CS_PLAIN)
-
 #define CONF_END							\
+									\
+    /* --- Reject an option --- *					\
+     *									\
+     * We could get here as a result of an explicit @CONF_REJECT@ or	\
+     * because the option wasn't accepted.				\
+     */									\
+									\
+     goto _conf_reject;							\
   _conf_reject:								\
     if (_conf_state == CS_PLAIN)					\
       _conf_state = CS_UNKNOWN;						\
@@ -170,19 +192,54 @@ extern int conf_prefix(scanner */*sc*/, const char */*p*/);
       error(_conf_sc, "unknown %s option `%s'",				\
 	    _conf_desc, _conf_sc->d.buf);				\
     }									\
+									\
+    /* --- Accept an option --- *					\
+     *									\
+     * It's safe to drop through from above.  Either an error will have	\
+     * been reported, or the state is not @CS_BRACE@.			\
+     */									\
+									\
   _conf_accept:								\
     if (_conf_state == CS_BRACE && _conf_sc->t == ';')			\
       token(_conf_sc);							\
   } while (_conf_state == CS_BRACE && _conf_sc->t == CTOK_WORD);	\
+									\
+  /* --- Check for a closing brace --- */				\
+									\
   if (_conf_state == CS_BRACE) {					\
     if (_conf_sc->t == '}')						\
       token(_conf_sc);							\
     else								\
       error(_conf_sc, "parse error, expected `}'");			\
   }									\
+									\
+  /* --- Return an appropriate value --- */				\
+									\
   return (_conf_state != CS_UNKNOWN);					\
 } while (0)
 
+/* --- @CONF_ACCEPT@, @CONF_REJECT@ --- *
+ *
+ * Arguments:	---
+ *
+ * Use:		Within an options parser (between @CONF_BEGIN@ and
+ *		@CONF_END@), accept or reject an option.
+ */
+
+#define CONF_ACCEPT goto _conf_accept
+#define CONF_REJECT goto _conf_reject
+
+/* --- @CONF_QUAL@ --- *
+ *
+ * Arguments:	---
+ *
+ * Use:		Evaluates to a nonzero value if the current option is
+ *		qualified.  This can be used to decide whether abbreviations
+ *		for options should be accepted.
+ */
+
+#define CONF_QUAL (_conf_state != CS_PLAIN)
+
 /* --- @conf_name@ --- *
  *
  * Arguments:	@scanner *sc@ = pointer to scanner