Qore Programming Language Reference Manual: Qore::GetOpt Class Reference

Qore Programming Language Reference Manual 0.8.11

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | List of all members
Qore::GetOpt Class Reference

The GetOpt class provides an easy way to process POSIX-style command-line options in Qore scripts/programs. More...

## Public Member Functions
| constructor (hash options)
| Creates the GetOpt object and sets the option hash with the single required argument. More...
| copy ()
| Throws an exception; objects of this class cannot be copied. More...
hash | parse (reference pgm_args)
| Parses the parameter list according to the option hash passed to the constructor. More...
hash | parse (softlist pgm_args)
| Parses the parameter list according to the option hash passed to the constructor. More...
hash | parse2 (reference pgm_args)
| Parses the parameter list according to the option hash passed to the constructor. More...
hash | parse2 (softlist pgm_args)
| Parses the parameter list according to the option hash passed to the constructor. More...
hash | parse3 (reference pgm_args)
| Parses the parameter list according to the option hash passed to the constructor and displays an explanatory error message on stderr and exits the program if an error occurs. More...
hash | parse3 (softlist pgm_args)
| Parses the parameter list according to the option hash passed to the constructor and displays an explanatory error message on stderr and exits the program if an error occurs. More...

## Detailed Description

The GetOpt class provides an easy way to process POSIX-style command-line options in Qore scripts/programs.

## Member Function Documentation

Qore::GetOpt::constructor | ( | hash | options | ) |

Creates the GetOpt object and sets the option hash with the single required argument.

Parameters

  options | Each key defines the key value for the return hash if any arguments are given corresponding to the string value of the key; The string value of each hash key follows the following pattern: opts`[(=|:)`type`[`modifier`]]` Where the meaning of the above placeholders in italics is: opts: At least one short option and/or a long option name; if both are present, then they must be separated by a comma. The short option must be a single character. `(=|:)`type: if `"="` is used, then the option takes a mandatory argument, if `":"` is used, then the argument is optional. Types are specified as follows: s: string i: integer f: float d: date b: boolean modifier: `"@"` specifies a list, `"+"` an additive value (sum; must be integer or float type)

Example:
  const program_options =
  ( "url" : "url,u=s",
  "xml" : "xml,x",
  "lxml" : "literal-xml,X",
  "verb" : "verbose,v",
  "help" : "help,h" );
  my GetOpt $getopt(program_options);

Exceptions

  GETOPT-PARAMETER-ERROR | option key value is not a string; `"_ERRORS_"` used as option key
  GETOPT-OPTION-ERROR | list option specified as optional; empty option key value string; multiple long options given for key; duplicate options given; invalid attributes for option; unknown modifier given for option

Qore::GetOpt::copy | ( |  | ) |

Throws an exception; objects of this class cannot be copied.

Exceptions

  GETOPT-COPY-ERROR | copying GetOpt objects is not supported

hash Qore::GetOpt::parse | ( | reference | pgm_args | ) |

Parses the parameter list according to the option hash passed to the constructor.

All arguments parsed will be removed from the list reference passed as the sol argument, leaving only unparsed arguments (for example, file names).

If any errors are encountered, the return value hash will have a key `"_ERRORS_"` giving a list of error messages pertaining to the options parsed.

Parameters

  pgm_args | The reference should point to a list of arguments to process (normally `$ARGV`); any argument accepted by the object will be removed from the list

Returns
  A hash keyed by option names (as given in the hash to the GetOpt constructor), where each key's value is the value of the argument passed in the list argument. The hash key `"_ERRORS_"` will contain any errors.

Example:
  my hash $o = $getopt.parse(\$ARGV);
  if (exists $o."_ERRORS_") {
  foreach my string $err in ($o."_ERRORS_")
  stderr.printf("%s\n", $err);
  exit(1);
  }

See Also
  GetOpt::parse2() for a similar method that throws an exception instead of putting error information in the `"_ERRORS_"` key of the hash value returned

hash Qore::GetOpt::parse | ( | softlist | pgm_args | ) |

