Command Line Helper

This is a simple Command Line Interface helper extension that makes it easy to handle command line arguments.

NOTE: This documentation is incomplete. I would love your help to finish it up. Until that time, please read the documentation in the fio_cli.h header file.

Overview

Initializing the CLI helper is easy with a single call to the function/macro fio_cli_start.

Data can be accessed either as a C string or an integer using the fio_cli_get and fio_cli_set functions.

example

fio_cli_start(argc, argv, 0, "This example defines the following arguments:",
             "-t -thread number of threads to run.", FIO_CLI_TYPE_INT,
             "-w -workers number of workers to run.", FIO_CLI_TYPE_INT,
             "-b, -address the address to bind to.",
             "-p,-port the port to bind to.", FIO_CLI_TYPE_INT,
             "-v -log enable logging.", FIO_CLI_TYPE_BOOL);

if (fio_cli_get_bool("-v")) {
    printf("Logging is enabled\n");
}

fio_cli_end();

Constants

The following constants are defined by the CLI extension.

FIO_CLI_TYPE_STRING

Indicates the previous CLI argument should be a String (default).

FIO_CLI_TYPE_BOOL

Indicates the previous CLI argument is a Boolean value.

FIO_CLI_TYPE_INT

Indicates the previous CLI argument should be an Integer (numerical). */

Functions

Initialization / Destruction

fio_cli_start

void fio_cli_start(int argc, char const *argv[], int allow_unknown,
                   char const *description,
                   char const **names);
/* Automatically appends a NULL marker at the end of the `names` array. */
#define fio_cli_start(argc, argv, allow_unknown, description, ...)             \
  fio_cli_start((argc), (argv), (allow_unknown), (description),                \
                (char const *[]){__VA_ARGS__, NULL})

This function parses the Command Line Interface (CLI), creating a temporary "dictionary" that allows easy access to the CLI using their names or aliases.

Command line arguments may be typed. If an optional type requirement is provided and the provided arument fails to match the required type, execution will end and an error message will be printed along with a short "help".

The following optional type requirements are:

Argument names MUST start with the '-' character. The first word starting without the '-' character will begin the description for the CLI argument.

The arguments "-?", "-h", "-help" and "--help" are automatically handled unless overridden.

Example use:

fio_cli_start(argc, argv, 0, "this example accepts the following:",
             "-t -thread number of threads to run.", FIO_CLI_TYPE_INT,
             "-w -workers number of workers to run.", FIO_CLI_TYPE_INT,
             "-b, -address the address to bind to.",
             "-p,-port the port to bind to.", FIO_CLI_TYPE_INT,
             "-v -log enable logging.", FIO_CLI_TYPE_BOOL);

This would allow access to the named arguments:

fio_cli_get("-b") == fio_cli_get("-address");

Once all the data was accessed, free the parsed data dictionary using:

fio_cli_end();

It should be noted, arguments will be recognized in a number of forms, i.e.:

app -t=1 -p3000 -a localhost

fio_cli_end

void fio_cli_end(void);

Clears the memory used by the CLI dictionary, removing all parsed data.

Access CLI arguments

fio_cli_get

char const *fio_cli_get(char const *name);

Returns the argument's value as a NUL terminated C String.

fio_cli_get_i

int fio_cli_get_i(char const *name);

Returns the argument's value as an integer.

fio_cli_get_bool

#define fio_cli_get_bool(name) (fio_cli_get((name)) != NULL)

This MACRO returns the argument's value as a boolean.

fio_cli_unknown_count

unsigned int fio_cli_unknown_count(void);

Returns the number of unrecognized argument.

Unknown arguments are only relevant if the allow_unknown argument in fio_cli_start was set to true (1).

fio_cli_unknown

char const *fio_cli_unknown(unsigned int index);

Returns the unrecognized argument using a 0 based index.

Unknown arguments are only relevant if the allow_unknown argument in fio_cli_start was set to true (1).

Set CLI argument data

fio_cli_set

void fio_cli_set(char const *name, char const *value);

Sets the argument's value as a NUL terminated C String (no copy!).

CAREFUL: This does not automatically detect aliases or type violations! it will only effect the specific name given, even if invalid. i.e.:

fio_cli_start(argc, argv,
             "this is example accepts the following options:",
             "-p -port the port to bind to", FIO_CLI_TYPE_INT;

fio_cli_set("-p", "hello"); // fio_cli_get("-p") != fio_cli_get("-port");

Note: this does NOT copy the C strings to memory. Memory should be kept alive until fio_cli_end is called.

fio_cli_set_default

#define fio_cli_set_default(name, value)                                       \
  if (!fio_cli_get((name)))                                                    \
    fio_cli_set(name, value);

This MACRO sets the argument's value only if the argument has no existing value.

CAREFUL: This does not automatically detect aliases or type violations! it will only effect the specific name given, even if invalid. See fio_cli_set.

Important Notes

The CLI extension is NOT thread safe. If you wish to write data to the CLI storage while facil.io is running, you should protect both read and write access to the storage.