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_opts.

• 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" }