File: README

package info (click to toggle)
shhopt 1.1.7-5
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, bullseye, sid
  • size: 140 kB
  • sloc: ansic: 351; makefile: 168
file content (158 lines) | stat: -rw-r--r-- 4,821 bytes parent folder | download | duplicates (6)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
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 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
      command line, 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 the dash 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 it by writing a
  function converting a string argument to a double (functions
  strToDouble and doubleFunc).


Portability
-----------

If your libc lacks strtoul, you will need to link with GNU's -liberty,
that may be found by anonymous ftp to ftp://ftp.gnu.org/pub/gnu/

The library has (more or less recently) been compiled and `tested' on
the following systems:

	IRIX Release 5.3 IP22
	GNU/Linux 2.4.17 with glibc 2.2.5
	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        shh@thathost.com
        Lofthusvn. 11 B         http://shh.thathost.com/
        N-0587 Oslo
        Norway


License
-------

This program is released under the Artistic License:

  http://www.opensource.org/licenses/artistic-license.html

Comments (even as simple as "I use your program") are very welcome.
If you insist on paying something, please donate some money to an
organization that strives to make the world a better place for
everyone.

I don't like bugs, so please help me removing them by reporting
whatever you find!