usage: move ahead of help in the struct

Since the usage information is now used for parsing and not only
displaying to end-users, it's less optional.  Move it ahead of the help
information in the struct.

Author: ethomson

adopt.h

@@ -48,8 +48,8 @@ typedef enum {
 } adopt_type_t;
 
 /**
- * Usage information for an argument, to be displayed to the end-user.
- * This is only for display, the parser ignores this usage information.
+ * Additional information about an option, including parsing
+ * restrictions and usage information to be displayed to the end-user.
  */
 typedef enum {
 	/** This argument is required. */
@@ -77,47 +77,50 @@ typedef struct adopt_spec {
 	const char alias;
 
 	/**
-	 * If this spec is of type `ADOPT_BOOL`, this is a pointer to
-	 * an `int` that will be set to `1` if the option is specified.
+	 * If this spec is of type `ADOPT_TYPE_BOOL`, this is a pointer
+	 * to an `int` that will be set to `1` if the option is specified.
 	 *
-	 * If this spec is of type `ADOPT_SWITCH`, this is a pointer to
-	 * an `int` that will be set to the opt's `value` (below) when
+	 * 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.
 	 *
-	 * If this spec is of type `ADOPT_VALUE` or `ADOPT_VALUE_OPTIONAL`,
-	 * this is a pointer to a `char *`, that will be set to the value
+	 * If this spec is of type `ADOPT_TYPE_VALUE`,
+	 * `ADOPT_TYPE_VALUE_OPTIONAL`, or `ADOPT_TYPE_ARG`, this is
+	 * a pointer to a `char *` that will be set to the value
 	 * specified on the command line.
 	 *
-	 * If this spec is of type `ADOPT_VALUES`, this is a pointer to a
-	 * `char **` that will be set to the remaining values specified on
-	 * the command line.
+	 * If this spec is of type `ADOPT_TYPE_ARGS`, this is a pointer
+	 * to a `char **` that will be set to the remaining values
+	 * specified on the command line.
 	 */
 	void *value;
 
 	/**
-	 * If this spec is of type `ADOPT_SWITCH`, this is the value to
-	 * set in the option's `value_ptr` pointer when it is specified.
+	 * 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.
 	 */
 	int switch_value;
 
 	/**
 	 * The name of the value, provided when creating usage information.
 	 * This is required only for the functions that display usage
-	 * information and only when a spec is of type `ADOPT_VALUE`.
+	 * information and only when a spec is of type `ADOPT_TYPE_VALUE,
+	 * `ADOPT_TYPE_ARG` or `ADOPT_TYPE_ARGS``.
 	 */
 	const char *value_name;
 
 	/**
-	 * Short description of the option, used when creating usage
-	 * information.  This is only used when creating usage information.
+	 * Optional usage flags that change parsing behavior and how
+	 * usage information is shown to the end-user.
 	 */
-	const char *help;
+	uint32_t usage;
 
 	/**
-	 * Optional `adopt_usage_t`, used when creating usage information.
+	 * Optional short description of the option to display to the
+	 * end-user.  This is only used when creating usage information.
 	 */
-	adopt_usage_t usage;
+	const char *help;
 } adopt_spec;
 
 /** Return value for `adopt_parser_next`. */

examples/loop.c

@@ -19,20 +19,20 @@ static char **other = NULL;
 
 adopt_spec opt_specs[] = {
 	{ ADOPT_TYPE_BOOL, "verbose", 'v', &verbose, 0,
-	  NULL, "Turn on verbose information", 0 },
+	  NULL, 0, "Turn on verbose information" },
 	{ ADOPT_TYPE_SWITCH, "quiet", 'q', &volume, 0,
-	  NULL, "Emit no output", ADOPT_USAGE_REQUIRED },
+	  NULL, ADOPT_USAGE_REQUIRED, "Emit no output" },
 	{ ADOPT_TYPE_SWITCH, "loud", 'l', &volume, 2,
-	  NULL, "Emit louder than usual output", ADOPT_USAGE_CHOICE },
+	  NULL, ADOPT_USAGE_CHOICE, "Emit louder than usual output" },
 	{ ADOPT_TYPE_VALUE, "channel", 'c', &channel, 0,
-	  "channel", "Set the channel", 0 },
+	  "channel", 0, "Set the channel" },
 	{ ADOPT_TYPE_LITERAL },
 	{ ADOPT_TYPE_ARG, NULL, 0, &filename1, 0,
-	  "file1", "The first filename", ADOPT_USAGE_REQUIRED },
+	  "file1", ADOPT_USAGE_REQUIRED, "The first filename" },
 	{ ADOPT_TYPE_ARG, NULL, 0, &filename2, 0,
-	  "file2", "The second (optional) filename", 0 },
+	  "file2", 0, "The second (optional) filename" },
 	{ ADOPT_TYPE_ARGS, NULL, 0, &other, 0,
-	  "other", "The other (optional) arguments", 0 },
+	  "other", 0, "The other (optional) arguments" },
 	{ 0 }
 };
 

examples/parse.c

