Fix issue libconfuse#24: Add support for CFGF_DEPRECATED and CFGF_DRO…

…P option flags

- `CFGF_DEPRECATED` causes a deprecated warning message for an option
- `CFGF_DEPRECATED | CFGF_DROP` causes a deprecated option to be dropped

Note: `CFGF_DROP` must currently be used with `CFG_DEPRECATED` to have
      an effect on the option.

Signed-off-by: Sebastian Geiger <sbastig@gmx.net>
Signed-off-by: Joachim Nilsson <troglobit@gmail.com>

examples/Makefile.am

@@ -1,5 +1,5 @@
-EXTRA_DIST      = simple.conf reread.conf ftp.conf test.conf nested.conf
-noinst_PROGRAMS = simple reread ftpconf cfgtest cli nested
+EXTRA_DIST      = simple.conf reread.conf ftp.conf test.conf nested.conf deprecated.conf
+noinst_PROGRAMS = simple reread ftpconf cfgtest cli nested deprecated
 AM_CPPFLAGS     = -I$(top_srcdir)/src
 AM_LDFLAGS      = -L../src/
 LIBS            = $(LTLIBINTL)

examples/deprecated.c

@@ -0,0 +1,40 @@
+/* Example of how to deprecate and drop options by Sebastian Geiger */
+#include "confuse.h"
+#include <string.h>
+
+int main(void)
+{
+	int i, repeat;
+	cfg_opt_t opts[] = {
+		CFG_STR_LIST("targets", "{World}", CFGF_DEPRECATED),
+		CFG_INT("repeat", 1, CFGF_DEPRECATED),
+		CFG_INT("foobar", 1, CFGF_DEPRECATED | CFGF_DROP),
+		CFG_END()
+	};
+	cfg_t *cfg;
+
+	cfg = cfg_init(opts, CFGF_NONE);
+	if (cfg_parse(cfg, "deprecated.conf") == CFG_PARSE_ERROR)
+		return 1;
+
+	repeat = cfg_getint(cfg, "repeat");
+	while (repeat--) {
+		printf("Hello");
+		for (i = 0; i < cfg_size(cfg, "targets"); i++)
+			printf(", %s", cfg_getnstr(cfg, "targets", i));
+		printf("!\n");
+	}
+
+	cfg_print_indent(cfg, stdout, 4);
+	cfg_free(cfg);
+
+	return 0;
+}
+
+/**
+ * Local Variables:
+ *  version-control: t
+ *  indent-tabs-mode: t
+ *  c-file-style: "linux"
+ * End:
+ */

examples/deprecated.conf

@@ -0,0 +1,4 @@
+# Example of how to deprecate and drop options by Sebastian Geiger
+targets = {"Fish", "Cat"}
+repeat = 1
+foobar = 1

src/confuse.c

@@ -991,6 +991,16 @@ static int call_function(cfg_t *cfg, cfg_opt_t *opt, cfg_opt_t *funcopt)
 	return ret;
 }
 
+static void cfg_handle_deprecated(cfg_t *cfg, cfg_opt_t *opt)
+{
+	if (opt->flags & CFGF_DROP) {
+		cfg_error(cfg, _("dropping deprecated configuration option '%s'"), opt->name);
+		cfg_free_value(opt);
+	} else {
+		cfg_error(cfg, _("found deprecated option '%s', please update configuration file."), opt->name);
+	}
+}
+
 static int cfg_parse_internal(cfg_t *cfg, int level, int force_state, cfg_opt_t *force_opt)
 {
 	int state = 0;
@@ -1019,11 +1029,18 @@ static int cfg_parse_internal(cfg_t *cfg, int level, int force_state, cfg_opt_t
 				cfg_error(cfg, _("premature end of file"));
 				return STATE_ERROR;
 			}
+
+			if (opt && opt->flags & CFGF_DEPRECATED)
+				cfg_handle_deprecated(cfg, opt);
+
 			return STATE_EOF;
 		}
 
 		switch (state) {
 		case 0:	/* expecting an option name */
+			if (opt && opt->flags & CFGF_DEPRECATED)
+				cfg_handle_deprecated(cfg, opt);
+
 			if (tok == '}') {
 				if (level == 0) {
 					cfg_error(cfg, _("unexpected closing brace"));

src/confuse.h

@@ -91,6 +91,8 @@ typedef enum cfg_type_t cfg_type_t;
 #define CFGF_RESET 64
 #define CFGF_DEFINIT 128
 #define CFGF_IGNORE_UNKNOWN 256 /**< ignore unknown options in configuration files */
+#define CFGF_DEPRECATED     512  /**< option is deprecated and should be ignored. */
+#define CFGF_DROP           1024 /**< option should be dropped after parsing */
 
 /** Return codes from cfg_parse(), cfg_parse_boolean(), and cfg_set*() functions. */
 #define CFG_SUCCESS     0