/**	@file	dk3opt.h	Command line options.

This module is used to process command line options.

Different options - with or without an argument - can be used.

In the examle you see we specify an array of options first.
Each option can be specified as short option (i.e. "-a") and
long option (i.e. "--append"). Some of the options can require
an option argument, this is specified by a non-0 number as third
element.

When creating an option set you specify the array and the array
length.

The next 2 arguments are "further option" indicators (unused here).

We can use dk3opt_is_set() to check whether or not an option was set,
dk3opt_get_short_arg() to obtain an object argument and
dk3opt_get_num_args() and dk3opt_get_arg() to traverse the remaining
command line arguments.

@code
/**	Options for the copy operation.
*/
static dk3_option_t const example_copy_options[] = {
  { dkT('a'), dkT("append"), 0 },
  { dkT('i'), dkT("input"), 1 }
};

/**	Size of example_copy_options array (number of elements).
*/
static size_t const example_sz_copy_options =
sizeof(example_copy_options)/sizeof(dk3_option_t);

dkChar const		*fn;
dk3_option_set_t	*opt;
int			 i;
int			 na;

opt = dk3opt_open_app(
  example_copy_options, example_sz_copy_options,
  dkT('o'), NULL, argc, argv, app
);
if(opt) {
  if(0 == dk3opt_get_error_code(opt)) {
    if(dk3opt_is_set(opt, dkT('a'))) {
      ... Option -a or --append was used ...
    }
    if(dk3opt_is_set(opt, dkT('i'))) {
      ... Option -i or --input was used ...
      fn = dk3opt_get_short_arg(opt, dkT('i'));
      if(fn) {
        ... fn is now the file name specified as argument to -i ...
      } else {
        /* ERROR: No argument for -i specified! */
      }
    }
    na = dk3opt_get_num_args(opt);
    for(i = 0; i < na; i++) {
      fn = dk3opt_get_arg(opt, i);
      if(fn) {
        ... Now process command line argument ...
      } else {
        /* ERROR: Bug in dk3opt */
      }
    }
  } else {
    /* ERROR: Problem while parsing command line options! */
  }
  dk3opt_close(opt);
} else {
  /* ERROR: Failed to open option set! */
}
@endcode

"Further options" are options like in a call
@code
example -o a=b -o c=d -o e=f ...
@endcode
which can occur multiple times and require an argument each time.

*/