Parses the parameter list according to the option hash passed to the constructor.

If any errors are encountered, the return value hash will have a key `"_ERRORS_"` giving a list of error messages pertaining to the options parsed.

Parameters

  pgm_args | A list of arguments to process

Returns
  A hash keyed by option names (as given in the hash to the GetOpt constructor), where each key's value is the value of the argument passed in the list argument. The hash key `"_ERRORS_"` will contain any errors.

Example:
  my hash $o = $getopt.parse($ARGV);
  if (exists $o."_ERRORS_") {
  foreach my string $err in ($o."_ERRORS_")
  stderr.printf("%s\n", $err);
  exit(1);
  }

See Also
  GetOpt::parse2() for a similar method that throws an exception instead of putting error information in the `"_ERRORS_"` key of the hash value returned

hash Qore::GetOpt::parse2 | ( | reference | pgm_args | ) |

Parses the parameter list according to the option hash passed to the constructor.

If any errors are encountered, an appropriate exception will be thrown.

Parameters

  pgm_args | The reference should point to a list of arguments to process (normally `$ARGV`); any argument accepted by the object will be removed from the list

Returns
  A hash keyed by option names (as given in the hash to the GetOpt constructor), where each key's value is the value of the argument passed in the list argument

Example:
  try {
  my hash $o = $getopt.parse2(\$ARGV);
  }
  catch ($ex) {
  stderr.printf("%s\n", $ex.desc);
  exit(1);
  }

Exceptions

  GETOPT-ERROR | error parsing arguments

See Also
  GetOpt::parse() for a similar method that puts error information in the `"_ERRORS_"` key of the hash value returned instead of throwing an exception

hash Qore::GetOpt::parse2 | ( | softlist | pgm_args | ) |

Parses the parameter list according to the option hash passed to the constructor.

If any errors are encountered, an appropriate exception will be thrown.

Parameters

  pgm_args | A list of arguments to process

Returns
  A hash keyed by option names (as given in the hash to the GetOpt constructor), where each key's value is the value of the argument passed in the list argument

Example:
  try {
  my hash $o = $getopt.parse2($ARGV);
  }
  catch ($ex) {
  stderr.printf("%s\n", $ex.desc);
  exit(1);
  }

Exceptions

  GETOPT-ERROR | error parsing arguments

See Also
  GetOpt::parse() for a similar method that puts error information in the `"_ERRORS_"` key of the hash value returned instead of throwing an exception

hash Qore::GetOpt::parse3 | ( | reference | pgm_args | ) |

Parses the parameter list according to the option hash passed to the constructor and displays an explanatory error message on stderr and exits the program if an error occurs.

Restrictions:
  Qore::PO_NO_PROCESS_CONTROL

Parameters

  pgm_args | The reference should point to a list of arguments to process (normally `$ARGV`); any argument accepted by the object will be removed from the list

Returns
  A hash keyed by option names (as given in the hash to the GetOpt constructor), where each key's value is the value of the argument passed in the list argument

Example:
  my hash $o = $getopt.parse3(\$ARGV);

See Also
  - GetOpt::parse() for a similar method that puts error information in the `"_ERRORS_"` key of the hash value returned
  - GetOpt::parse2() for a similar method that throws exceptions instead of exiting the program

hash Qore::GetOpt::parse3 | ( | softlist | pgm_args | ) |

Parses the parameter list according to the option hash passed to the constructor and displays an explanatory error message on stderr and exits the program if an error occurs.

Restrictions:
  Qore::PO_NO_PROCESS_CONTROL

Parameters

  pgm_args | A list of arguments to process

Returns
  A hash keyed by option names (as given in the hash to the GetOpt constructor), where each key's value is the value of the argument passed in the list argument

Example:
  my hash $o = $getopt.parse3($ARGV);

Exceptions

  GETOPT-ERROR | error parsing arguments

See Also
  - GetOpt::parse() for a similar method that puts error information in the `"_ERRORS_"` key of the hash value returned
  - GetOpt::parse2() for a similar method that throws exceptions instead of exiting the program