NAME
	getopts - get options from a string

SYNOPSIS
	mapping getopts(string switches, string data)

DEFINITION
	A switch cluster is a set of one or more character, prepended with the
	character '-'. For example, '-a' , '-np' and '-usljh' are switch
	clusters, while 'foo', 'bar' and 'gnu' are not.

DESCRIPTION
	This function processes single character switches with switch
	clustering. The string 'switches' contains all the switches you are
	asking about, and the string 'data' will be checked for the switches.
	If a switch in the 'switch' string is followed by a ':', it will take
	an argument.

	The switches are collected in a mapping, which is then returned. The
	switches are the indices in this mapping and the arguments are the
	values, or 1 if no value. Switches that take an argument do not care
	if there is a space in between the switch and the argument; thus such
	switches must be last in a switch cluster. A problem is then if the
	switch is followed by another switch cluster; the switch is NOT set in
	this case.

	Whatever isn't a switch cluster nor an argument to a switch is
	collected with the special index "$REST". If nothing such is found,
	$REST is set to an empty string, "".

USAGE
	This function, getopts, can be used as an easy and convenient way of
	detecting options to a wizard command. 

EXAMPLES
	Switches: "a:bc"
	Data:     "-bca 12"
	Result:   ([ a : 12,  b : 1,  c : 1,  "$REST" : "" ])

	Switches: "abcdefghijkl"
	Data:     "-a -b -cde fgh -lkji"
	Result:   ([ a : 1,  b : 1,  c : 1,  d : 1, 
		     e : 1,  i : 1,  j : 1,  k : 1,  l : 1,
		     "$REST" : "fgh" ])

	Switches: "n:l:u:f:abcd"
	Data:     "-n brom foo -u12 -l 4 -afbcd -c"
	Result:   ([ a : 1,  c : 1,   f : "bcd",
		     l : 5,  u : 12,  n : "brom",
		     "$REST" : "foo" ])

	Switches: "a:bc"
	Data:     "-a -bc"
	Result:   ([ b : 1,  c : 1,  $REST : "" ])

NOTE
	In order to keep the game a fantasy illusion for the mortal players,
	this function should not be used to parse player input.

BUGS
	None known. Some of the bahaviour (notably what happens to a switch
	demanding an argument last in a cluster, directly followed by another
	switch cluster) are due to design decisions and could perhaps been done
	in some other ways. Also, a single '-' is ignored.

Help topics available:

_get_all_obj	_next_obj	_prev_obj	abs	expand_file_name
frnd	get_objects	getopts	implode_nicely	itoa
line_break	load_object	mapping_rusage	query_ip_name	set_light
sgn	short_date	typep