---

2.9 Option Parsing Flags ¶

There are several flags which affect option parsing in different ways. These flags are passed in the flags parameter to mu_opt_context_new (see Parsing Options and Environment).

Constant: MU_OPT_PERMUTE ¶

This flag indicates that mu_parse_opts should rearrange argv so that the options are at the beginning, and positional arguments are at the end.⁵ If this flag is not given, option parsing will stop as soon as the first non-option argument is encountered. Option parsing will also stop when the string ‘--’ is encountered, whether or not this flag was given. The ‘--’ string will be treated as an option, i.e., it will be counted in the return value of mu_parse_opts and, if this flag is set, it will be moved before all the other positional arguments in argv.

If the environment variable POSIXLY_CORRECT is set, or the MU_OPT_STOP_AT_ARG flag is used, mu_parse_opts will act as though this flag were not given even if it was. Note that POSIXLY_CORRECT is searched for in the env parameter given to mu_opt_context_new_with_env, or in the program environment if no env parameter is given or if mu_opt_context_new was used to create the option parsing context. If you want to ignore POSIXLY_CORRECT entirely, use the MU_OPT_IGNORE_POSIX flag.

Constant: MU_OPT_BUNDLE ¶

This flag enables bundling of short options. Without this flag, long options may be specified with a single ‘-’ or ‘--’. When this flag is set, long options may only be specified with ‘--’.

So when this flag is set, -abc will be treated as three short options, a, b, and c (assuming that a and b don’t take arguments⁶), whereas without this flag, -abc will be treated as a single long option, abc.

Note that when this flag is not set, short options with optional arguments take precedence over long options. So, if there is a short option, o, which takes an optional argument, and another long option, option (it doesn’t matter whether it takes an argument or not), then the string -option is a short option, o with an argument ‘ption’.

While this may seem counter-intuitive at first, the reason for this seemingly strange behavior becomes apparent when you consider a short option, o, which takes an optional argument and a long option, option. (Again, it doesn’t matter whether the long option takes an argument or not.) Suppose that instead, long options took precedence over short ones.⁷ Now lets look at the -option example again. It would be parsed as a single long option, option. But what if you wanted to pass the o short option an argument ‘ption’? Or indeed, even just ‘p’? It would be parsed as a long option, option. So there is no possible way to pass an argument to the o short option such that ‘ption’ begins with that argument (or is the argument). But, you ask, couldn’t you write -o ption? You could, if the o short option takes a required argument, but not if it takes an optional argument, because optional arguments to short options are required to be specified as part of the option itself (see Option Arguments). Note that you can still write the option long option as --option, which is unambiguous, so there is no issue.

Since this behavior can be confusing and counter-intuitive, long options take precedence when the short option that would match takes a required argument, and the long option matches exactly. Going back to the above example, if the o short option instead took a required argument, ‘-option’ would be the long option option, rather than the short option o, with an argument ‘ption’. Note, however, that ‘-opt’ would be the o short option with an argument ‘pt’. Also note that if the option long option did not exist, ‘-option’ would be the short option o with an argument ‘ption’. If you want to avoid ambiguity, you should always pass required arguments to short options in the next argument, and precede long options with two dashes like so: ‘-o arg --option’.

Constant: MU_OPT_CONTINUE ¶

This flag should be used if you are going to call mu_parse_opts more than once. See Ordered Option Parsing for more information on how to use this flag correctly.

If the POSIXLY_CORRECT environment variable is set, or the MU_OPT_STOP_AT_ARG flag is passed, all arguments after the first non-option arguments will be treated as non-option arguments as well. Note that POSIXLY_CORRECT is searched for in the env parameter given to mu_opt_context_new_with_env, or in the program environment if no env parameter is given or if mu_opt_context_new was used to create the option parsing context. If you want to ignore POSIXLY_CORRECT entirely, use the MU_OPT_IGNORE_POSIX flag.

Constant: MU_OPT_ALLOW_INVALID ¶

This flag makes mu_parse_opts treat invalid options as positional arguments. It can be useful if you are writing a function which parses some options, but then leaves the rest for the caller to parse. An example of a function which does this (although it does not use Mu) is gtk_init (see section Main loop and Events in GTK+ 3 Reference Manual).

Note: if you use mu_opt_context_add_help_options, the help option will only print the help for the context you called mu_opt_context_add_help_options with. mu_opt_context_add_help_options has no way of knowing what options will be parsed in the future. So if you are writing a function like that described above, you may wish instead to make your function take an option context as a parameter, and then add some standard ones using mu_opt_context_add_options (see Parsing Options and Environment).

Constant: MU_OPT_IGNORE_POSIX ¶

Ignore the POSIXLY_CORRECT environment variable even if it is set. This flag can be used for programs for which it would not make sense to parse options in a POSIXly correct way. For example, you might have an option which acts on the last positional argument given before it.

Constant: MU_OPT_STOP_AT_ARG ¶

Stop parsing options after the first positional argument. I.e., act as though the POSIXLY_CORRECT environment variable were set. If this flag is used, MU_OPT_IGNORE_POSIX has no effect.

Note that this behavior is the default, unless the MU_OPT_PERMUTE flag is used, the MU_OPT_CONTINUE flag is used, and/or an argument callback is used (see Ordered Option Parsing).