Command Line Options

Functions
void	amxrt_cmd_line_options_reset (void)
	Removes all default options. More...
int	amxrt_cmd_line_add_option (int id, char short_option, const char *long_option, int has_args, const char *doc, const char *arg_doc)
	Adds a command line option definition. More...
void	amxrt_cmd_line_set_usage_doc (const char *usage)
	Set the overall usage documentation string. More...
int	amxrt_cmd_line_parse (int argc, char *argv[], amxrt_arg_fn_t fn)
	Starts parsing the command line options. More...
void	amxrt_cmd_line_parse_assignment (const char *option, bool force)
	Parses an command line option or an argument with an assignment. More...
void	amxrt_print_usage (void)
	Prints the usage information and all available options to stdout. More...

Detailed Description

The command line option parser, reads the options passed on the command line and passes them to the configuration.

The command line option parser can handle short options (starting with a single '-') and long options (staring with a double '-'). Options must be put before any other arguments on the command line. The command line option parser stops at the first argument that is not an option (not starting with a '-').

The command line option parser uses getopt_long to parse the options.

The default options handled are:

-h       --help                         Print usage help and exit
-H       --HELP                         Print extended help and exit
-B       --backend so file              Loads the shared object as bus backend
-u       --uri uri                      Adds an uri to the list of uris
-A       --no-auto-detect               Do not auto detect unix domain sockets and back-ends
-C       --no-connect                   Do not auto connect the provided or detected uris
-I       --include-dir dir              Adds include directory for odl parser, multiple allowed
-L       --import-dir dir               Adds import directory for odl parser, multiple allowed
-o       --option name=value            Adds a configuration option
-F       --forced-option name=value     Adds a configuration option, which can not be overwritten by odl files
-O       --ODL odl-string               An ODL in string format, only one ODL string allowed
-D       --daemon                       Daemonize the process
-p       --priority nice level          Sets the process nice level
-N       --no-pid-file                  Disables the creation of a pid-file in /var/run
-E       --eventing                     Enables eventing during loading of ODL files
-d       --dump [caps|config]           Dumps configuration options or capabilities at start-up
-l       --log                          Write to syslog instead of stdout and stderr
-R       --requires root object         Checks if datamodel objects are available or waits until they are available
-V       --version                      Print version

If the default options doesn't fit your usage, they can be removed by calling amxrt_cmd_line_options_reset.

Adding new options (or re-adding some of the default options) can be done using: amxrt_cmd_line_add_option

Use amxrt_cmd_line_parse to start parsing the given command line options.

The syntax for parsing options at command line is:

# option has no argument or an optional argument
  -o
# option has a required or optional argument
  -o arg
  -o=arg

Function Documentation

amxrt_cmd_line_add_option()

int amxrt_cmd_line_add_option	(	int	id,
		char	short_option,
		const char *	long_option,
		int	has_args,
		const char *	doc,
		const char *	arg_doc
	)

Adds a command line option definition.

This function adds a command line option definition to the list of accepted options.

Parameters

id	the id of the option, if 0 is given the short_option is used as id.
short_option	a single character representing the short option/
long_option	a string literal containing the name of the long option without the double '-'
has_args	must be one of no_argument (if the option does not take an argument), required_argument (if the option requires an argument) or optional_argument (if the takes an optional argument).
doc	a string literal describing the option
arg_doc	a string literal describing the argument or NULL if the option doesn't have an argument

Returns

0 when option definition is added, any other value indicates an error.

Definition at line 206 of file amxrt_args.c.

                                                                                                                                      {
    int rv = -1;
    amxrt_t* rt = amxrt_get();
    amxrt_arg_t* option = NULL;
 
    option = (amxrt_arg_t*) calloc(1, sizeof(amxrt_arg_t));
    when_null(option, exit);
 
    option->id = id == 0 ? (int) short_option : id;
    option->short_option = short_option;
    option->long_option = long_option;
    option->has_args = has_args;
    option->doc = doc;
    option->arg_doc = arg_doc;
 
    rv = amxc_llist_append(&rt->cmd_line_args, &option->it);
 
exit:
    if(rv != 0) {
        free(option);
    }
    return rv;
}

amxrt_cmd_line_options_reset()

void amxrt_cmd_line_options_reset

(

void

)

Removes all default options.

Calling this function will remove all defined default options. If some of them are needed they can be re-added using amxrt_cmd_line_add_option

