Parse options from command line arguments
GetOpt(grammar [, argumentArray])
- grammar A string describing the valid options for the program
- argumentArray A numerically keyed array containing arguments to be parsed
- return An array containing options, arguments and error info
put GetOpt("h,help v,verbose z") into tInfo if the number of elements in tInfo["errors"] > 0 then write "ERROR:" && tInfo["errors"] to stderr else if "z" is among the keys of tInfo["options"] then write "Z value is" & tInfo["options"]["z"] to stderr else if "help" is among the keys of tInfo["options"] then write "Usage: my-program [--help]" to stderr end if
Parse UNIX-like command line arguments, extracting options and their arguments.
The GetOpt function parses the command-line arguments. The optional parameter argumentArray is a numerically-keyed array containing the arguments to be parsed; if it is omitted, it is set to the commandArguments.
The grammar describes the possible options that GetOpt should understand. It is a string containing a series of option specifications, separated by spaces. Each option specification is a series of option names which should be treated as synonyms of each other, separated by commas. Single-character synonyms are treated as short (-h) options, and multi-character synonyms are treated as long (--help) options. Option names can't start with a - or contain =. The last synonym in each option specification is treated as the "proper" name of the option.
For example, "h,help" indicates that both -h and --help options are supported, and they are both properly known as the "help" option (the last indicated).
Each option specification can end with a =. This indicates that the option expects an argument. For example, with the grammar "-o,--output=", the option can be specified like:
-o file -ofile --output file --output=file
If a non-option argument is found in argumentArray, GetOpt stops parsing options and all subsequent arguments are returned as they are. The minus sign (-) is always treated as a non-option argument. The special double minus sign (--) option ends option parsing, but is otherwise ignored. This makes it possible to pass filenames on the command line that are named the same as options. For example, "-- --help" will treat --help as a normal argument, not an option.
Short options can be run together. For example, if grammar is h,help v,verbose, then -hv is treated as if both --help and --verbose were passed as options to the command.
If an option is specified more than once, only the last occurrence is reflected in the return value of GetOpt
The return value of GetOpt is an array with three keys:
- "options": an array where the keys are option names and the values are the arguments to those options.
- "arguments": a numerically-indexed array where the values are the non-option arguments
- "errors": a numerically-indexed array where the values are error messages from GetOpt's processing of the argumentArray.
Argument processing errors occur if:
- an option is found that wasn't in the grammar
- an option has an argument, but the grammar says it shouldn't
- an option doesn't have an argument, but the grammar says it should