allow for accumulators

An "accumulator" allows a user to specify the same argument multiple
times to increase its value.  For example, you may want to turn on
verbose mode with "-v", and very verbose mode with "-vv", and insanely
verbose mode with "-vvv", etc.

Author: ethomson

README.md

@@ -15,9 +15,14 @@ Types of options
 ----------------
 
 * Boolean values are options that do not take a value, and are
-  either set or unset, for example `-v` or `--verbose`.  Booleans
-  are shorthand for switches that are assigned a value of `1` when
-  present.
+  either set or unset, for example `-v` or `--verbose`.  If a
+  boolean has a long name (eg `--verbose`) then it implicitly has
+  a negation prefixed by `no-` (in this case, `--no-verbose`).
+  The given value will be set to `1` when the boolean is given on
+  the command line and `0` when its negation is given.
+* Accumulators are options that can be provided multiple times to
+  increase its value.  For example, `-v` will set verbosity to `1`,
+  but `-vvv` will set verbosity to `3`.
 * Switches are options that do not take a value on the command
   line, for example `--long` or `--short`.  When a switch is present
   on the command line, a variable will be set to a predetermined value.
@@ -41,15 +46,21 @@ Options should be specified as an array of `adopt_spec` elements,
 elements, terminated with an `adopt_spec` initialized to zeroes.
 
 ```c
+int debug = 0;
 int verbose = 0;
 int volume = 1;
 char *channel = "default";
 char *filename1 = NULL;
 char *filename2 = NULL;
 
 adopt_spec opt_specs[] = {
-    /* `verbose`, above, will be set to `1` when specified. */
-    { ADOPT_BOOL, "verbose", 'v', &verbose },
+    /* `verbose`, above, will increment each time `-v` is specified. */
+    { ADOPT_ACCUMULATOR, "verbose", 'v', &verbose },
+
+    /* `debug`, above, will be set to `1` when `--debug` is specified,
+     * or to `0` if `--no-debug` is specified.
+     */
+    { ADOPT_BOOL, "debug", 'd', &debug },
 
     /* `volume` will be set to `0` when `--quiet` is specified, and
      * set to `2` when `--loud` is specified.  if neither is specified,

adopt.c

@@ -180,6 +180,10 @@ static adopt_status_t parse_long(adopt_opt *opt, adopt_parser *parser)
 	else if (spec->type == ADOPT_TYPE_BOOL && spec->value)
 		*((int *)spec->value) = !is_negated;
 
+	/* --accumulate */
+	else if (spec->type == ADOPT_TYPE_ACCUMULATOR && spec->value)
+		*((int *)spec->value) += spec->switch_value ? spec->switch_value : 1;
+
 	/* --switch */
 	else if (spec->type == ADOPT_TYPE_SWITCH && spec->value)
 		*((int *)spec->value) = spec->switch_value;
@@ -228,6 +232,9 @@ static adopt_status_t parse_short(adopt_opt *opt, adopt_parser *parser)
 	if (spec->type == ADOPT_TYPE_BOOL && spec->value)
 		*((int *)spec->value) = 1;
 
+	else if (spec->type == ADOPT_TYPE_ACCUMULATOR && spec->value)
+		*((int *)spec->value) += spec->switch_value ? spec->switch_value : 1;
+
 	if (spec->type == ADOPT_TYPE_SWITCH && spec->value)
 		*((int *)spec->value) = spec->switch_value;
 

adopt.h

@@ -29,12 +29,27 @@ typedef enum {
 	ADOPT_TYPE_BOOL,
 
 	/**
-	 * An option that, when specified, sets the given `value_ptr`
-	 * to the given `value`.
+	 * An option that, when specified, sets the given `value` pointer
+	 * to the specified `switch_value`.  This is useful for booleans
+	 * where you do not want the implicit negation that comes with an
+	 * `ADOPT_TYPE_BOOL`, or for switches that multiplex a value, like
+	 * setting a mode.  For example, `--read` may set the `value` to
+	 * `MODE_READ` and `--write` may set the `value` to `MODE_WRITE`.
 	 */
 	ADOPT_TYPE_SWITCH,
 
-	/** An option that has a value ("-nvalue" or "--name value") */
+	/**
+	 * An option that, when specified, increments the given
+	 * `value` by the given `switch_value`.  This can be specified
+	 * multiple times to continue to increment the `value`.
+	 * (For example, "-vvv" to set verbosity to 3.)
+	 */
+	ADOPT_TYPE_ACCUMULATOR,
+
+	/**
+	 * An option that takes a value, for example `-n value`,
+	 * `-nvalue`, `--name value` or `--name=value`.
+	 */
 	ADOPT_TYPE_VALUE,
 
 	/**
@@ -46,10 +61,21 @@ typedef enum {
 	 */
 	ADOPT_TYPE_LITERAL,
 
-	/** A single bare argument ("path") */
+	/**
+	 * A single argument, not an option.  When options are exhausted,
+	 * arguments will be matches in the order that they're specified
+	 * in the spec list.  For example, if two `ADOPT_TYPE_ARGS` are
+	 * specified, `input_file` and `output_file`, then the first bare
+	 * argument on the command line will be `input_file` and the
+	 * second will be `output_file`.
+	 */
 	ADOPT_TYPE_ARG,
 
-	/** Unmatched arguments, a collection of bare arguments ("paths...") */
+	/**
+	 * A collection of arguments.  This is useful when you want to take
+	 * a list of arguments, for example, multiple paths.  When specified,
+	 * the value will be set to the first argument in the list.
+	 */
 	ADOPT_TYPE_ARGS,
 } adopt_type_t;
 
@@ -123,8 +149,13 @@ typedef struct adopt_spec {
 	 * to an `int` that will be set to `1` if the option is specified.
 	 *
 	 * If this spec is of type `ADOPT_TYPE_SWITCH`, this is a pointer
-	 * to an `int` that will be set to the opt's `value` (below) when
-	 * this option is specified.
+	 * to an `int` that will be set to the opt's `switch_value` (below)
+	 * when this option is specified.
+	 *
+	 * If this spec is of type `ADOPT_TYPE_ACCUMULATOR`, this is a
+	 * pointer to an `int` that will be incremented by the opt's
+	 * `switch_value` (below).  If no `switch_value` is provided then
+	 * the value will be incremented by 1.
 	 *
 	 * If this spec is of type `ADOPT_TYPE_VALUE`,
 	 * `ADOPT_TYPE_VALUE_OPTIONAL`, or `ADOPT_TYPE_ARG`, this is
@@ -139,8 +170,10 @@ typedef struct adopt_spec {
 
 	/**
 	 * If this spec is of type `ADOPT_TYPE_SWITCH`, this is the value
-	 * to set in the option's `value_ptr` pointer when it is specified.
-	 * This is ignored for other opt types.
+	 * to set in the option's `value` pointer when it is specified.  If
+	 * this spec is of type `ADOPT_TYPE_ACCUMULATOR`, this is the value
+	 * to increment in the option's `value` pointer when it is
+	 * specified.  This is ignored for other opt types.
 	 */
 	int switch_value;
 

tests/adopt.c

@@ -701,6 +701,82 @@ void test_adopt__parse_arg_mixed_with_switches(void)
 	cl_assert_equal_p(NULL, result.value);
 }
 
+void test_adopt__accumulator(void)
+{
+	int foo = 0;
+	adopt_opt result;
+	char *argz;
+
+	char *args_zero[] = { "foo", "bar", "baz" };
+	char *args_one[] =  { "-f", "foo", "bar", "baz" };
+	char *args_two[] =  { "-f", "-f", "foo", "bar", "baz" };
+	char *args_four[] = { "-f", "-f", "-f", "-f", "foo", "bar", "baz" };
+
+	adopt_spec specs[] = {
+		{ ADOPT_TYPE_ACCUMULATOR, "foo", 'f', &foo,  0 },
+		{ ADOPT_TYPE_ARGS,        "argz", 0,  &argz, 0 },
+		{ 0 },
+	};
+
+	foo = 0;
+	cl_must_pass(adopt_parse(&result, specs, args_zero, 3, ADOPT_PARSE_DEFAULT));
+	cl_assert_equal_i(ADOPT_STATUS_DONE, result.status);
+	cl_assert_equal_i(0, foo);
+
+	foo = 0;
+	cl_must_pass(adopt_parse(&result, specs, args_one, 4, ADOPT_PARSE_DEFAULT));
+	cl_assert_equal_i(ADOPT_STATUS_DONE, result.status);
+	cl_assert_equal_i(1, foo);
+
+	foo = 0;
+	cl_must_pass(adopt_parse(&result, specs, args_two, 5, ADOPT_PARSE_DEFAULT));
+	cl_assert_equal_i(ADOPT_STATUS_DONE, result.status);
+	cl_assert_equal_i(2, foo);
+
+	foo = 0;
+	cl_must_pass(adopt_parse(&result, specs, args_four, 7, ADOPT_PARSE_DEFAULT));
+	cl_assert_equal_i(ADOPT_STATUS_DONE, result.status);
+	cl_assert_equal_i(4, foo);
+}
+
+void test_adopt__accumulator_with_custom_incrementor(void)
+{
+	int foo = 0;
+	adopt_opt result;
+	char *argz;
+
+	char *args_zero[] = { "foo", "bar", "baz" };
+	char *args_one[] =  { "-f", "foo", "bar", "baz" };
+	char *args_two[] =  { "-f", "-f", "foo", "bar", "baz" };
+	char *args_four[] = { "-f", "-f", "-f", "-f", "foo", "bar", "baz" };
+
+	adopt_spec specs[] = {
+		{ ADOPT_TYPE_ACCUMULATOR, "foo", 'f', &foo,  42 },
+		{ ADOPT_TYPE_ARGS,        "argz", 0,  &argz, 0  },
+		{ 0 },
+	};
+
+	foo = 0;
+	cl_must_pass(adopt_parse(&result, specs, args_zero, 3, ADOPT_PARSE_DEFAULT));
+	cl_assert_equal_i(ADOPT_STATUS_DONE, result.status);
+	cl_assert_equal_i(0, foo);
+
+	foo = 0;
+	cl_must_pass(adopt_parse(&result, specs, args_one, 4, ADOPT_PARSE_DEFAULT));
+	cl_assert_equal_i(ADOPT_STATUS_DONE, result.status);
+	cl_assert_equal_i(42, foo);
+
+	foo = 0;
+	cl_must_pass(adopt_parse(&result, specs, args_two, 5, ADOPT_PARSE_DEFAULT));
+	cl_assert_equal_i(ADOPT_STATUS_DONE, result.status);
+	cl_assert_equal_i(84, foo);
+
+	foo = 0;
+	cl_must_pass(adopt_parse(&result, specs, args_four, 7, ADOPT_PARSE_DEFAULT));
+	cl_assert_equal_i(ADOPT_STATUS_DONE, result.status);
+	cl_assert_equal_i(168, foo);
+}
+
 void test_adopt__parse_arg_with_literal(void)
 {
 	int foo = 0;