link options
May 5, 2000; Robert J. Alexander and Gregg M. Townsend
This file is in the public domain.
options(arg, optstring,errproc) removes command options from the
argument list of an Icon main procedure, returning a table of
option values.
____________________________________________________________
options(arg,optstring,errproc) -- Get command line options.
This procedure separates and interprets command options included in
the main program argument list. Option names and values are removed
from the argument list and returned in a table.
On the command line, options are introduced by a "-" character. An
option name is either a single printable character, as in "-n" or "-?",
or a string of letters, numbers, and underscores, as in "-geometry".
Valueless single-character options may appear in combination, for
example as "-qtv".
Some options require values. Generally, the option name is one
argument and the value appears as the next argument, for example
"-F file.txt". However, with a single-character argument name
(as in that example), the value may be concatenated: "-Ffile.txt"
is accepted as equivalent.
Options may be freely interspersed with non-option arguments.
An argument of "-" is treated as a non-option. The special argument
"--" terminates option processing. Non-option arguments are returned
in the original argument list for interpretation by the caller.
An argument of the form @filename (a "@" immediately followed
by a file name) causes options() to replace that argument with
arguments retrieved from the file "filename". Each line of the file
is taken as a separate argument, exactly as it appears in the file.
Arguments beginning with - are processed as options, and those
starting with @ are processed as nested argument files. An argument
of "--" causes all remaining arguments IN THAT FILE ONLY to be
treated as non-options (including @filename arguments).
The parameters of options(arg,optstring,errproc) are:
arg the argument list as passed to the main procedure.
optstring a string specifying the allowable options. This is
a concatenation, with optional spaces between, of
one or more option specs of the form
-name%
where
- introduces the option
name is either a string of alphanumerics
(any of a-z, A-Z, 0-9, and _)
or any single printable character
% is one of the following flag characters:
! No value is required or allowed
: A string value is required
+ An integer value is required
. A real value is required
The leading "-" may be omitted for a single-character
option. The "!" flag may be omitted except when
needed to terminate a multi-character name.
Thus, the following optstrings are equivalent:
"-n+ -t -v -q -F: -geometry: -silent"
"n+tvqF:-geometry:-silent"
"-silent!n+tvqF:-geometry:"
If "optstring" is omitted any single letter is
assumed to be valid and require no data.
errproc a procedure which will be called if an error is
is detected in the command line options. The
procedure is called with one argument: a string
describing the error that occurred. After errproc()
is called, options() immediately returns the outcome
of errproc(), without processing further arguments.
Already processed arguments will have been removed
from "arg". If "errproc" is omitted, stop() is
called if an error is detected.
A table is returned containing the options that were specified.
The keys are the specified option names. The assigned values are the
data values following the options converted to the specified type.
A value of 1 is stored for options that accept no values.
The table's default value is &null.
Upon return, the option arguments are removed from arg, leaving
only the non-option arguments.