156 lines
4.6 KiB
Groff
156 lines
4.6 KiB
Groff
shhopt - library for parsing command line options.
|
|
==================================================
|
|
|
|
This is a set of functions for parsing command line options. Both
|
|
traditional one-character options, and GNU-style --long-options are
|
|
supported.
|
|
|
|
|
|
What separates this from traditional getopt?
|
|
--------------------------------------------
|
|
|
|
This library does more of the parsing for you. You set up a special
|
|
structure describing the names and types of the options you want your
|
|
program to support. In the structure you also give addresses of
|
|
variables to update or functions to call for the various
|
|
options. By calling optParseOptions, all options in argv are parsed
|
|
and removed from argv. What is left, are the non-optional arguments to
|
|
your program.
|
|
|
|
The down-side of this, is that you won't be able to make a program
|
|
where the position of the options between the non-options are
|
|
significant.
|
|
|
|
|
|
Usage
|
|
-----
|
|
|
|
To see how to use this library, take a look at the sample program
|
|
example.c.
|
|
|
|
A brief explanation:
|
|
|
|
To parse your command line, you need to create and initialize an array
|
|
of optStruct's. Each element in the array describes a long and short
|
|
version of an option and specifies what type of option it is and how
|
|
to handle it.
|
|
|
|
The structure fields (see also shhopt.h):
|
|
|
|
`shortName' is the short option name without the leading '-'.
|
|
|
|
`longName' is the long option name without the leading "--".
|
|
|
|
`type' specifies what type of option this is. (Does it expect an
|
|
argument? Is it a flag? If it takes an argument,what type should
|
|
it be?)
|
|
|
|
`arg' is either a function to be called with the argument from
|
|
the commandline, or a pointer to a location in which to store
|
|
the value.
|
|
|
|
`flags' indicates whether `arg' points to a function or a storage
|
|
location.
|
|
|
|
The different argument types:
|
|
|
|
`OPT_END' flags this as the last element in the options array.
|
|
|
|
`OPT_FLAG' indicates an option that takes no arguments. If `arg' is
|
|
not a function pointer, the value of `arg' will be set to 1 if
|
|
this flag is found on the command line.
|
|
|
|
`OPT_STRING' expects a string argument.
|
|
|
|
`OPT_INT' expects an int argument.
|
|
|
|
`OPT_UINT' expects an unsigned int argument.
|
|
|
|
`OPT_LONG' expects a long argument.
|
|
|
|
`OPT_ULONG' expects an unsigned long argument.
|
|
|
|
The different flag types:
|
|
|
|
`OPT_CALLFUNC' indicates that `arg' is a function pointer. If this
|
|
is not given, `arg' is taken as a pointer to a variable.
|
|
|
|
|
|
Notes
|
|
-----
|
|
|
|
* A dash (`-') by itself is not taken as any kind of an option, as
|
|
several programs use this to indicate the special files stdin and
|
|
stdout. It is thus left as a normal argument to the program.
|
|
|
|
* Two dashes (`--') as an argument, is taken to mean that the rest of
|
|
the arguments should not be scanned for options. This simplifies
|
|
giving names of files that start with a dash.
|
|
|
|
* Short (one-character) options accept parameters in two ways, either
|
|
directly following the option in the same argv-entry, or in the next
|
|
argv-entry:
|
|
|
|
-sPARAMETER
|
|
-s PARAMETER
|
|
|
|
* Long options accept parameters in two ways:
|
|
|
|
--long-option=PARAMETER
|
|
--long-option PARAMETER
|
|
|
|
To follow the GNU-tradition, your program documentation should use
|
|
the first form.
|
|
|
|
* Several one-character options may be combined after a single
|
|
dash. If any of the options requires a parameter, the rest of the
|
|
string is taken as this parameter. If there is no "rest of the
|
|
string", the next argument is taken as the parameter.
|
|
|
|
* There is no support for floating point (double) arguments to
|
|
options. This is to avoid unnecessary linking with the math
|
|
library. See example.c for how to get around this by writing a
|
|
function converting a string argument to a double.
|
|
|
|
|
|
Portability
|
|
-----------
|
|
|
|
If your libc lacks strtoul, you will need to link with GNU's -liberty,
|
|
that may be found by anonymous ftp to prep.ai.mit.edu:/pub/gnu
|
|
|
|
The library has (more or less recently) been compiled and `tested' on
|
|
the following systems:
|
|
|
|
IRIX Release 5.3 IP22
|
|
Linux 1.2.9
|
|
SunOS Release 4.1.3_U1 (-liberty needed)
|
|
ULTRIX V4.4 (Rev. 69)
|
|
|
|
All compilations were done using GNU's gcc, and GNU's make.
|
|
|
|
|
|
Author
|
|
------
|
|
|
|
The program is written by
|
|
|
|
Sverre H. Huseby
|
|
Maridalsvn. 122, leil. 101
|
|
N-0461 Oslo
|
|
Norway
|
|
|
|
sverrehu@ifi.uio.no
|
|
http://www.ifi.uio.no/~sverrehu/
|
|
|
|
You can use and copy this for free. If you decide to use it, please do
|
|
me three small favours:
|
|
|
|
1. Tell me! (E-mail, postcard, letter, whatever. If you wish
|
|
to give me something, please send a bottle of your
|
|
favourite beer (making this BeerWare))
|
|
2. Let your friends and favourite download site have a copy!
|
|
(with all files intact, please..)
|
|
3. Report any bugs you find!
|
|
|