/usr/share/doc/libbobcat3-dev/man/arg.3.html is in libbobcat-dev 3.19.01-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 | <html><head>
<title>FBB::Arg</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::Arg</h1>
<h2>libbobcat-dev_3.19.01-x.tar.gz</h2>
<h2>2005-2013</h2>
<html><head>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1></h1>
<html><head>
<title>FBB::Arg(3bobcat)</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::Arg(3bobcat)</h1>
<h2>libbobcat-dev_3.19.01-x.tar.gz Command Line Arguments</h2>
<h2>2005-2013</h2>
<p>
<h2>NAME</h2>FBB::Arg - A singleton class interfacing command line arguments
<p>
<h2>SYNOPSIS</h2>
<strong>#include <bobcat/arg></strong><br>
Linking option: <em>-lbobcat</em>
<p>
<h2>DESCRIPTION</h2>
Singleton class (see Gamma <em>et al.</em>, 1995) built around <strong>getopt()</strong>(3)
and <strong>getopt_long()</strong>(3). The class handles short- and long command-line
options,
<p>
<h2>NAMESPACE</h2>
<strong>FBB</strong><br>
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace <strong>FBB</strong>.
<p>
<h2>INHERITS FROM</h2>
-
<p>
<h2>ENUMERATION</h2>
<p>
The <strong>FBB::Arg::Type</strong> enumeration is defined by the <strong>FBB::Arg</strong>
class. It has the following values intended for public use: <strong>None, Required,
Optional</strong>. These values are used when constructing objects of the nested class
<strong>FBB::Arg::LongOption</strong>, see below.
<p>
<h2>CONSTRUCTORS</h2>
Since the class is a <em>Singleton</em>, no public constructors are
available. Instead, static members are offered to initialize and access the
single <strong>FBB::Arg</strong> object. See below.
<p>
<h2>STATIC MEMBERS</h2>
<ul>
<li> <strong>FBB::Arg &initialize(char const *optstring, int argc, char **argv)</strong>:<br>
Initializes the <strong>FBB::Arg</strong> singleton. Must be called only once.
Throws an <strong>FBB::Exception</strong> exception if called repeatedly or if called with
<em>argv</em> not containing a defined option (which is shown by the
<strong>FBB::Exception</strong>'s <em>what()</em> member). Returns a reference to the singleton
object, allowing code initializing <strong>Arg</strong> to use the initialized object
immediately.
<li> <strong>FBB::Arg &initialize(char const *optstring,
LongOption const * const begin,
LongOption const * const end,
int argc, char **argv)</strong>:<br>
Initializes the <strong>FBB::Arg</strong> singleton. Accepts two iterators of an
array of <strong>Arg::LongOption</strong> objects, holding long-options. Must be
called only once. Throws an <strong>FBB::Exception</strong> exception if called
repeatedly or if called with <em>argv</em> not containing a defined option
(which is shown by the <strong>FBB::Exception</strong>'s <em>what()</em> member). See the
description of <strong>Arg::LongOption</strong> below. Returns a reference to the
singleton object, allowing code initializing <strong>Arg</strong> to use the
initialized object immediately.
<p>
<em>optstring</em> should consist of letters, possibly postfixed by:
<ul>
<li> a colon (<em>:</em>), indicating that the option has a required
argument;
<li> a double colon (<em>::</em>), indicating that the option itself
has an optional argument (in that case, the option's value
will be empty, unless specified).
</ul>
<p>
<li> <strong>FBB::Arg &instance()</strong>:<br>
Returns the instance of the <strong>Arg</strong> object, available after calling one
of the <strong>Arg::initialize()</strong> members. If called before
initialization, an <em>FBB::Exception</em> exception is thrown.
</ul>
<p>
<h2>OVERLOADED OPERATOR</h2>
<p>
<ul>
<li> <strong>char const *operator[](size_t idx) const</strong>:<br>
Returns <em>argument[idx]</em>, after having removed all specified options.
0 is returned if no <em>arg[x]</em> is available. The program name
(<em>argv[0]</em>) is NOT counted here: index 0 refers to the first
ARGUMENT, e.g., the program's <em>argv[1]</em>.
</ul>
<p>
<h2>NON-STATIC MEMBER FUNCTIONS</h2>
<ul>
<li> <strong>char const **argPointers()</strong>:<br>
Returns <em>argv</em>-like set of pointers to all remaining arguments. The
last element is guaranteed to be a 0-pointer. The first <em>nArg()</em>
elements point to the respective <strong>C</strong>-string values of the arguments.
<li> <strong>std::string const &basename() const</strong>:<br>
Returns the program's basename.
<li> <strong>size_t beyondDashes() const</strong>:<br>
Returns the index of the first argument after a <em>--</em>
argument or <em>nArgs()</em> if no <em>--</em> argument was encountered.<br>
A <em>--</em> argument ends <em>Arg</em>'s argument processing, and all arguments
beyond the first <em>--</em> argument are kept `as is'. The
<em>beyondDashes</em> member returns the index of the first argument beyond
the <em>--</em> argument, which itself is removed from the remaining set of
arguments.
<li> <strong>size_t nArgs() const</strong>:<br>
Returns the number of arguments left after option-removal. The
program name <strong>argv[0]</strong> is NOT counted here.
<li> <strong>size_t nLongOptions() const</strong>:<br>
Returns the number of long options for which no short option synonym
exist. If long options are multiply specified, then each specification
is counted.
<li> <strong>size_t nOptions() const</strong>:<br>
Returns the number of specified single character options. If short
options have long option synonyms, then these long option synonyms are
counted as if they were specified as single character options. If
single character options (or their long option synonyms) are multiply
specified, then each specification is counted.
<li> <strong>size_t option(int option) const</strong>:<br>
The number of times `option' (or its long option synonym, if defined)
was specified is returned.
<li> <strong>size_t option(std::string const &options) const</strong>:<br>
The number of times one of the options specified in the `option'
argument (or their long option synonyms) were present is returned.
<li> <strong>size_t option(string *value, int option) const</strong>:<br>
Returns the number of times the provided option (or its long option
synonym) was present. If the return value is non-zero then the value
of the first occurrence of this option is stored in <em>*value</em>, which
is left untouched if `option' was not present. 0 may be specified for
<strong>value</strong> if the option does not have a value or if the value should
not be stored.
<li> <strong>size_t option(size_t idx, string *value, int option) const</strong>:<br>
Returns the number of times the provided option (or its long option
synonym) was present. If the return value is non-zero then the value
of the <em>idx</em>th occurrence (0-based offset) of this option is stored
in <em>*value</em>, which is left untouched if `option' was not present or
if <em>idx</em> is or exceeds the number of specifications of the provided
option. 0 may be specified for <strong>value</strong> if the option does not have a
value or if the value should not be stored.
<li> <strong>size_t option(size_t *idx, string *value, int option) const</strong>:<br>
Returns the number of times the provided option (or its long option
synonym) was present. If the return value is non-zero then the offset
(within the series of <em>option</em> specifications) of the first option
having a non-empty option value is returned in <em>*idx</em>, while its
option value is stored in <em>*value</em>. Both <em>*value</em> and <em>*idx</em> are
left untouched if `option' was not present. 0 may be specified for
<strong>value</strong> if the option does not have a value or if the value should
not be stored.
<li> <strong>size_t option(string *value, char const *longOption) const</strong>:<br>
Returns the number of times the specified long option (not having a
single-character synonym) was present. Its value is then stored in
<em>*value</em>, which is left untouched if the long option was not
present. 0 may be specified for <strong>value</strong> if the option does not have
a value or if the value should not be stored.
<li> <strong>size_t option(size_t idx, string *value,
char const * longOption) const</strong>:<br>
Returns the number of times the provided long option (not having a
single-character synonym) was present. If the return value is non-zero
then the value of the <em>idx</em>th occurrence (0-based offset) of this
long option is stored in <em>*value</em>, which is left untouched if the
long option was not present or if <em>idx</em> is or exceeds the number of
specifications of the provided long option. 0 may be specified for
<strong>value</strong> if the long option does not have a value or if the value
should not be stored.
<li> <strong>size_t option(size_t *idx, string *value, int longOption) const</strong>:<br>
Returns the number of times the provided long option (not having a
single-character synonym) was present. If the return value is non-zero
then the offset (within the series of this long option specifications)
of the first long option having a non-empty option value is returned
in <em>*idx</em>, while its option value is stored in <em>*value</em>. Both
<em>*value</em> and <em>*idx</em> are left untouched if long option was not
present. 0 may be specified for <strong>value</strong> if the long option does not
have a value or if the value should not be stored.
<li> <strong>void versionHelp(void (*usage)(std::string const &progname),
char const *version, size_t minArgs, int helpFlag = 'h',
int versionFlag = 'v') const</strong>:<br>
If <em>versionFlag</em> was specified, and the <em>helpFlag</em> was not
specified the program's name (using <strong>basename()</strong>) and <em>version</em> is
displayed to <em>std::cout</em>. Otherwise, if the <em>helpFlag</em> was
provided or if there are fewer arguments than <em>minArgs</em> <em>usage()</em>
is called with argument <strong>basename()</strong>. If either version- or help
information is shown, the <strong>int</strong> value 1 is thrown as an
exception.<br>
Note that <em>versionhelp</em> compares <em>minArgs</em> against <em>nArgs</em>. If
<em>minArgs</em> should be compaired against the number of arguments up to
a possible `--' argument (i.e., <em>beyondDashes</em>' return value), then
add <em>nArgs() - beyondDashes()</em> to the <em>minArg</em> argument. E.g.,
<pre>
arg.versionHelp(usage, version, 2 + arg.nArgs() - arg.beyondDashes());
</pre>
The address of the <em>usage()</em> function, the current version and the
minimum number of arguments must be specified. Default argument values
are provided for the option flags.
</ul>
<p>
<h2>THE NESTED CLASS FBB::Arg::LongOption</h2>
Long options are defined using objects of the nested class
<strong>FBB::Arg::LongOption</strong>. This class offers the following constructors:
<ul>
<li> <strong>FBB::Arg::LongOption(char const *name, FBB::Arg::Type type = None)</strong>:<br>
This constructor is used to define a long option for which no
corresponding short option is defined. The parameter <em>name</em> is the
name of the long option (without prefixing the <em>--</em> characters,
which <em>are</em> required when specifying the long option).
<li> <strong>FBB::Arg::LongOption(char const *name, int optionChar)</strong>:<br>
This constructor is used to define a long option for which a
corresponding short option is defined. The parameter <em>name</em> is the
name of the long option (without prefixing the <em>--</em> characters,
which <em>are</em> required when specifying the long option).
</ul>
In a program, long options may be specified as follows:
<ul>
<li> First, construct an array
<pre>
FBB::Arg::LongOption longOptions[] = { c1, c2, ... cn }
</pre>
Where <em>c1, c2, ..., cn</em> are <strong>n</strong> constructor invocations of
<strong>FBB::Arg::LongOption()</strong> constructors
<li> Next, pass <strong>longOptions, LongOptions + n</strong>
as 2nd and 3rd arguments to <strong>initialize()</strong>
</ul>
<p>
<h2>EXAMPLE</h2>
The following example illustrates defining long options and shows an
initialization. It is not a full-fledched example in the sense of a small
runnable program.
<pre>
#include <bobcat/arg>
using namespace FBB;
namespace // the anonymous namespace can be used here
{
Arg::LongOption longOptions[] =
{
Arg::LongOption("debug"),
Arg::LongOption("filenames", 'f'),
Arg::LongOption("help", 'h'),
Arg::LongOption("version", 'v'),
};
auto longEnd = longOptions + sizeof(longOptions) / sizeof(longOptions[0]);
}
int main(int argc, char **argv)
try
{
Arg &arg = Arg::initialize("df:hv",
longOptions, longEnd, argc, argv);
// code using arg, etc.
}
catch(Exception const &err) // handle exceptions
{
cerr << err.what() << endl;
return err.which();
}
catch(int x)
{
return x;
}
</pre>
<p>
<h2>FILES</h2>
<em>bobcat/arg</em> - defines the class interface
<p>
<h2>SEE ALSO</h2>
<strong>bobcat</strong>(7)
<p>
<h2>BUGS</h2>
None Reported.
<p>
<h2>DISTRIBUTION FILES</h2>
<ul>
<li> <em>bobcat_3.19.01-x.dsc</em>: detached signature;
<li> <em>bobcat_3.19.01-x.tar.gz</em>: source archive;
<li> <em>bobcat_3.19.01-x_i386.changes</em>: change log;
<li> <em>libbobcat1_3.19.01-x_*.deb</em>: debian package holding the
libraries;
<li> <em>libbobcat1-dev_3.19.01-x_*.deb</em>: debian package holding the
libraries, headers and manual pages;
<li> <em>http://sourceforge.net/projects/bobcat</em>: public archive location;
</ul>
<p>
<h2>BOBCAT</h2>
Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
<p>
<h2>COPYRIGHT</h2>
This is free software, distributed under the terms of the
GNU General Public License (GPL).
<p>
<h2>AUTHOR</h2>
Frank B. Brokken (<strong>f.b.brokken@rug.nl</strong>).
<p>
|