Definition at line 200 of file amxrt_args.c.

                                        {
    amxrt_t* rt = amxrt_get();
    amxc_llist_clean(&rt->cmd_line_args, amxrt_cmd_line_free_option);
}

amxrt_cmd_line_parse()

int amxrt_cmd_line_parse	(	int	argc,
		char *	argv[],
		amxrt_arg_fn_t	fn
	)

Starts parsing the command line options.

Typically this function is called from within the applications main and the argc and argv arguments of the main are passed to this method.

Optionally a function pointer can be provided. This function will be called for each option encountered before the default option handler is used. If the argument handle function returns 0, it indicates that the option is handled and should not be passed to the default handler, when the callback function returns -1 the option parser will stop and the application should exit, when the callback function return -2, the default command line argument option handler is called. If the callback function returns anything else then 0,-1 or -2, it is considered an error and the command line option parser will stop.

The callback function must match this signature

typedef int (* amxrt_arg_fn_t) (amxc_var_t* config,
                                int arg_id,
                                const char* value);

Parameters

argc	the number of arguments available
argv	the vector containing the commandline arguments
fn	(optional) a pointer to a callback function to handle the option or NULL

Returns

A negative number indicates an error, a positive number indicates the index in argv where the parsing has stopped (first non option argument). If the returned value equals argc, all command line options were parsed and handled.

Definition at line 236 of file amxrt_args.c.

                                                                    {
    amxrt_t* rt = amxrt_get();
    amxc_var_t* config = amxrt_get_config();
    int nr_options = amxc_llist_size(&rt->cmd_line_args);
    struct option* long_options = (struct option*) calloc(nr_options + 1, sizeof(struct option));
    amxc_string_t format;
    int index = 0;
    int rv = 0;
    int c;
 
    if(long_options == NULL) {
        // handle error case where calloc failed
        return -1;
    }
 
    optind = 1;
    amxc_string_init(&format, 0);
    amxc_llist_for_each(it, &rt->cmd_line_args) {
        amxrt_arg_t* option = amxc_container_of(it, amxrt_arg_t, it);
        long_options[index].name = option->long_option;
        long_options[index].has_arg = option->has_args;
        long_options[index].val = option->id;
        if(option->has_args == no_argument) {
            amxc_string_appendf(&format, "%c", option->short_option);
        } else if(option->has_args == optional_argument) {
            amxc_string_appendf(&format, "%c::", option->short_option);
        } else {
            amxc_string_appendf(&format, "%c:", option->short_option);
        }
        index++;
    }
 
    index = 0;
    while(1) {
        c = getopt_long(argc, argv, amxc_string_get(&format, 0), long_options, &index);
        if(c == -1) {
            break;
        }
        rv = -2;
        if(fn != NULL) {
            // call provided function
            // if it returns 0 the option is handled
            // if it returns -1 stop option parsing and exit
            // if it returns -2 call default argument handler
            // all others are considered as an error
            rv = fn(config, c, optarg);
        }
        if(rv == -2) {
            rv = amxrt_cmd_line_default(config, c, optarg);
        }
        when_failed_status(rv, exit, rv = -1);
    }
 
exit:
    free(long_options);
    amxc_string_clean(&format);
    return rv == 0 ? optind : rv;
}

amxrt_cmd_line_parse_assignment()

void amxrt_cmd_line_parse_assignment	(	const char *	option,
		bool	force
	)

Parses an command line option or an argument with an assignment.

This function parses a command line option or command line argument with an assignment.

The key will be added to the config options. The config can be retrieved using amxrt_get_config.

Example:

amxrt -o key=value
amxrt key=value

The key can be any string without spaces. The value can a simple value or a JSON string.

If the key contains dots (.), is is used as a path to the config option.

Parameters

option	the command line option value or the command line argument.
force	when set to true, odl config sections can not overwrite this value.

