/usr/share/doc/libbobcat2-dev/man/argconfig.3.html

<html><head>
<title>FBB::ArgConfig</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::ArgConfig</h1>
<h2>libbobcat1-dev_2.20.01-x.tar.gz</h2>
<h2>2005-2011</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::ArgConfig(3bobcat)</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::ArgConfig(3bobcat)</h1>
<h2>libbobcat1-dev_2.20.01-x.tar.gz Program Arguments</h2>
<h2>2005-2011</h2>


<p>
<h2>NAME</h2>FBB::ArgConfig - A singleton class processing program arguments
<p>
<h2>SYNOPSIS</h2>
    <strong>#include &lt;bobcat/argconfig&gt;</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 as well as configuration files.
<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>
    <strong>FBB::Arg</strong>,<br>
    <strong>FBB::ConfigFile</strong>
<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>ArgConfig</strong> object. See below.
<p>
<h2>STATIC MEMBERS</h2>
    <ul>
    <li> <strong>FBB::ArgConfig &amp;initialize(char const *optstring, int argc, char **argv)</strong>:<br>
        Initializes the <strong>FBB::ArgConfig</strong> singleton. Must be called only once.
Throws an <strong>FBB::Errno</strong> exception if called repeatedly or if called with
<em>argv</em> not containing a defined option (which is shown by the
<strong>FBB::Errno</strong>'s <em>what()</em> member). Returns a reference to the singleton
object, allowing code initializing <strong>ArgConfig</strong> to use the initialized object
immediately.
    <li> <strong>FBB::ArgConfig &amp;initialize(char const *optstring,
                                LongOption const * const begin,
                                LongOption const * const end,
                                int argc, char **argv)</strong>:<br>
        Initializes the <strong>FBB::ArgConfig</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::Errno</strong> exception if called repeatedly or if
called with <em>argv</em> not containing a defined option (which is shown by the
<strong>FBB::Errno</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>ArgConfig</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::ArgConfig &amp;instance()</strong>:<br> 
        Returns the instance of the <strong>ArgConfig</strong> object, available after calling
one of the <strong>ArgConfig::initialize()</strong> members.  If called before initialization, an
<em>FBB::Errno</em> exception is thrown.
    </ul>
<p>
<h2>NON-STATIC MEMBER FUNCTIONS</h2>
    All public members of the <em>Arg</em> and <em>ConfigFile</em> classes are also
offered by the <em>ArgConfig</em> class. As several  <em>option()</em> members were
reimplemented by this class all <em>option()</em> members are discussed below. All
other members inherit straight from the classes <em>Arg</em> and
<em>ConfigFile</em>. Consult their man pages for details.
    <ul>
    <li> <strong>size_t option(int option) const</strong>:<br>
        Returns the number of times `option' (or its long option synonym, if
defined) was specified as command line option or as as a configuration file
option.
<p>
<li> <strong>size_t option(std::string const &amp;options) const</strong>:<br>
        Returns the total number of times any of the characters specified in
the `options' string (or their long option synonyms)
was specified as command line option or as as a configuration file
option.
<p>
<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 as either a command line option or as a configuration
file option. If the return value is non-zero then the value of the
first occurrence of this option (first checking the command line options; then
checking the configuration file) 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.
<p>
<li> <strong>size_t option(size_t idx, string *value, int option) const</strong>:<br>
        This member acts identically to the <em>Arg::option()</em> member having
the identical prototype. It does not consider the configuration file but 
merely 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. 
<p>
<li> <strong>size_t option(size_t *idx, string *value, int option) const</strong>:<br>
        This member acts identically to the <em>Arg::option()</em> member having
the identical prototype. It does not consider the configuration file but
merely 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.
<p>
<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 as either a command line option or in
the configuration file. If found, then the value found at the first occurrence
of the option (first considering the command line options, then the
configuration file) is stored in <em>*value</em>. The string pointed to by
<em>value</em> 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.
<p>
<li> <strong>size_t option(size_t idx, string *value, 
                                        char const * longOption) const</strong>:<br>
        This member acts identically to the <em>Arg::option()</em> member having
the identical prototype. It does not consider the configuration file but
merely 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.
<p>
<li> <strong>size_t option(size_t *idx, string *value, int longOption) const</strong>:<br>
        This member acts identically to the <em>Arg::option()</em> member having
the identical prototype. It does not consider the configuration file but
merely 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.
    </ul>
<p>
<h2>EXAMPLE</h2>
<p>
<pre>

#include &lt;iostream&gt;
#include &lt;string&gt;

#include &lt;bobcat/argconfig&gt;
#include &lt;bobcat/errno&gt;

using namespace std;
using namespace FBB;

ArgConfig::LongOption lo[] =
{
    ArgConfig::LongOption("option", 'o'),
    ArgConfig::LongOption("value-option", 'v')
};

class X
{
    ArgConfig &amp;d_arg;

    public:
        X();
        void function();
};

X::X()
:
    d_arg(ArgConfig::instance())
{}

void X::function()
{
    if (d_arg.nArgs() == 0)
        throw Errno("Provide the name of a config file as 1st arg");

    cout &lt;&lt; "Counting " &lt;&lt; d_arg.option('o') &lt;&lt; " instances of -o or "
                                                            "--option\n";

    d_arg.open(d_arg[0]);       // Now open the config file explicitly
                            // (alternatively: use a constructor expecting 
                            // a file name)

    cout &lt;&lt; "Counting " &lt;&lt; d_arg.option('o') &lt;&lt; " instances of -o or "
                                                            "--option\n";

    string optval;
    size_t count = d_arg.option(&amp;optval, 'v');

    cout &lt;&lt; "Counting " &lt;&lt; count &lt;&lt; 
                        " instances of -v or --value-option\n";
    if (count)
        cout &lt;&lt; "Option value = " &lt;&lt; optval &lt;&lt; endl;
}

int main(int argc, char **argv)
try
{
    ArgConfig::initialize("ov:", lo, lo + 2, argc, argv);

    X x;
    x.function();

    return 0;
}
catch (Errno const &amp;err)
{
    cout &lt;&lt; "Terminating " &lt;&lt; err.what() &lt;&lt; endl;
    return 1;
}
    
</pre>

<p>
<h2>FILES</h2>
    <em>bobcat/argconfig</em> - defines the class interface
<p>
<h2>SEE ALSO</h2>
    <strong>arg</strong>(3bobcat), <strong>configfile</strong>(3obcat), <strong>bobcat</strong>(7)
<p>
<h2>BUGS</h2>
    None Reported.
<p>

<h2>DISTRIBUTION FILES</h2>
    <ul>
    <li> <em>bobcat_2.20.01-x.dsc</em>: detached signature;
    <li> <em>bobcat_2.20.01-x.tar.gz</em>: source archive;
    <li> <em>bobcat_2.20.01-x_i386.changes</em>: change log;
    <li> <em>libbobcat1_2.20.01-x_*.deb</em>: debian package holding the
            libraries;
    <li> <em>libbobcat1-dev_2.20.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>
libbobcat-dev 2.20.01-1 / usr / share / doc / libbobcat2-dev / man / argconfig.3.html
