options.icn: Procedure to get command-line options

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.

Source code | Program Library Page | Icon Home Page