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