#./fio-stl/005 cli.h

23 public symbols.

#Macros

#FIO_CLI_ARG_NONE

#define FIO_CLI_ARG_NONE FIO_CLI_ARG_PRINT_HEADER

Symbol type: macro

#FIO_CLI_STRING

#define FIO_CLI_STRING(line)   \
  ((fio___cli_line_s){.t = FIO_CLI_ARG_STRING, .l = line})

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

Symbol type: macro

#FIO_CLI_BOOL

#define FIO_CLI_BOOL(line)   \
  ((fio___cli_line_s){.t = FIO_CLI_ARG_BOOL, .l = line})

Indicates the CLI argument is a Boolean value.

Symbol type: macro

#FIO_CLI_INT

#define FIO_CLI_INT(line) ((fio___cli_line_s){.t = FIO_CLI_ARG_INT, .l = line})

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

Symbol type: macro

#FIO_CLI_PRINT

#define FIO_CLI_PRINT(line)   \
  ((fio___cli_line_s){.t = FIO_CLI_ARG_PRINT, .l = line})

Indicates the CLI string should be printed as is with proper offset.

Symbol type: macro

#FIO_CLI_PRINT_LINE

#define FIO_CLI_PRINT_LINE(line)   \
  ((fio___cli_line_s){.t = FIO_CLI_ARG_PRINT_LINE, .l = line})

Indicates the CLI string should be printed as is with no offset.

Symbol type: macro

#FIO_CLI_PRINT_HEADER

#define FIO_CLI_PRINT_HEADER(line)   \
  ((fio___cli_line_s){.t = FIO_CLI_ARG_PRINT_HEADER, .l = line})

Indicates the CLI string should be printed as a header.

Symbol type: macro

#Types

#fio_cli_arg_e

typedef enum {
/** A String CLI argument */
FIO_CLI_ARG_STRING,
/** A Boolean CLI argument */
FIO_CLI_ARG_BOOL,
/** An integer CLI argument */
FIO_CLI_ARG_INT,
FIO_CLI_ARG_PRINT,
FIO_CLI_ARG_PRINT_LINE,
FIO_CLI_ARG_PRINT_HEADER,
} fio_cli_arg_e

Used internally.

Symbol type: type

#Functions

#fio_cli_start

#define fio_cli_start(argc, argv, unnamed_min, unnamed_max, description, ...)   \
  fio_cli_start((argc),   \
                (argv),   \
                (unnamed_min),   \
                (unnamed_max),   \
                (description),   \
                (fio___cli_line_s[]){__VA_ARGS__, {0}})

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 function / macro accepts the following arguments:

• argc: command line argument count.
• argv: command line argument list (array).
• unnamed_min: the required minimum of un-named arguments.
• unnamed_max: the maximum limit of un-named arguments.
• description: a C string containing the program's description.
• named arguments list: a list of C strings describing named arguments.

The following optional type requirements are:

• FIO_CLI_STRING(desc_line) - (default) string argument.
• FIO_CLI_BOOL(desc_line) - boolean argument (no value).
• FIO_CLI_INT(desc_line) - integer argument.
• FIO_CLI_PRINT_HEADER(desc_line) - extra header for output.
• FIO_CLI_PRINT(desc_line) - extra information for output.

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.

Un-named arguments shouldn't be listed in the named arguments list.

Example use:

fio_cli_start(argc, argv, 0, 0, "The NAME example accepts the following:", FIO_CLI_PRINT_HREADER("Concurrency:"), FIO_CLI_INT("-t -thread number of threads to run."), FIO_CLI_INT("-w -workers number of workers to run."), FIO_CLI_PRINT_HREADER("Address Binding:"), "-b, -address the address to bind to.", FIO_CLI_INT("-p,-port the port to bind to."), FIO_CLI_PRINT("\t\tset port to zero (0) for Unix s."), FIO_CLI_PRINT_HREADER("Logging:"), FIO_CLI_BOOL("-v -log enable logging.") );

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

This function is NOT thread safe.

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_cli_start

void fio_cli_start FIO_NOOP(int argc, char const *argv[], int unnamed_min, int unnamed_max, char const *description, fio___cli_line_s *arguments)

Never use the function directly, always use the MACRO, because the macro attaches a NULL marker at the end of the names argument collection.

Symbol type: function

#fio_cli_end

void fio_cli_end(void)

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

This function is NOT thread safe.

Symbol type: function

#fio_cli_get

char const *fio_cli_get(char const *name)

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

Symbol type: function

#fio_cli_get_str

fio_buf_info_s fio_cli_get_str(char const *name)

Returns the argument's value as a NUL terminated fio_buf_info_s.

Symbol type: function

#fio_cli_get_i

int64_t fio_cli_get_i(char const *name)

Returns the argument's value as an integer.

Symbol type: function

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

Note: this may be a macro only / macro wrapper for a function.

Symbol type: macro

#fio_cli_unnamed_count

unsigned int fio_cli_unnamed_count(void)

Returns the number of unnamed argument.

Symbol type: function

#fio_cli_unnamed

char const *fio_cli_unnamed(unsigned int index)

Returns the unnamed argument using a 0 based index.

Symbol type: function

#fio_cli_unnamed_str

fio_buf_info_s fio_cli_unnamed_str(unsigned int index)

Returns the unnamed argument using a 0 based index.

Symbol type: function

#fio_cli_set

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

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

fio_cli_set("-p", "hello");

This function is NOT thread safe.

Symbol type: function

#fio_cli_set_i

void fio_cli_set_i(char const *name, int64_t i)

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

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

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

This function is NOT thread safe.

Symbol type: function

#fio_cli_set_unnamed

unsigned int fio_cli_set_unnamed(unsigned int index, const char *)

Sets / adds an unnamed argument to the 0 based array of unnamed elements.

Symbol type: function

#fio_cli_each

size_t fio_cli_each(int (*task)(fio_buf_info_s name, fio_buf_info_s value, fio_cli_arg_e arg_type, void *udata), void *udata)

Calls task for every argument received.

Symbol type: function

#fio_cli_type

fio_cli_arg_e fio_cli_type(char const *name)

Returns the argument's expected content type.

Symbol type: function