MP4v2

Classes | Functions | Variables
mp4v2::platform::prog Namespace Reference

Command-line argument parsing. More...

## Classes
struct | Option
| Structure describing a single option. More...

## Functions
int | getOption (int argc, char *const *argv, const char *optstr, const Option *longopts, int *idx)
| Get option character from command line argument list. More...
int | getOptionSingle (int argc, char *const *argv, const char *optstr, const Option *longopts, int *idx)
| Get option character from command line argument list and allow long-options with single-hyphens. More...

## Variables
const char * | optarg
| On return from getOption() or getOptionSingle(), points to an option argument, if it is anticipated.
int | optind
| On return from getOption() or getOptionSingle(), contains the index to the next argv argument for a subsequent call to getOption() or getOptionSingle(). More...
int | optopt
| On return from getOption() or getOptionSingle(), saves the last known option character returned by getOption() or getOptionSingle(). More...
int | opterr
| Initialized to 1 and may be set to 0 to disable error messages.
int | optreset
| Must be set to 1 before evaluating the 2nd or each additional set of arguments.

## Detailed Description

Command-line argument parsing.

WARNING: THIS IS A PRIVATE NAMESPACE. NOT FOR PUBLIC CONSUMPTION.

This namespace provides a mechanism to parse command-line arguments and options for executables. It is identical in behavior to getopt_long functions available with many popular posix-platforms such as Darwin, FreeBSD and Linux. Virtually any OS which has getopt_long will adequately document this functionality. However, to avoid symbol ambiguity with the popular posix implementation, the following identifiers have been renamed:

- getopt_long() -> getOption()
- getopt_long_only() -> getOptionSingle()
- option -> Option
- option.has_arg -> Option.type

## Function Documentation

## ◆ getOption()

int mp4v2::platform::prog::getOption | ( | int | argc,
|  | char *const * | argv,
|  | const char * | optstr,
|  | const Option * | longopts,
|  | int * | idx
| ) |  |

Get option character from command line argument list.

getOption() is similar to posix getopt() but it accepts options in two forms: words and characters. The getOption() function provides a superset of the functionality of getopt(). The getOption() function can be used in two ways. In the first way, every long-option understood by the program has a corresponding short-option, and the Option structure is only used to translate from long-options to short-options. When used in this fashion, getOption() behaves identically to getopt(). This is a good way to add long-option processing to an esxisting program with a minimum of rewriting.

In the second mechanism, a long-option sets a flag in the Option structure structure passed, or will store a pointer to the command line argument in the Option structure passed to it for options that take arguments. Additionally, the long-option's argument may be specified as a single argument with an equal sign, eg:

myprogram --myoption=somevalue

When a long-option is processed, the call to getOption() will return 0. For this reason, long-option processing without shortcuts is not backwards compatible with getopt().

It is possible to combine these methods, providing for long-options processing with short-option equivalents for some options. Less frequently used options would be processed as long-options only.

Parameters

  argc | number of arguments.
  argv | argument array of strings.
  optstr | string containing the following elements: individual characters, and characters followed by a colon to indicate an option argument is to follow. For example, an option string "x" recognizes an option "-x", and an option string "x:" recognizes an option and argument "-x argument".
  longopts | array of Option entries. The last element must be filled with zeroes to indicate end-of-array.
  idx | If not NULL, then the integer pointed to it will be set to the index of the long-option relative to longops.

Returns
  If the flag field is NULL, val field is returned, which is usually just the corresponding short-option. If flag is not NULL, 0 is returned and val is stored in the location pointed to by flag field. A ':' will be returned if there was a missing option argument. A '?' will be returned if an unknown or ambiguous option was used. A -1 will be returned when the argument list has been exhausted.

## ◆ getOptionSingle()

int mp4v2::platform::prog::getOptionSingle | ( | int | argc,
|  | char *const * | argv,
|  | const char * | optstr,
|  | const Option * | longopts,
|  | int * | idx
| ) |  |

Get option character from command line argument list and allow long-options with single-hyphens.

Behaves identically to getOption() with the exception that long-options may start with '-' in addition to '–'. If an option starting with '-' does not match a long option but does match a single-character option, the single-character option is returned.

Parameters

  argc | number of arguments.
  argv | argument array of strings.
  optstr | string containing the following elements: individual characters, and characters followed by a colon to indicate an option argument is to follow. For example, an option string "x" recognizes an option "-x", and an option string "x:" recognizes an option and argument "-x argument".
  longopts | array of Option entries. The last element must be filled with zeroes to indicate end-of-array.
  idx | If not NULL, then the integer pointed to it will be set to the index of the long-option relative to longops.

Returns
  If the flag field is NULL, val field is returned, which is usually just the corresponding short-option. If flag is not NULL, 0 is returned and val is stored in the location pointed to by flag field. A ':' will be returned if there was a missing option argument. A '?' will be returned if an unknown or ambiguous option was used. A -1 will be returned when the argument list has been exhausted.

## Variable Documentation

## ◆ optind

int mp4v2::platform::prog::optind
| extern

On return from getOption() or getOptionSingle(), contains the index to the next argv argument for a subsequent call to getOption() or getOptionSingle().

Initialized to 1 and must be set manually to 1 prior to invoking getOption() or getOptionSingle() to evaluate multiple sets of arguments.

## ◆ optopt

int mp4v2::platform::prog::optopt
| extern

On return from getOption() or getOptionSingle(), saves the last known option character returned by getOption() or getOptionSingle().

On error, contains the character/code of option which caused error.