Differences From
Artifact [fb0395874f]:
28 28
29 29 ## kcli_usage(kcli_set, kiochan)
30 30 kcli_usage() takes a `kcli_set` and prints a succinct usage summary to a [kiochan](../kio/kio.md).
31 31
32 32 # types
33 33
34 34 ## struct kcli_set
35 -`kcli_set` is a struct containing information about your program, such as its name, a synopsis of its function, a pointer to `argv`, and a list of `kcli_opt`s.
35 +`kcli_set` is a struct containing information about your program, such as its name, a synopsis of its function, a pointer to an array of arguments, and a list of `kcli_opt`s.
36 36
37 37 * `const char* name` - program name (if null, will be determined from argv instead)
38 + * `const char* version` - a string describing the program version (if null, version will not be printed)
39 + * `const char** args` - the `argv` pointer passed to the `entry` function, representing the command-line arguments passed to the program.
38 40 * `size_t argc` - the number of arguments in the `argv` array.
39 - * `const char** argv` - the `argv` pointer passed to the `entry` function, representing the command-line arguments passed to the program.
40 41 * `const char* desc` - program description
41 42 * `const kcli_param* params` - a list of options expected by the program.
42 43 * `size_t paramc` - the number of params in the list to process.
43 44 * `const kcli_opt* opts` - a list of options expected by the program.
44 45 * `size_t optc` - the number of options in the list to process.
45 46
46 47 a kcli_set might be used like so:
................................................................................
51 52 stat entry(kenv e) {
52 53 kcli_flag aardvark;
53 54 kcli_flag zebra;
54 55 char* user;
55 56 char* password;
56 57 long age;
57 58 kcli_param params[] = {
58 - { "user", kcli_param_string, kcli_class_required,
59 + { "user", kcli_param_string, kcli_rule_required,
59 60 &user, "the user to log in as" }
60 61 // or Kcli_param(user,string,required,"the user to log in as"),
61 62
62 - { "age", kcli_param_dec, kcli_class_optional,
63 + { "age", kcli_param_dec, kcli_rule_optional,
63 64 &age, "the age of the user" }
64 65 // or Kcli_param(age,dec,optional,"the age of the user"),
65 66 };
66 67 kcli_opt options[] = {
67 68 { 'a', "aardvark", kcli_opt_flag, &aardvark,
68 69 "a nocturnal burrowing mammal" },
69 70 // or Kcli_opt(aardvark, 'a', flag, "a nocturnal burrowing mammal")
70 71 { 'z', "zebra", kcli_opt_flag, &zebra,
71 72 "a striped equine" },
72 73 { 'p', "password", kcli_opt_string, &password,
73 74 "the password to log in with" }
74 75 };
75 76 kcli_set argset = {
76 - "demo", e.argc, e.argv,
77 + "demo", e.args, e.argc,
77 78 "a demonstration of the kcli_set type",
78 79 params, Kmsz(params),
79 80 options, Kmsz(options)
80 81 },
81 - size_t args_parsed = kcli_parse(&argset);
82 - if (args_parsed == 0) { kcli_usage(&me, e.err); return 1; }
82 + size_t args_parsed = kcli_parse(argset);
83 + if (args_parsed == 0) { kcli_usage(me, e.err); return 1; }
83 84
84 85 return 0;
85 86 }
86 87
87 -### struct kcli_opt
88 +## struct kcli_opt
88 89 a `kcli_opt` is a representation of a command-line flag and its function. each option must have a unique `id` and/or a unique `name`.
89 90
90 91 * `char id` - the short single-character form of the flag (or NUL for no short form)
91 92 * `const char* name` - the long string form of the flag (or NULL for no long form)
92 93 * `kcli_opt_kind kind` - enum that describes how the flag will function
93 94 * `void* val` - a pointer to an appropriate type to store the return value in.
94 95 * `const char* desc` - a description of the flag's purpose and function (or NULL for no description)
95 96
96 -#### enum kcli_opt_kind
97 +## enum kcli_opt_kind
97 98
98 99 * `kcli_opt_none` - flag is disabled and will not be shown in usage
99 100 * `kcli_opt_string` - flag tells kcli to add a string to the list of expected parameters; appropriate string will be returned
101 + * `kcli_opt_int` - flag tells kcli to add an integer to the last of expected parameters; must be bitwise-OR'd with default base
100 102 * `kcli_opt_oct` - flag tells kcli to add an octal number to the list of expected parameters
101 103 * `kcli_opt_dec` - flag tells kcli to add a decimal number to the list of expected parameters
102 104 * `kcli_opt_hex` - flag tells kcli to add a hexdecimal number to the list of expected parameters
103 105 * `kcli_opt_flag` - flag is an option: will return `kcli_flag_on` if entered at least once, `kcli_flag_off` otherwise.
104 106 * `kcli_opt_toggle` - flag toggles value on and off: will return `kcli_flag_on` if entered an odd number of times, `kcli_flag_off` otherwise.
105 107 * `kcli_opt_accumulate` - flag increments a value every time it is entered; often used to implement `-v (--verbose)`-style options (e.g. `-vvvv` would return a value of `4`).
106 108 * `kcli_opt_enum` - flag is one of a series of enumerated values, which will be matched against a table to yield the associated integer.
107 109
108 -### struct kcli_param
110 +## struct kcli_param
109 111 `kcli_param` describes a parameter that may be passed to the program whether or not any flags are passed.
110 112
111 113 * `const char* name` - a short name for the parameter
112 114 * `kcli_param_kind kind` - the kind of parameter passed
113 - * `kcli_class class` - whether or not the parameter is optional
115 + * `kcli_rule rule` - whether or not the parameter is optional
114 116 * `void* val` - a pointer to an appropriate type of variable to fill
115 117 * `const char* desc` - a description of the parameter's function
116 118
117 -#### enum kcli_param_kind
119 +### enum kcli_param_kind
118 120 * `kcli_param_none` - parameter is disabled and will not be expected or accepted
119 121 * `kcli_param_string` - parameter will not be parsed; a raw string will be returned
122 + * `kcli_param_enum` - parameter will be matched against an enumeration table
123 + * `kcli_param_int` - parameter will be parsed as an integer; must be bitwise-OR'd with default base
120 124 * `kcli_param_oct` - parameter will be parsed as an octal number
121 125 * `kcli_param_dec` - parameter will be parsed as a decimal number
122 126 * `kcli_param_hex` - parameter will be parsed as a hexadecimal number
123 127
124 -### enum kcli_class
125 - * `kcli_class_forbidden` - parameter may not be passed
126 - * `kcli_class_optional` - parameter may or may not be passed
127 - * `kcli_class_required` - parameter must be passed
128 +## enum kcli_rule
129 + * `kcli_rule_forbidden` - parameter may not be passed
130 + * `kcli_rule_optional` - parameter may or may not be passed
131 + * `kcli_rule_required` - parameter must be passed
128 132
129 -### enum kcli_flag
133 +## enum kcli_flag
130 134 results that an option of kind `kcli_opt_flag` can return.
131 135
132 136 * `kcli_flag_off = 0` - flag is off
133 137 * `kcli_flag_on = 1` - flag is on
134 138
135 -## macros
139 +# macros
136 140
137 -### Kcli_param(field, kind, class, description)
141 +## Kcli_param(field, kind, class, description)
138 142 a convenience macro for filling out parameter lists.
139 143
140 144 `Kcli_param(field,a,b,"description")` is transformed into:
141 145
142 - { "field", kcli_param_a, kcli_class_b, &field, "description" }
146 + { "field", kcli_param_a, kcli_rule_b, &field, "description" }
143 147
144 -### Kcli_opt(field, kind, class, description)
148 +## Kcli_opt(field, kind, class, description)
145 149 a convenience macro for filling out option lists.
146 150
147 151 `Kcli_opt(name,'n',string,"description")` is transformed into:
148 152
149 153 { 'n', "name", kcli_opt_string, &name, "description" }