Khepera III Toolbox/The Toolbox/Modules/commandline

The commandline module parses command line values and provides a simple interface for accessing the values. The module expects the command line arguments to consist of

• options with exactly one value (key-value pairs), e.g. -s 10000 or --speed 10000
• options without value (just keys), e.g. -h or --help
• an argument list, holding all values that were provided without a key

As an example, the command line

./my_program --white-floor --speed 15000 10 12 10

would result in one key (--white-floor), one key-value pair (--speed 15000) and three arguments (10, 12, 10).

Synopsis

// Initialize the module
commandline_init();

// Register an option without value (by default, options are considered key-value pairs)
struct sCommandLineOption *option_white_floor = commandline_option_register("-wf", "--white-floor", cCommandLine_Option);

// Parse the command line
commandline_parse(int argc, char *argv[]);

// Check if the -h --help option was provided
if (commandline_option_provided("-h", "--help")) {
    ...
}

// Read the -s --speed option
int value = commandline_option_value_int("-s", "--speed", int defaultvalue);
float value = commandline_option_value_float("-s", "--speed", float defaultvalue);
const char *value = commandline_option_value("-s", "--speed", const char *defaultvalue);

// Obtain the number of arguments provided
int count = commandline_argument_count();

// Read argument (the index counter starts with 0)
int value = commandline_argument_int(int index, int defaultvalue);
float value = commandline_argument_float(int index, float defaultvalue);
const char *value = commandline_argument(int index, const char *defaultvalue);

// The following two lines are equivalent, as the option "--white-floor" was registered above
white_floor = option_white_floor->provided;
white_floor = commandline_option_provided("-wf", "--white-floor");

Description

commandline_register_option registers an option with a specific type. By default (for all options that are not explicitly registered), an option is of type cCommandLine_Option_Value and "eats" the next command line argument. E.g. the command line:

./my_program --white-floor 15

would be parsed as one key-value pair (--white-floor 15) by default. If --white-floor is registered as cCommandLine_Option, however, the same line will be parsed as one option (--white-floor) and one argument (15).

Once all necessary options have been registered, commandline_parse can be called to parse the command line. Subsequently, the function commandline_option_value and its _int and _float versions can be used to access option value, while commandline_option_provided returns whether the option has occurred on the command line or not. To access the arguments, commandline_argument and its _int and _float versions are available. The index must be smaller than the number returned by commandline_argument_count.

Option Hooks

Alternatively, a program can register a hook with an option:

// The function to process the --white-floor argument.
void white_floor_hook(struct sCommandLineOption *option) {
    char *value = option->value;
}

int main(int argc, char *argv[]) {
    ...
    commandline_init();
    ...

    // Register a hook for --white-floor
    commandline_option_register_hook("-wf", "--white-floor", cCommandLine_Option_Value, white_floor_hook);

    ...
    commandline_parse(argc, argv);
    ...
}

The hook function will be called each time the corresponding option appears on the command line. Note that the function will be invoked more than once if the user provides the same option multiple times.