update documentation for new functionality

added SIMPLE_OPT_CHAR, SIMPLE_OPT_DOUBLE, and SIMPLE_OPT_STRING_SET
types

1 files changed, 63 insertions, 18 deletions

diff --git a/doc/interface.md b/doc/interface.md
index 5408332..86937f8 100644
--- a/doc/interface.md
+++ b/doc/interface.md
@@ -21,16 +21,29 @@ fields which should be defined in these elements are:
 
 	/* optional, a custom string describing the arg, used for usage printing */
 	const char *custom_arg_string;
+
+	/* required for type SIMPLE_OPT_STRING_SET, a NULL-terminated array of
+	 * string possibilities against which an option's argument is matched */
+	const char **string_set;
 ```
 
 if `type` is `SIMPLE_OPT_FLAG`, this option may not accept arguments. if `type`
 is `SIMPLE_OPT_END`, parsing and usage printing will return at this point when
 iterating through the array and will not see any elements which may follow.
+thus, in practice, the array definition should look something like this:
+
+```
+struct simple_opt options[] = {
+	{ SIMPLE_OPT_<type>, <short_name>, <long_name>, <true|false> ...},
+	{ SIMPLE_OPT_<type>, <short_name>, <long_name>, <true|false> ...},
+	...
+	{ SIMPLE_OPT_END }
+};
+```
 
-`short_name` is optional, and may be undefined for this option by passing '\0'.
-`long_name` is also optional, and may be left undefined for this option by
-passing `NULL`. however, at fewest one of these two must be defined for every
-option.
+`short_name` is optional, and it may be left undefined for this option by
+passing '\0'. `long_name` is also optional and may be left undefined by passing
+`NULL`. however, at fewest one of these two must be defined for every option.
 
 the fields which are set by `simple_opt_parse` are:
 
@@ -49,7 +62,9 @@ the fields which are set by `simple_opt_parse` are:
 `was_seen` indicates if this option was encountered during parsing,
 `arg_is_stored` if an argument was passed to the option, and the `val_<type>`
 fields contain the value passed (with the correct field to set being determined
-by the `type` field shown above).
+by the `type` field shown above) for all but `SIMPLE_OPT_STRING_SET`, for which
+`val_string_set_idx` is set, an index into the `string_set` field's array,
+indicating which possibility was matched.
 
 options of the following types:
 
@@ -57,10 +72,13 @@ options of the following types:
 	SIMPLE_OPT_BOOL,
 	SIMPLE_OPT_INT,
 	SIMPLE_OPT_UNSIGNED,
+	SIMPLE_OPT_DOUBLE,
+	SIMPLE_OPT_CHAR,
 	SIMPLE_OPT_STRING,
+	SIMPLE_OPT_STRING_SET,
 ```
 
-take arguments. if the user passes a short option on the cli, that options
+take arguments. if the user passes a short option on the cli, that option's
 argument is passed as the following cli argument, like so:
 
 ```
@@ -68,8 +86,7 @@ argument is passed as the following cli argument, like so:
 ```
 
 if the user passes a long option on the cli, that option's argument can be
-passed either as the following cli argument or following an `=` typed at the
-end of the argument, like so:
+passed either as the next cli argument or appended to a trailing `=`, like so:
 
 ```
 ./a.out --opt-x <arg_goes_here>
@@ -80,15 +97,42 @@ arguments acceptable to type `SIMPLE_OPT_BOOL` are `true`, `yes`, or `on`, all
 of which result in a value of true, and `false`, `no`, or `off`, which result
 in a value of false.
 
-arguments acceptable to type `SIMPLE_OPT_INT` must be decimal integers (that is
-digit-only strings) with an optional leading sign indicator of `-` or `+`.
+arguments acceptable to type `SIMPLE_OPT_INT` must be integers with an optional
+leading sign indicator of '-' or '+'. they are assumed decimal unless given a
+prefix to indicate otherwise ('0' for octal and '0x' for hexadecimal).
+arguments with values too large (negative or positive) to be stored in a signed
+integer `long` will also be rejected.
+
+arguments acceptable to type `SIMPLE_OPT_UNSIGNED` are the same as those
+acceptable to `SIMPLE_OPT_INT`, save that they cannot have a sign indicator and
+are limited to the size of an `unsigned long`.
 
-arguments acceptable to type `SIMPLE_OPT_UNSIGNED` must be decimal integers
-(that is digit-only strings).
+arguments acceptable to type `SIMPLE_OPT_DOUBLE` may be any representation of a
+floating point number that can be read by the standard library `strtod`
+function and stored in a `double` type. this includes arguments like "4.9",
+"-1.2e20", "infinity", or "nan".
+
+arguments acceptable to type `SIMPLE_OPT_CHAR` may be any single-byte
+character.
 
 arguments acceptable to type `SIMPLE_OPT_STRING` may be any string of
 characters the user passes.
 
+arguments acceptable to type `SIMPLE_OPT_STRING_SET` may be any character
+string which also appears in the programmer-defined NULL-terminated array of
+strings in the `string_set` field. in practice, adding an argument of this type
+would look something like this:
+
+```
+const char *set[] = { "choice_a", "choice_b", ..., NULL };
+
+struct simple_opt options[] = {
+	...
+	{ SIMPLE_OPT_STRING_SET, <short_name>, <long_name>, <true|false>,
+	[description], [custom_arg_string], set },
+	...
+};
+```
 
 ### struct simple_opt_result
 
@@ -144,8 +188,9 @@ limit can also be resized by defining `SIMPLE_OPT_MAX_ARGC`
 finally, `SIMPLE_OPT_RESULT_MALFORMED_OPTION_STRUCT` is returned if the
 programmer has passed a `struct simple_opt` array which contains disallowed
 option configurations (that is, two options share a `short_name` or
-`long_name`, an option has neither a `short_name` nor a `long_name`, or an
-option of type `SIMPLE_OPT_FLAG` is marked as requiring an argument)
+`long_name`, an option has neither a `short_name` nor a `long_name`, an option
+of type `SIMPLE_OPT_FLAG` is marked as requiring an argument, or an option of
+type `SIMPLE_OPT_STRING_SET` has a NULL `string_set` field)
 
 
 functions
@@ -218,8 +263,8 @@ defined above.
 
 *note:* usage printing's word wrap operates under the assumptions that your
 language delimits words with spaces (i.e. "when i was a child..." vs.
-"子供時代に..."), that the font used is fixed-width, and that every character
+"子供時代に..."), that the font used is fixed-width and that every character
 occupies one column (that is, there are no ｗｉｄｅ characters, combining
-diacritics, etc) and one byte (no multi-byte utf-8 characters). if these
-assumptions do not apply to your use case, you should use an alternative method
-for usage printing.
+diacritics, etc), and that all characters are one byte (no multi-byte utf-8
+characters). if these assumptions do not apply to your use case, you should use
+an alternative method for usage printing.