| 1 | .\" @(#)GetLongOpt.3 2.0 12/01/1993
|
|---|
| 2 | .TH GETLONGOPT 3 "12 January 1993" "" "C++ LIBRARY CLASSES"
|
|---|
| 3 | .UC 4
|
|---|
| 4 | .SH NAME
|
|---|
| 5 | GetLongOpt - C++ class for parsing command line and strings for options
|
|---|
| 6 | .SH SYNOPSIS
|
|---|
| 7 | .nf
|
|---|
| 8 | .ft B
|
|---|
| 9 | .ss 18
|
|---|
| 10 | #include <GetLongOpt.h>
|
|---|
| 11 |
|
|---|
| 12 | GetLongOpt::GetLongOpt(const char optmark = '-');
|
|---|
| 13 | int GetLongOpt::parse(int argc, char * const *argv);
|
|---|
| 14 | int GetLongOpt::parse(char * const str, char * const p);
|
|---|
| 15 | int GetLongOpt::enroll(const char * const opt, const OptType t,
|
|---|
| 16 | const char * const desc, const char * const val);
|
|---|
| 17 | const char * GetLongOpt::retrieve(const char * const opt) const;
|
|---|
| 18 | void GetLongOpt::usage(ostream &outfile = cout) const;
|
|---|
| 19 | void GetLongOpt::usage(const char *str);
|
|---|
| 20 | .ft
|
|---|
| 21 | .fi
|
|---|
| 22 | .ss
|
|---|
| 23 |
|
|---|
| 24 | .SH DESCRIPTION
|
|---|
| 25 | GetLongOpt is a C++ class for getting options from the command line
|
|---|
| 26 | and from strings. GetLongOpt supports long options. These options
|
|---|
| 27 | may be flags or require optional or mandatory values.
|
|---|
| 28 | If an option requires a value, then the value should be separated
|
|---|
| 29 | from the option either by whitespace or by a "=". Long options
|
|---|
| 30 | can be abbreviated. GetLongOpt can also be used to parse options given
|
|---|
| 31 | through environments.
|
|---|
| 32 |
|
|---|
| 33 | The constructor for GetLongOpt takes an optional argument: the option
|
|---|
| 34 | marker. If unspecified, this defaults to '-', the standard (?)
|
|---|
| 35 | Unix option marker. For example, a DOS addict may want to
|
|---|
| 36 | specify '/' for the option marker!
|
|---|
| 37 |
|
|---|
| 38 | .I GetLongOpt::enroll
|
|---|
| 39 | adds option specifications to its internal
|
|---|
| 40 | database. The first argument is the option sting. The second
|
|---|
| 41 | is an enum saying if the option is a flag (GetLongOpt::NoValue),
|
|---|
| 42 | if it requires a mandatory value (GetLongOpt::MandatoryValue) or
|
|---|
| 43 | if it takes an optional value (GetLongOpt::OptionalValue).
|
|---|
| 44 | The third argument is a string giving a brief description of
|
|---|
| 45 | the option. This description will be used by
|
|---|
| 46 | .I GetLongOpt::usage.
|
|---|
| 47 | GetLongOpt, for usage-printing, uses $val to represent values
|
|---|
| 48 | needed by the options. <$val> is a mandatory value and [$val]
|
|---|
| 49 | is an optional value. The final argument to
|
|---|
| 50 | .I GetLongOpt::enroll
|
|---|
| 51 | is the default string to be returned if the option is not
|
|---|
| 52 | specified. For flags (options with NoValue), use "" (empty
|
|---|
| 53 | string, or in fact any arbitrary string) for specifying TRUE
|
|---|
| 54 | and 0 (null pointer) to specify FALSE.
|
|---|
| 55 |
|
|---|
| 56 | .I GetLongOpt::usage
|
|---|
| 57 | is overloaded. If passed a string
|
|---|
| 58 | .I s,
|
|---|
| 59 | it sets the
|
|---|
| 60 | internal usage string to
|
|---|
| 61 | .I s.
|
|---|
| 62 | Otherwise it simply prints the
|
|---|
| 63 | command usage. The options and their
|
|---|
| 64 | descriptions (as specified during enroll) are printed in the
|
|---|
| 65 | order they are enrolled.
|
|---|
| 66 |
|
|---|
| 67 | .I GetLongOpt::parse
|
|---|
| 68 | is also overloaded. It can either parse a string of
|
|---|
| 69 | options (typically given from the environment), or it can parse
|
|---|
| 70 | the command line args (argc, argv). In either case a return
|
|---|
| 71 | value < 1 represents a parse error. Appropriate error messages
|
|---|
| 72 | are printed when errors are seen. GetLongOpt::parse, in its first
|
|---|
| 73 | form, takes two strings: the first one is the string to be
|
|---|
| 74 | parsed and the second one is a string to be prefixed to the
|
|---|
| 75 | parse errors. In its second form,
|
|---|
| 76 | .I GetLongOpt::parse
|
|---|
| 77 | takes in argc and argv and returns the
|
|---|
| 78 | the optind (see getopt(3)) if parsing is successful.
|
|---|
| 79 | Successful parsing, in either form of
|
|---|
| 80 | .I GetLongOpt::parse,
|
|---|
| 81 | updates the values of the options within the internal database.
|
|---|
| 82 |
|
|---|
| 83 | The values of the options that are enrolled in the database
|
|---|
| 84 | can be retrieved using
|
|---|
| 85 | .I GetLongOpt::retrieve.
|
|---|
| 86 | This returns a string
|
|---|
| 87 | and this string should be converted to whatever type you want.
|
|---|
| 88 | See atoi(3), atof(3), atol(3) etc. I suppose you would do a
|
|---|
| 89 | .I GetLongOpt::parse
|
|---|
| 90 | before
|
|---|
| 91 | retrieving. Otherwise all you would get are the default values
|
|---|
| 92 | you gave while enrolling!
|
|---|
| 93 | Ambiguities while retrieving (may happen when options are
|
|---|
| 94 | abbreviated) are resolved by taking the matching option that
|
|---|
| 95 | was enrolled last.
|
|---|
| 96 |
|
|---|
| 97 | If you try to retrieve something you did not enroll, you will
|
|---|
| 98 | get a warning message. This means that you probably had made
|
|---|
| 99 | a typo somewhere while enrolling or retrieving.
|
|---|
| 100 |
|
|---|
| 101 | .SH BUGS
|
|---|
| 102 | They should be there well-hidden. If you spot one report it.
|
|---|
| 103 |
|
|---|
| 104 | .SH "SEE ALSO"
|
|---|
| 105 | getopt(3),
|
|---|
| 106 | getopts(1),
|
|---|
| 107 | atoi(3), atof(3), atol(3).
|
|---|
| 108 |
|
|---|
| 109 | .SH AUTHOR
|
|---|
| 110 | .nf
|
|---|
| 111 | S Manoharan
|
|---|
| 112 | Advanced Computer Research Institute
|
|---|
| 113 | 1 Boulevard Marius Vivier-Merle
|
|---|
| 114 | 69443 Lyon Cedex 03 France
|
|---|
| 115 |
|
|---|
| 116 | mano@acri.fr
|
|---|
| 117 | .fi
|
|---|
| 118 |
|
|---|
| 119 | .\" end of man page
|
|---|
