diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/example.c | 5 | ||||
| -rw-r--r-- | doc/interface.md | 81 |
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 ｗｉｄｅ 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. |