4.6. GetOpt Class

4.6. GetOpt Class
Prev	Chapter 4. System Namespaces and Class Library	Next

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

Table 4.219. GetOpt Method Overview

Method	Except?	Description
`GetOpt::constructor(hash$options)`	Y	Creates the GetOpt object with the option hash passed.
`GetOpt::destructor()`	N	Destroys the object.
`GetOpt::copy()`	Y	Throws an exception; objects of this class cannot be copied.
`hashGetOpt::parse(reference$list_ref)` `hashGetOpt::parse(list$list)`	N	Parses the argument list passed and retuns a hash of the results; if there are any errors, they are returned in the `"_ERRORS_"` key of the hash returned.
`hashGetOpt::parse2(reference$list_ref)` `hashGetOpt::parse2(list$list)`	N	Parses the argument list passed and retuns a hash of the results; if there are any errors, an exception is thrown.

4.6.1. GetOpt::constructor()

Synopsis

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

Prototype

GetOpt::constructor(hash$options)

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);

Table 4.220. Arguments for GetOpt::constructor()

Argument	Description
`hash$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 follows the following pattern:

opts[=|:type[modifier]]

Table 4.221. Option Hash Value String

Component	Description
`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)

Table 4.222. Exceptions Thrown by GetOpt::constructor()

err	desc
`GETOPT-OPTION-ERROR`	There was a syntax or format error in the option specification.

4.6.2. GetOpt::destructor()

Synopsis

Destroys the GetOpt object.

Example

delete $getopt;

4.6.3. GetOpt::copy()

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

Table 4.223. Exceptions Thrown by GetOpt::copy()

err	desc
`GETOPT-COPY-ERROR`	Objects of this class cannot be copied.

4.6.4. GetOpt::parse()

Synopsis

Parses the list of parameters according to the option hash passed to the constructor. If a reference to a list is passed to this function, then all arguments parsed will be removed from the list, 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.

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

Prototype

hashGetOpt::parse(reference$list_ref)

hashGetOpt::parse(list$list)

Example

my hash $o = $getopt.parse(\$ARGV);
if (exists $o."_ERRORS_") {
   stderr.printf("%s\n", $o."_ERRORS_"[0]);
   exit(1);
}

Table 4.224. Arguments for GetOpt::parse()

Argument	Description
`list$list`	The entire command line to process (ex: $ARGV).
`reference$list_ref`	The reference should point to a list of arguments to process; any argument accepted by the object will be removed from the list.

Table 4.225. Return Values for GetOpt::parse()

Return Type	Description
`hash`	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 arguments passed in the list argument. The hash key `"_ERRORS_"` will contain any errors.

4.6.5. GetOpt::parse2()

Synopsis

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

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

Prototype

hashGetOpt::parse2(reference$list_ref)

hashGetOpt::parse2(list$list)

Example

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

Table 4.226. Arguments for GetOpt::parse2()

Argument	Description
`list$list`	The entire command line to process (ex: $ARGV).
`reference$list_ref`	The reference should point to a list of arguments to process; any argument accepted by the object will be removed from the list.

Table 4.227. Return Values for GetOpt::parse2()

Return Type	Description
`hash`	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 arguments passed in the list argument. If any errors are encountered processing the arguments, an appropriate exception will be thrown.

Table 4.228. Exceptions Thrown by GetOpt::parse2()

err	desc
`GETOPT-ERROR`	The description varies according to the error encountered.

Prev	Up	Next
4.5. TermIOS Class	Home	4.7. FtpClient Class