# $EPIC: getopt,v 1.4 2003/04/19 00:36:02 crazyed Exp $
Synopsis:
   $getopt(<optopt-var> <optarg-var> <option-list> <argument-list>)

Technical:
   * 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 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.

Practical:
   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.

Returns:
   See technical specification for return values.

Examples:
   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
   }

See also:
    WHILE(5); SWITCH(5)