/* -*-c-*-
*
- * $Id: conf.h,v 1.2 1999/07/26 23:28:39 mdw Exp $
+ * $Id: conf.h,v 1.8 2003/11/25 14:08:23 mdw Exp $
*
* Configuration parsing
*
/*----- Revision history --------------------------------------------------*
*
* $Log: conf.h,v $
+ * Revision 1.8 2003/11/25 14:08:23 mdw
+ * Debianization. Socket target options. Internet binding.
+ *
+ * Revision 1.7 2002/02/22 23:42:56 mdw
+ * `fw'-specific configuration code moved out. This file might become part
+ * of a library some day.
+ *
+ * Revision 1.6 2002/01/13 14:48:16 mdw
+ * Make delimiters be a property of a scanner. Change the delimiter-
+ * changing functions' names.
+ *
+ * Revision 1.5 1999/10/22 22:46:44 mdw
+ * Improve documentation for conf_enum.
+ *
+ * Revision 1.4 1999/08/19 18:32:48 mdw
+ * Improve lexical analysis. In particular, `chmod' patterns don't have to
+ * be quoted any more.
+ *
+ * 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.
*
/*----- Functions provided ------------------------------------------------*/
+/* --- @conf_undelim@ --- *
+ *
+ * Arguments: @scanner *sc@ = pointer to scanner definition
+ * @const char *d, *dd@ = pointer to characters to escape
+ *
+ * Returns: ---
+ *
+ * Use: Modifies the tokenizer. Characters in the first list will
+ * always be considered to begin a word. Characters in the
+ * second list will always be allowed to continue a word.
+ */
+
+extern void conf_undelim(scanner */*sc*/,
+ const char */*d*/, const char */*dd*/);
+
/* --- @token@ --- *
*
* Arguments: @scanner *sc@ = pointer to scanner definition
extern void error(scanner */*sc*/, const char */*msg*/, ...);
+/* --- @pushback@ --- *
+ *
+ * Arguments: @scanner *sc@ = pointer to scanner definition
+ *
+ * Returns: ---
+ *
+ * Use: Pushes the current token back. This is normally a precursor
+ * to pushing a new scanner source.
+ */
+
+extern void pushback(scanner */*sc*/);
+
/* --- @conf_enum@ --- *
*
* Arguments: @scanner *sc@ = pointer to a scanner object
* Returns: Index into list, zero-based, or @-1@.
*
* Use: Checks whether the current token is a string which matches
- * one of the comma-separated items given. If not, an error is
- * reported; otherwise the index of the matched item is
- * returned.
+ * one of the comma-separated items given. The return value is
+ * the index (zero-based) of the matched string in the list.
+ *
+ * The flags control the behaviour if no exact match is found.
+ * If @ENUM_ABBREV@ is set, and the current token is a left
+ * substring of exactly one of the possibilities, then that one
+ * is chosen. If @ENUM_NONE@ is set, the value @-1@ is
+ * returned; otherwise an error is reported and the program is
+ * terminated.
*/
#define ENUM_ABBREV 1u
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
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); \
_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; \
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
extern void conf_name(scanner */*sc*/, char /*delim*/, dstr */*d*/);
-/* --- @conf_parse@ --- *
- *
- * Arguments: @scanner *sc@ = pointer to a scanner structure
- *
- * Returns: ---
- *
- * Use: Parses a configuration file fragment from the scanner
- */
-
-extern void conf_parse(scanner *sc);
-
/*----- That's all, folks -------------------------------------------------*/
#ifdef __cplusplus