[thirdparty/util-linux.git] / hwclock / README.shhopt-1.1

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!
Commit	Line	Data
fd6b7a7f KZ	1	shhopt - library for parsing command line options.
	2	==================================================
	3
	4	This is a set of functions for parsing command line options. Both
	5	traditional one-character options, and GNU-style --long-options are
	6	supported.
	7
	8
	9	What separates this from traditional getopt?
	10	--------------------------------------------
	11
	12	This library does more of the parsing for you. You set up a special
	13	structure describing the names and types of the options you want your
	14	program to support. In the structure you also give addresses of
	15	variables to update or functions to call for the various
	16	options. By calling optParseOptions, all options in argv are parsed
	17	and removed from argv. What is left, are the non-optional arguments to
	18	your program.
	19
	20	The down-side of this, is that you won't be able to make a program
	21	where the position of the options between the non-options are
	22	significant.
	23
	24
	25	Usage
	26	-----
	27
	28	To see how to use this library, take a look at the sample program
	29	example.c.
	30
	31	A brief explanation:
	32
	33	To parse your command line, you need to create and initialize an array
	34	of optStruct's. Each element in the array describes a long and short
	35	version of an option and specifies what type of option it is and how
	36	to handle it.
	37
	38	The structure fields (see also shhopt.h):
	39
	40	`shortName' is the short option name without the leading '-'.
	41
	42	`longName' is the long option name without the leading "--".
	43
	44	`type' specifies what type of option this is. (Does it expect an
	45	argument? Is it a flag? If it takes an argument,what type should
	46	it be?)
	47
	48	`arg' is either a function to be called with the argument from
	49	the commandline, or a pointer to a location in which to store
	50	the value.
	51
	52	`flags' indicates whether `arg' points to a function or a storage
	53	location.
	54
	55	The different argument types:
	56
	57	`OPT_END' flags this as the last element in the options array.
	58
	59	`OPT_FLAG' indicates an option that takes no arguments. If `arg' is
	60	not a function pointer, the value of `arg' will be set to 1 if
	61	this flag is found on the command line.
	62
	63	`OPT_STRING' expects a string argument.
	64
65	`OPT_INT' expects an int argument.
66
67	`OPT_UINT' expects an unsigned int argument.
68
69	`OPT_LONG' expects a long argument.
70
71	`OPT_ULONG' expects an unsigned long argument.
72
73	The different flag types:
74
75	`OPT_CALLFUNC' indicates that `arg' is a function pointer. If this
76	is not given, `arg' is taken as a pointer to a variable.
77
78
79	Notes
80	-----
81
82	* A dash (`-') by itself is not taken as any kind of an option, as
83	several programs use this to indicate the special files stdin and
84	stdout. It is thus left as a normal argument to the program.
85
86	* Two dashes (`--') as an argument, is taken to mean that the rest of
87	the arguments should not be scanned for options. This simplifies
88	giving names of files that start with a dash.
89
90	* Short (one-character) options accept parameters in two ways, either
91	directly following the option in the same argv-entry, or in the next
92	argv-entry:
93
94	-sPARAMETER
95	-s PARAMETER
96
97	* Long options accept parameters in two ways:
98
99	--long-option=PARAMETER
100	--long-option PARAMETER
101
102	To follow the GNU-tradition, your program documentation should use
103	the first form.
104
105	* Several one-character options may be combined after a single
106	dash. If any of the options requires a parameter, the rest of the
107	string is taken as this parameter. If there is no "rest of the
108	string", the next argument is taken as the parameter.
109
110	* There is no support for floating point (double) arguments to
111	options. This is to avoid unnecessary linking with the math
112	library. See example.c for how to get around this by writing a
113	function converting a string argument to a double.
114
115
116	Portability
117	-----------
118
119	If your libc lacks strtoul, you will need to link with GNU's -liberty,
120	that may be found by anonymous ftp to prep.ai.mit.edu:/pub/gnu
121
122	The library has (more or less recently) been compiled and `tested' on
123	the following systems:
124
125	IRIX Release 5.3 IP22
126	Linux 1.2.9
127	SunOS Release 4.1.3_U1 (-liberty needed)
128	ULTRIX V4.4 (Rev. 69)
129
130	All compilations were done using GNU's gcc, and GNU's make.
131
132
133	Author
134	------
135
136	The program is written by
137
138	Sverre H. Huseby
139	Maridalsvn. 122, leil. 101
140	N-0461 Oslo
141	Norway
142
143	sverrehu@ifi.uio.no
144	http://www.ifi.uio.no/~sverrehu/
145
146	You can use and copy this for free. If you decide to use it, please do
147	me three small favours:
148
149	1. Tell me! (E-mail, postcard, letter, whatever. If you wish
150	to give me something, please send a bottle of your
151	favourite beer (making this BeerWare))
152	2. Let your friends and favourite download site have a copy!
153	(with all files intact, please..)
154	3. Report any bugs you find!
155