aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorkatherine <shmibs@shmibbles.me>2018-03-19 20:38:34 -0700
committerkatherine <shmibs@shmibbles.me>2018-03-19 20:38:34 -0700
commite2efbbe64e1cea3942e9ffc5c60f9e3f60975180 (patch)
treea455ee447bc9dbb00163dece65c8a351eab81509 /doc
parent4593a526a91d40d26cf6799e6150bda6769f9bed (diff)
downloadsimple-opt-e2efbbe64e1cea3942e9ffc5c60f9e3f60975180.tar.gz
update documentation for new functionality
added SIMPLE_OPT_CHAR, SIMPLE_OPT_DOUBLE, and SIMPLE_OPT_STRING_SET types
Diffstat (limited to 'doc')
-rw-r--r--doc/example.c5
-rw-r--r--doc/interface.md81
2 files changed, 65 insertions, 21 deletions
diff --git a/doc/example.c b/doc/example.c
index 1f2708c..18aec1c 100644
--- a/doc/example.c
+++ b/doc/example.c
@@ -23,8 +23,6 @@ int main(int argc, char **argv)
{ SIMPLE_OPT_STRING_SET, '\0', "set-choice", true,
"a choice of one string from a NULL-terminated array",
"(str_a|str_b)", set },
- { SIMPLE_OPT_CHAR, 'c', "char", false,
- "(optionally) takes a character argument" },
{ SIMPLE_OPT_END },
};
@@ -116,7 +114,8 @@ int main(int argc, char **argv)
break;
case SIMPLE_OPT_STRING_SET:
- printf(", val: %s", set[options[i].val_string_set_idx]);
+ printf(", val: %s",
+ options[i].string_set[options[i].val_string_set_idx]);
break;
default:
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 wide 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.