Definition at line 296 of file amxrt_args.c.

                                                                     {
    amxrt_t* rt = amxrt_get();
    amxc_var_t* config = NULL;
    amxc_string_t str_option;
    amxc_llist_t options;
    amxc_string_t* name = NULL;
    amxc_string_t* value = NULL;
    amxc_var_t var_option;
 
    amxc_var_init(&var_option);
    amxc_llist_init(&options);
    amxc_string_init(&str_option, 0);
 
    amxc_string_set(&str_option, option);
    amxc_string_split_to_llist(&str_option, &options, '=');
    when_true(amxc_llist_is_empty(&options), leave);
    when_true(amxc_llist_size(&options) != 2, leave);
 
    name = amxc_string_from_llist_it(amxc_llist_get_first(&options));
    value = amxc_string_from_llist_it(amxc_llist_get_last(&options));
 
    amxc_string_trim(name, NULL);
    amxc_string_trim(value, NULL);
 
    if(amxc_var_set(jstring_t, &var_option, amxc_string_get(value, 0)) != 0) {
        amxc_var_set(cstring_t, &var_option, amxc_string_get(value, 0));
    } else {
        amxc_var_cast(&var_option, AMXC_VAR_ID_ANY);
    }
 
    config = force ? &rt->forced_options : &rt->parser.config;
    amxc_var_set_path(config, amxc_string_get(name, 0), &var_option,
                      AMXC_VAR_FLAG_AUTO_ADD | AMXC_VAR_FLAG_COPY);
 
leave:
    amxc_string_clean(&str_option);
    amxc_llist_clean(&options, amxc_string_list_it_free);
    amxc_var_clean(&var_option);
    return;
}

amxrt_cmd_line_set_usage_doc()

void amxrt_cmd_line_set_usage_doc

(

const char *

usage

)

Set the overall usage documentation string.

When the function amxrt_print_usage the usage documentation is printed to stdout. On the first line the global usage is printed.

Example (default string)

amxrt [OPTIONS] <odl files>

The first part (until the first space) is the name of the application, this is added automatically by amxrt_print_usage (taken from argv[0] and should not be added to the provided string.

Example:

amxrt_cmd_line_set_usage_doc("[OPTIONS] <OBJECT PATH> <FILTER>");

if after this line amxrt_print_usage is called (assuming that the name of the application is "amxrt") the output will look like this:

amxrt [OPTIONS] <OBJECT PATH> <FILTER>

Parameters

usage

A string literal containing the usage overview.

Definition at line 230 of file amxrt_args.c.

                                                     {
    amxrt_t* rt = amxrt_get();
    rt->usage_doc = usage == NULL ? "[OPTIONS] <odl files>" : usage;
}

amxrt_print_usage()

void amxrt_print_usage

(

void

)

Prints the usage information and all available options to stdout.

Using the usage doc string and the defined options the usage information is created and printed to stdout.

The usage doc string can be set using amxrt_cmd_line_set_usage_doc.

Options can be added using amxrt_cmd_line_add_option or all removed using amxrt_cmd_line_options_reset.

The default usage information is: Example:

amxrt [OPTIONS] <odl files>
 
 -h    --help                          Print usage help and exit
 -H    --HELP                          Print extended help and exit
 -B    --backend <so file>             Loads the shared object as bus backend
 -u    --uri <uri>                     Adds an uri to the list of uris
 -A    --no-auto-detect                Do not auto detect unix domain sockets and back-ends
 -C    --no-connect                    Do not auto connect the provided or detected uris
 -I    --include-dir <dir>             Adds include directory for odl parser, multiple allowed
 -L    --import-dir <dir>              Adds import directory for odl parser, multiple allowed
 -o    --option <name=value>           Adds a configuration option
 -F    --forced-option <name=value>    Adds a configuration option, which can not be overwritten by odl files
 -O    --ODL <odl-string>              An ODL in string format, only one ODL string allowed
 -D    --daemon                        Daemonize the process
 -p    --priority <nice level>         Sets the process nice level
 -N    --no-pid-file                   Disables the creation of a pid-file in /var/run
 -E    --eventing                      Enables eventing during loading of ODL files
 -d    --dump-config                   Dumps configuration options at start-up
 -l    --log                           Write to syslog instead of stdout and stderr
 -R    --requires <root object>        Checks if datamodel objects are available or waits until they are available
 -V    --version                       Print version

Definition at line 137 of file amxrt_user_output.c.

                             {
    amxrt_t* rt = amxrt_get();
    const char* name = GET_CHAR(&rt->parser.config, "name");
 
    printf("%s %s\n", name, rt->usage_doc);
 
    if(!amxc_llist_is_empty(&rt->cmd_line_args)) {
        printf("\n");
        printf("%sOptions%s:\n", c(CYAN), c(RESET));
        printf("\n");
 
        amxc_llist_for_each(it, &rt->cmd_line_args) {
            amxrt_arg_t* arg = amxc_container_of(it, amxrt_arg_t, it);
            amxrt_cmd_line_arg(arg->short_option,
                               arg->long_option == NULL ? "" : arg->long_option,
                               arg->arg_doc,
                               arg->doc);
        }
    }
 
    printf("\n");
}