# kcli
**kcli** is a module that implements common routines used by command-line utilities, such as option parsing, usage display, and more.
## functions
### 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:
#include <k/core.h>
#include <k/io.h>
#include <k/cli.h>
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" }