MPDGETOPT(3)

NAME
mpdgetopt - parse command arguments

SYNOPSIS
import MPDgetopt
do c := getopt(optstring) != EOF -> process option c od

DESCRIPTION

MPDgetopt provides a means for an MPD program to parse command line arguments in accordance with the standard Unix conventions; it is analogous to, and based on, getopt(3) for C programs. MPDgetopt is a global containing one procedure, getopt, and variables that control its behavior or return additional information.

Getopt interprets command arguments in accordance with the standard Unix conventions: option arguments are introduced by "-" followed by a key character; an argument value follows certain keys. Multiple keys can be combined, as in "-ab", if they do not require arguments. A non-option argument terminates the processing of options, as does the special argument "--".

Option interpretation is controlled by the parameter optstring, which specifies the characters that designate legal options and indicates which ones require associated values. The call getopt("ab") specifies that the command line should contain only the options "-a" and "-b". If a letter in optstring is followed by a colon, the option is expected to have an argument. The argument may or may not be separated by whitespace from the option letter. For example, getopt("w:") accepts either "-w 80" or "-w80".

Each call to getopt returns the key of the next command line argument; this key must match a letter in optstring. If the option accepts an argument, the string variable optarg is set to the argument value. Predefined conversion functions such as int, char, etc. can then be applied to optarg. The constant optMAXLEN defines the length of the longest string that getopt can handle; extra characters are truncated silently.

Getopt places in the variable optind the index of the next command line argument to be processed; optind is automatically initialized to 1 before the first call to getopt.

When all options have been processed, and only non-option arguments remain, getopt returns optEOF. The remaining arguments can be retrieved using the predefined function getarg, beginning with argument number optind.

DIAGNOSTICS

Getopt prints an error message on stderr and returns a question mark (′?′) when it encounters a command line argument not matched by optstring. Setting the variable opterr to false disables this error message.

NOTES

The following notes describe MPDgetopt's behavior in a few interesting or special cases; this behavior is consistent with getopt(3).

A ′-′ by itself is treated as a non-option argument. By convention, most programs interpret this as specifying the use of stdin or stdout, depending on context, in place of a named file.

If optstring is "a:" and the command line arguments are "-a -x", then "-x" is treated as the argument associated with the "-a".

Duplicate command line options are allowed; it is up to user to deal with them appropriately.

An option ``letter'' can be a letter, number, or almost any special character. Like getopt(3), MPDgetopt disallows a colon as an option letter.

EXAMPLE

The following code fragment shows how to use MPDgetopt to process a command that takes the options ′a′, ′f′, and ′w′ where ′f′ is followed by a file name and ′w′ is followed by an integer.

resource main()

	import MPDgetopt
	var ch: char

	# command line arguments
	var aflg := 0
	var filename: string[optMAXLEN] := "out"
	var width := 80

	do (ch := getopt("abf:w:")) != optEOF ->
		if ch = ′a′ ->
			aflg++
		[] ch = ′f′ ->
			filename := optarg
		[] ch = ′w′ ->
			width := int(optarg)
		[] else ->
			stop(1)
		fi
	od

	write("-a", aflg)
	write("-f", filename)
	write("-w", width)

	fa k := optind to numargs() ->
		var xx: string[40]
		getarg(k,xx)
		write("normal argument", k, "is", xx)
	af

end

SEE ALSO
getopt(3)

CAVEATS

Changing the value of the variable optind may lead to unexpected behavior.

Getopt, like the predefined functions numargs and getarg, is valid only on the main virtual machine.