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 (file)
--- 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