Mu includes option parsing capability. Mu can parse command line
options; both short options (a single dash followed by a letter, e.g.,
-s) and long options (two dashes followed by a multi-letter
word, e.g., --long). Long options may also be specified with a
single ‘-’ as long as the flag MU_OPT_BUNDLE is not set
(see Option Parsing Flags).
Mu also supports parsing the environment. See Parsing the Environment for more information.
The option structure is fairly complicated, and its organization is subject to change. For that reason, it is highly recommended that you use designated structure initializers or set the values after declaration.
You can use designated initializers like this:
const MU_OPT options[] = {
{
.short_opt = "s",
.long_opt = "long",
.has_arg = MU_OPT_NONE
},
{ 0 }
};
However, since designated initializers are only available in C99 and later (see (gcc)Designated Inits), this may not be an option for you. The following is equivalent to the above example without using designated initializers:
const MU_OPT options[2] = { 0 };
options[0].short_opt = "s";
options[0].long_opt = "long";
options[0].has_arg = MU_OPT_NONE;
If you would like to use option parsing features, include mu/options.h.
This is an opaque context for parsing options. It is allocated using
mu_opt_context_new and similar functions. To free it, you must
use mu_opt_context_free. Both functions (among others) are
described below.
MU_OPT_CONTEXT * mu_opt_context_new (int argc, char **argv, const MU_OPT *options, int flags) ¶MU_OPT_CONTEXT * mu_opt_context_new_with_env (int argc, char **argv, char **environment, const MU_OPT *options, int flags) ¶Allocate and return a new option parsing context. argv is the list
of arguments to be parsed. argv[0] should be the name the
program was invoked as, and the rest of argv should be the
arguments given on the command line. argc is the length of
argv. Normally, argc and argv should be used directly
from main.
The returned context can also be used for parsing environment variables
through the env_var field of the option structure (see Option Structure). When mu_opt_context_new is used to allocate the
option parsing context, environment variables are parsed in the program
environment (see (libc)Environment Access). If you want to use an
alternative environment, use mu_opt_context_new_with_env to
allocate the option parsing context, in which case environment variables
will be parsed in environment. environment can also be
NULL, in which case environment variable parsing will be
disabled. environment (or the program environment in the case of
mu_opt_context_new) is never modified, unless, of course, any of
the callbacks modify it (see Option Callbacks).
Normally, all arguments will be parsed at once when mu_parse_opts
is called, and the context returned by these functions should only be
passed to mu_parse_opts once. However, you can use
mu_opt_context_set_arg_callback or the MU_OPT_CONTINUE
flag if you care about the order in which options and arguments appear
on the command line (see Ordered Option Parsing).
options is the list of options and environment variables that can
occur in argv and environment (or the program
environment). See Option Structure. Note that options is copied
into the returned context, not used directly. Because of this, you need
not worry about options going out of scope. For example, you might
write a function which returns an option parsing context from a list of
options which is local to that function’s scope. Of course, you still
need to ensure that no pointers referenced by any of the fields in
options go out of scope (cb_data for example; see Option Structure).
flags is a bitmask of flags that effect how options are parsed (see Option Parsing Flags).
If you want to write a function which parses some options, but then
leaves the rest for the caller to parse, consider using the
MU_OPT_ALLOW_INVALID flag (see Option Parsing Flags). Note,
however, that it may instead be better to use
mu_opt_context_add_options (see below).
On error, this function returns NULL and the external variable
errno will be set to indicate the error. For a function which
terminates the program on error, use mu_opt_context_xnew and
mu_opt_context_xnew_with_env (see Safety Functions).
int mu_opt_context_free (MU_OPT_CONTEXT *context) ¶Free the option context, context. For the cb_data fields in
each option, the cb_data_destructor field (if any) will be used
to free that data (see Option Structure and Option Callbacks). If any of the destructors return nonzero,
mu_opt_context_free will return nonzero as well. Otherwise,
mu_opt_context_free will return zero.
Note that all the destructors are called, even if one or more of them return nonzero.
int mu_parse_opts (MU_OPT_CONTEXT *context) ¶Parse the options given in context. Use mu_opt_context_new
or mu_opt_context_new_with_env (see above) to create the
context. On success, the number of arguments parsed is returned. You can
pass this value to mu_shift_args (see below). On error, an error
code is returned, which can be detected by MU_OPT_ERR
(see Option Parsing Errors).
Note that if mu_opt_context_set_arg_callback was called on
context, the number of positional arguments will be
included in the return value as well, if neither the
MU_OPT_PERMUTE nor MU_OPT_STOP_AT_ARG flags are
used. However, if either of these flags are used, the return value will
not include the number of positional arguments parsed, even if
mu_opt_context_set_arg_callback was called. This is so that you
can shift the arguments by the return value and the remaining arguments
will be the non-option positional arguments. Note that this would not be
useful if neither the MU_OPT_PERMUTE flag nor the
MU_OPT_STOP_AT_ARG flag was passed, because it would not be
guaranteed that all the arguments left after shifting actually
were the non-option positional arguments. For this reason,
positional arguments are included in the return value when neither of
these flags are passed. See Ordered Option Parsing.
This type specifies whether to append or prepend options (see
mu_opt_context_add_options below). Values of this type can be
either of the following:
MU_OPT_PREPENDIndicate that options should be prepended (before existing options).
MU_OPT_APPENDIndicate that options should be appended (after existing options).
int mu_opt_context_add_options (MU_OPT_CONTEXT *context, const MU_OPT *options, enum MU_OPT_WHERE where) ¶Add options to context. If where is
MU_OPT_APPEND, append options to the current options in
context. Otherwise, if where is MU_OPT_PREPEND,
prepend options instead. If where is neither
MU_OPT_APPEND nor MU_OPT_PREPEND,
mu_opt_context_add_options will return nonzero and errno
will be set to EINVAL.
On success, this function returns zero. On error, this function returns
nonzero and sets errno to indicate the error.
If you want to add options for printing usage information, use
mu_opt_context_add_help_options (see Formatting Help).
void mu_shift_args (int *p_argc, char ***p_argv, int amount) ¶This function shifts the arguments in *p_argv by
amount and subtracts amount from *p_argc. The
old (*p_argv)[0] will be copied to the new
(*p_argv)[0] after the shift is performed. It can be useful
to call this function with the return value of mu_parse_opts
passed as amount1 and
p_argc and p_argv as the addresses of argc and
argv respectively, as passed to mu_opt_context_new.
But first you should make sure the return value is not an error code (see Option Parsing Errors).