File kcli/kcli.md artifact 91db6a8cad part of check-in 93014cedbc
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.
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 theargv
array.const char** argv
- theargv
pointer passed to theentry
function, representing the command-line arguments passed to the program.const char* desc
- program descriptionconst 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>
u8 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 me = {
"demo", e.argc, e.argv,
"a demonstration of the kcli_set type",
params, Kmsz(params),
options, Kmsz(options)
},
size_t args_parsed = kcli_parse(&me);
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 functionvoid* 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 usagekcli_opt_string
- flag tells kcli to add a string to the list of expected parameters; appropriate string will be returnedkcli_opt_oct
- flag tells kcli to add an octal number to the list of expected parameterskcli_opt_dec
- flag tells kcli to add a decimal number to the list of expected parameterskcli_opt_hex
- flag tells kcli to add a hexdecimal number to the list of expected parameterskcli_opt_flag
- flag is an option: will returnkcli_flag_on
if entered at least once,kcli_flag_off
otherwise.kcli_opt_toggle
- flag toggles value on and off: will returnkcli_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 of4
).
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 parameterkcli_param_kind kind
- the kind of parameter passedkcli_class class
- whether or not the parameter is optionalvoid* val
- a pointer to an appropriate type of variable to fillconst 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 acceptedkcli_param_string
- parameter will not be parsed; a raw string will be returnedkcli_param_oct
- parameter will be parsed as an octal numberkcli_param_dec
- parameter will be parsed as a decimal numberkcli_param_hex
- parameter will be parsed as a hexadecimal number
enum kcli_class
kcli_class_forbidden
- parameter may not be passedkcli_class_optional
- parameter may or may not be passedkcli_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 offkcli_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" }