| File xoptions.icn |
###########################################################################
File: xoptions.icn
Subject: Procedure to get command-line options
Based on the options.icn by
Robert J. Alexander and Gregg M. Townsend and Don Ward
Modified: Bruce Rennie Rewrite and extensions
Date: August 29, 2020
###########################################################################
This file is in the public domain.
###########################################################################
xoptions(arg, optstring, errproc, finishoption[]) removes command options
from the argument list of an Icon main procedure, returning a table of
option values.
###########################################################################
xoptions(arg, optstring, errproc, finishoption[]) -- Get command line options.
This procedure separates and interprets command line options included in
the main program argument list. Option names and values are removed
from the argument list and returned in a table. Allows for options to have
sub-options and allows for options/sub-options to be stored in separate files
and called by referencing these files by use of "@".
This procedure will now handle the POSIX conventions, the GNU long option
conventions and the various conventions that were originally in this procedure,
including non-alphanumeric characters as options.
Additionally, Icon/Unicon conventions of using "-x" as well as "--" to end
the processing of options from the command line by allowing an additional list
of values to do this. A addition allows for a series of values to be stored
against an option till "--" or other specified values are encountered.
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. In addition
the "=" can be used as the separator between the option and the value (no
space separation allowed) as in "-F=file.txt".
Options may be freely interspersed with non-option arguments. An argument
of a single "-" is treated as a non-option. The special argument "--" or other
specified values will terminate the option processing. Non-option arguments
are returned in the original argument list for interpretation by the caller,
including those collected from any specified option file (as described in the
next paragraph).
An argument of the form @filename (a "@" immediately followed by a file name)
causes xoptions() 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). filename can have a
fully specified path or a relative specified path or a local directory
specified path.
The parameters of xoptions(arg, optstring, errproc, finishoption[]) are:
arg the argument list as passed to the main procedure. This is the
list that is passed into the program from the operating system
being used.
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%* (one or more alphanumeric or _)
--name%* (one or more alphanumeric or _ or -)
name%* (one or more characters not flags and each
character is treated as a separate single
character option)
=name%* (one or more alphanumeric or _)
where
- introduces the option
-- introduces the option where the option name can
contain "-"
= introduces the option where command line option
can be either --name or -name
name is either a string of alphanumerics (any of a-z,
A-Z, 0-9, and _)
or any single printable character. The "-" is
allowed when prefixed by "--".
% 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
$ Optional value - anything
() Defines a set of comma separated sub-option
option/pairs. The option string definition
use the above flag characters "!", ":",
"+", ".", "$" with an optional "*". The
value (if supplied) is separated by "=".
< all values following this option up to any
value found in finishoption are to be
collected into a list for this option.
any "*" following this will be ignored.
* optional and indicates that the option can occur
multiple times in the command options and must
follow the % specifier, if used.
For all options that do not allow multiple occurrences,
the consequence of multiple appearances of that option
is that the last occurrence will overwrite any previous
occurrence.
The leading "-" may be omitted for a single-characteroption.
The "!" flag may be omitted except when needed to terminate
a multi-character name. In the case of a single "-" as the
start of the option specifier, any following "-" will
terminate the 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 or digit 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, xoptions() 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 and the program will abort.
finishoption is a list of options that terminate the processing of options.
This allows the proceeding options to be passed to another
program. By default this is "--". An example of other values
being used is the "-x" used in the icont compiler to pass
all following parameters to the iconx interpreter.
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 so testing for the occurrence of that
specific parameter can use the \ operator to check if it was actually specified
on the command line.
Upon return, the option arguments are removed from arg, leaving only the
non-option arguments.
Options with embedded "-"
Options may begin with "--" and, if they do, may contain "-" characters.
So options like --dry-run will be parsed correctly and will result in an
entry in the options table with a key of "-dry-run" (note the leading minus
in the key). All such options must be terminated by a space or one of
allowable specifier characters described above. The handling of these options
allows any number of "-" to be in the option name after the initial
alphanumeric or "_" character. The normal expectation is that the option name
will have a single "-" between each group of alphanumeric character grouping.
However, if you require multiple sequential "-" in the option name, this is
allowed.
For all options that have an associated value (optional or required), there
are three usable alternatives (as per POSIX standards).
For single character options, the value can follow immediately, or it can be
space separated or have a an "=" between the option and the value.
Using -l as an example, we can specify the command line as
-lone
-l one
-l=one
For multi-character options, the value is either space separated or have
an "=" between the option and the value.
Using -geometry as an example, we can specify the command line as
-geometry "240:240"
-geometry="240:240"
For options that have sub-options the following has been added (as per the
POSIX standards). The options that have sub-options have the sub-options as a
comma separated list of option/value pairs. Those sub-options that have values use
a "=" between sub-option and the associated value. To define the sub-options,
place these in parentheses.
An example of defining the option string.
-o(h!file:*sfr)
The command line form could be as follows
-o h,file=filename.ext,file="another file.ext",r
The value returned for an option that has sub-options is a table of key/values
pairs, the default is &null and for keys that have no required values, the value
returned is 1.
A similar extension is available in the @ file. You can now write
-time 45
or
-time=45
instead of the two lines previously required as in
-time
45
Treating options specified as --opt and -opt as the same option.
To remove the leading minus from such keys, make the first character
of the specified option in the option string an "=" character: then, a
supplied argument of either --opt or -opt would result in a key of "opt" in
the table. When the first character is an equals character, the procedure
ensures that only one of "--opt" or "-opt" may be specified in the option
way to allow (for example) both --run and -run as options is to miss out
string. The only the leading equals and to treat option["-run"] and option["run"]
separately in the calling program.
e.g.
"-bish-bash-bosh--bash" gives to four different options, which are
command line option table
------------------------------|-----------------------------
-bish | bish
-bash | bash
-bosh | bosh
--bash | -bash
"--bish-bash-bosh--bash" recognises a single command line option
command line option table
------------------------------|-----------------------------
--bish-bash-bosh--bash | -bish-bash-bosh--bash
"=bish-bash-bosh--bash" recognises two command line options that have the
same meaning
command line option table
------------------------------|-----------------------------
-bish-bash-bosh--bash | bish-bash-bosh--bash
--bish-bash-bosh--bash | bish-bash-bosh--bash
Specify short form of option names
As per GNU extensions, the option names can be shortened as long as these
shortened forms are able to be disambiguated from all other valid option
names. An example of this would be two options such as "-si" and "-silent".
In this case, "-s" would NOT be a valid short form as it could not be
disambiguated between either of the options. "-si" would be available as this
is the full option name and "-sil" and any longer prefix of "-silent" would
also be valid.
The command line could use the full names as:
"-si -silent"
or it could be specified as
"-si -sil"
as being equivalent command line forms.
###########################################################################
This file is part of the (main) package.
Source code.| Details |
| Procedures: |
convert_to_list(str, suboptionsep)
PD: : convert_to_list(str, suboptionsep) - the sub-string elements that are separated : by the value found in suboptionsep into a list of strings that are option/value : pairs and prefix each sub-string with the "-". : : This procedure is helper procedure to allow processing of sub-options as if : they were an argument list. :
process_command_option(args, option, opttable, maptable, finishoption, errproc, nosuboption)
PD: : process_command_option(args, option, opttable, maptable, finishoption, errproc, nosuboption) : :
process_option_string(optstring, flags, nosuboption)
PD: : process_option_string(optstring, flags, nosuboption) : :
xoptions(arg, optstring, errproc, finishoption)
PD: : xoptions(arg, optstring, errproc, finishoption[]) : :@param arg list of strings which represent the arguments given :@ to the calling program :@param optstring string representing the allowable options and sub-options :@ and any required values for those options/sub-options :@errproc error procedure to be used when an error is found in :@ the supplied arg list :@finishoption[] list of applicable values that can terminate the :@ processing of options and values :@returns table containing option/values found in the arg list :@updates arg the value of arg is updated by the removal the found :@ options/values and by pointer semantics, the value in :@ calling procedure :