$getopt(<optopt-var> <optarg-var> <option-list> <argument-list>)

• The <option-list> argument is a dword which is different from most function arguments.
• This function should be called as the expression of a WHILE command.
• If the <optopt-var> argument is omitted the empty string is returned.
• If the <optarg-var> argument is omitted the empty string is returned.
• If the <option-list> argument is omitted the empty string is returned.
• The <optopt-var> argument is taken as the name of a variable in which to put the current option being parsed.
• The <optarg-var> argument is taken as the name of a variable in which to put the current argument being parsed.
• The <option-list> argument is taken as a list of arguments that are to be parsed from <argument-list>.
  Each character in <option-list> permits an option by that character to be parsed.
  Each character may be followed by either a single colon which specifies that the option must always be followed by an argument, or a double colon, which specifies that the option may or may not be followed by an argument.
• The <argument-list> argument is taken to be word list of dwords, which means double quoted words are supported, and the double quotes are removed.
• The <argument-list> argument is taken as an argument list, perhaps to an alias, that are to be parsed.
  It is fully parsed the “first time” that $getopt() is called.
• Each and every time any of the arguments to the getopt() function change between one call and the next,
  it is considered the “first time” that the $getopt() function has been called.
• The return value of the function shall be an indicator of the “next” option found in <argument-list>.
  The “first time” that $getopt() is called, the first option in <argument-list> is returned.
  The second time that $getopt() is called, the second option in <argument-list> is returned, and so on.
• Five things can be returned each call to $getopt().
  • The name of an option that does not take an argument:
    $<optopt-var> contains the name of the option.
    $<optarg-var> contains the empty string.
  • The name of an option that takes an argument:
    $<optopt-var> contains the name of the option.
    $<optarg-var> contains the argument to the option.
    
  • A hyphen ('-') indicating an option that takes an argument and was not provided with one:
    $<optopt-var> contains the name of the option
    $<optarg-var> contains the empty string.
  • A bang ('!') indicating an option that was not one of the options listed in <option-list>:
    $<optopt-var> contains the name of the string
    $<optarg-var> contains the empty string.
  • An empty string indicates processing is complete or internal error:
    $<optopt-var> is empty.
    $<optarg-var> contains the remaining non-option args.

Useful when you want an alias to accept option flags and you need a way to parse them easily. See the example section for particulars.

See technical specification for return values.

alias myalias {
  while (option = getopt(optopt optarg "ab:c:" $*)) {
    switch ($option) {
      (a) {echo * option "$optopt" used}
      (b) {echo * option "$optopt" used - $optarg}
      (c) {echo * option "$optopt" used - $optarg}
      (!) {echo * option "$optopt" is an invalid option}
      (-) {echo * option "$optopt" is missing an argument}
    }
  }
  echo * remaining args: $optarg
}