From e2efbbe64e1cea3942e9ffc5c60f9e3f60975180 Mon Sep 17 00:00:00 2001 From: katherine Date: Mon, 19 Mar 2018 20:38:34 -0700 Subject: update documentation for new functionality added SIMPLE_OPT_CHAR, SIMPLE_OPT_DOUBLE, and SIMPLE_OPT_STRING_SET types --- doc/example.c | 5 ++-- doc/interface.md | 81 +++++++++++++++++++++++++++++++++++++++++++------------- 2 files changed, 65 insertions(+), 21 deletions(-) (limited to 'doc') 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_, , , ...}, + { SIMPLE_OPT_, , , ...}, + ... + { 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_` 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 @@ -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, , , , + [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. -- cgit v1.2.3