@@ -19,20 +19,20 @@ static char **other = NULL;
 
 adopt_spec opt_specs[] = {
 	{ ADOPT_TYPE_BOOL, "verbose", 'v', &verbose, 0,
-	  NULL, "Turn on verbose information", 0 },
+	  NULL, 0, "Turn on verbose information" },
 	{ ADOPT_TYPE_SWITCH, "quiet", 'q', &volume, 0,
-	  NULL, "Emit no output", ADOPT_USAGE_REQUIRED },
+	  NULL, ADOPT_USAGE_REQUIRED, "Emit no output" },
 	{ ADOPT_TYPE_SWITCH, "loud", 'l', &volume, 2,
-	  NULL, "Emit louder than usual output", ADOPT_USAGE_CHOICE },
+	  NULL, ADOPT_USAGE_CHOICE, "Emit louder than usual output" },
 	{ ADOPT_TYPE_VALUE, "channel", 'c', &channel, 0,
-	  "channel", "Set the channel", 0 },
+	  "channel", 0, "Set the channel" },
 	{ ADOPT_TYPE_LITERAL },
 	{ ADOPT_TYPE_ARG, NULL, 0, &filename1, 0,
-	  "file1", "The first filename", ADOPT_USAGE_REQUIRED },
+	  "file1", ADOPT_USAGE_REQUIRED, "The first filename" },
 	{ ADOPT_TYPE_ARG, NULL, 0, &filename2, 0,
-	  "file2", "The second (optional) filename", 0 },
+	  "file2", 0, "The second (optional) filename" },
 	{ ADOPT_TYPE_ARGS, NULL, 0, &other, 0,
-	  "other", "The other (optional) arguments", 0 },
+	  "other", 0, "The other (optional) arguments" },
 	{ 0 }
 };
 

tests/adopt.c

@@ -782,9 +782,9 @@ void test_adopt__required_choice_missing(void)
 	adopt_opt result;
 
 	adopt_spec specs[] = {
-		{ ADOPT_TYPE_SWITCH, "foo", 'f', &foo,  'f', NULL, NULL, ADOPT_USAGE_REQUIRED },
-		{ ADOPT_TYPE_VALUE,  "bar",  0,  &bar,  'b', NULL, NULL, ADOPT_USAGE_CHOICE },
-		{ ADOPT_TYPE_ARGS,   "argz", 0,  &argz,  0,  NULL, NULL, 0 },
+		{ ADOPT_TYPE_SWITCH, "foo", 'f', &foo,  'f', NULL, ADOPT_USAGE_REQUIRED },
+		{ ADOPT_TYPE_VALUE,  "bar",  0,  &bar,  'b', NULL, ADOPT_USAGE_CHOICE },
+		{ ADOPT_TYPE_ARGS,   "argz", 0,  &argz,  0,  NULL, 0 },
 		{ 0 },
 	};
 
@@ -807,10 +807,10 @@ void test_adopt__required_choice_specified(void)
 	adopt_opt result;
 
 	adopt_spec specs[] = {
-		{ ADOPT_TYPE_SWITCH, "foo", 'f', &foo,  'f', NULL, NULL, ADOPT_USAGE_REQUIRED },
-		{ ADOPT_TYPE_VALUE,  "bar",  0,  &bar,  'b', NULL, NULL, ADOPT_USAGE_CHOICE },
-		{ ADOPT_TYPE_ARG,    "baz",  0,  &baz,  'z', NULL, NULL, ADOPT_USAGE_REQUIRED },
-		{ ADOPT_TYPE_ARGS,   "argz", 0,  &argz,  0,  NULL, NULL, 0 },
+		{ ADOPT_TYPE_SWITCH, "foo", 'f', &foo,  'f', NULL, ADOPT_USAGE_REQUIRED },
+		{ ADOPT_TYPE_VALUE,  "bar",  0,  &bar,  'b', NULL, ADOPT_USAGE_CHOICE },
+		{ ADOPT_TYPE_ARG,    "baz",  0,  &baz,  'z', NULL, ADOPT_USAGE_REQUIRED },
+		{ ADOPT_TYPE_ARGS,   "argz", 0,  &argz,  0,  NULL, 0 },
 		{ 0 },
 	};
 
@@ -833,11 +833,11 @@ void test_adopt__choice_switch_or_arg_advances_arg(void)
 	adopt_opt result;
 
 	adopt_spec specs[] = {
-		{ ADOPT_TYPE_SWITCH, "foo",  'f', &foo,  'f', NULL, NULL },
-		{ ADOPT_TYPE_SWITCH, "fooz", 'z', &foo,  'z', NULL, NULL, ADOPT_USAGE_CHOICE },
-		{ ADOPT_TYPE_VALUE,  "bar",   0,  &bar,  'b', NULL, NULL, ADOPT_USAGE_CHOICE },
-		{ ADOPT_TYPE_ARG,    "baz",   0,  &baz,   0,  NULL, NULL, ADOPT_USAGE_CHOICE },
-		{ ADOPT_TYPE_ARG,    "final", 0, &final, 0,  NULL, NULL, 0 },
+		{ ADOPT_TYPE_SWITCH, "foo",  'f', &foo,  'f', NULL, 0 },
+		{ ADOPT_TYPE_SWITCH, "fooz", 'z', &foo,  'z', NULL, ADOPT_USAGE_CHOICE },
+		{ ADOPT_TYPE_VALUE,  "bar",   0,  &bar,  'b', NULL, ADOPT_USAGE_CHOICE },
+		{ ADOPT_TYPE_ARG,    "baz",   0,  &baz,   0,  NULL, ADOPT_USAGE_CHOICE },
+		{ ADOPT_TYPE_ARG,    "final", 0,  &final, 0,  NULL, 0 },
 		{ 0 },
 	};