Query: arg
OS: osx
Section: 3bobcat
Format: Original Unix Latex Style Formatted with HTML and a Horizontal Scroll Bar
FBB::Arg(3bobcat) Command Line Arguments FBB::Arg(3bobcat)NAMEFBB::Arg - A singleton class interfacing command line argumentsSYNOPSIS#include <bobcat/arg> Linking option: -lbobcatDESCRIPTIONSingleton class (see Gamma et al., 1995) built around getopt()(3) and getopt_long()(3). The class handles short- and long command-line options,NAMESPACEFBB All constructors, members, operators and manipulators, mentioned in this man-page, are defined in the namespace FBB.INHERITS FROM-ENUMERATIONThe FBB::Arg::Type enumeration is defined by the FBB::Arg class. It has the following values intended for public use: None, Required, Optional. These values are used when constructing objects of the nested class FBB::Arg::LongOption, see below.CONSTRUCTORSSince the class is a Singleton, no public constructors are available. Instead, static members are offered to initialize and access the sin- gle FBB::Arg object. See below.STATIC MEMBERSo FBB::Arg &initialize(char const *optstring, int argc, char **argv): Initializes the FBB::Arg singleton. Must be called only once. Throws an FBB::Errno exception if called repeatedly or if called with argv not containing a defined option (which is shown by the FBB::Errno's what() member). Returns a reference to the singleton object, allowing code initializing Arg to use the initialized object immediately. o FBB::Arg &initialize(char const *optstring, LongOption const * const begin, LongOption const * const end, int argc, char **argv): Initializes the FBB::Arg singleton. Accepts two iterators of an array of Arg::LongOption objects, holding long-options. Must be called only once. Throws an FBB::Errno exception if called repeatedly or if called with argv not containing a defined option (which is shown by the FBB::Errno's what() member). See the description of Arg::LongOption below. Returns a reference to the singleton object, allowing code initializing Arg to use the initialized object immediately. optstring should consist of letters, possibly postfixed by: o a colon (:), indicating that the option has a required argument; o a double colon (::), indicating that the option itself has an optional argument (in that case, the option's value will be empty, unless specified). o FBB::Arg &instance(): Returns the instance of the Arg object, available after calling one of the Arg::initialize() members. If called before initializa- tion, an FBB::Errno exception is thrown.OVERLOADED OPERATORo char const *operator[](size_t idx) const: Returns argument[idx], after having removed all specified options. 0 is returned if no arg[x] is available. The program name (argv[0]) is NOT counted here: index 0 refers to the first ARGUMENT, e.g., the program's argv[1]. NON-STATIC MEMBER FUNCTIONS o char const **argPointers(): Returns argv-like set of pointers to all remaining arguments. The last element is guaranteed to be a 0-pointer. The first nArg() elements point to the respective C-string values of the arguments. o std::string const &basename() const: Returns the program's basename. o size_t beyondDashes() const: Returns the index of the first argument after a -- argument or nArgs() if no -- argument was encountered. A -- argument ends Arg's argument processing, and all arguments beyond the first -- argument are kept `as is'. The beyondDashes mem- ber returns the index of the first argument beyond the -- argument, which itself is removed from the remaining set of arguments. o size_t nArgs() const: Returns the number of arguments left after option-removal. The program name argv[0] is NOT counted here. o size_t nLongOptions() const: Returns the number of long options for which no short option synonym exist. If long options are multiply specified, then each speci- fication is counted. o size_t nOptions() const: Returns the number of specified single character options. If short options have long option synonyms, then these long option syn- onyms 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. o size_t option(int option) const: The number of times `option' (or its long option synonym, if defined) was specified is returned. o size_t option(std::string const &options) const: The number of times one of the options specified in the `option' argument (or their long option synonyms) were present is returned. o size_t option(string *value, int option) const: 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 *value, which is left untouched if `option' was not present. 0 may be specified for value if the option does not have a value or if the value should not be stored. o size_t option(size_t idx, string *value, int option) const: 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 idxth occurrence (0-based offset) of this option is stored in *value, which is left untouched if `option' was not present or if idx is or exceeds the number of specifications of the provided option. 0 may be specified for value if the option does not have a value or if the value should not be stored. o size_t option(size_t *idx, string *value, int option) const: 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 option specifications) of the first option having a non-empty option value is returned in *idx, while its option value is stored in *value. Both *value and *idx are left untouched if `option' was not present. 0 may be specified for value if the option does not have a value or if the value should not be stored. o size_t option(string *value, char const *longOption) const: Returns the number of times the specified long option (not having a single-character synonym) was present. Its value is then stored in *value, which is left untouched if the long option was not present. 0 may be specified for value if the option does not have a value or if the value should not be stored. o size_t option(size_t idx, string *value, char const * longOption) const: 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 idxth occurrence (0-based offset) of this long option is stored in *value, which is left untouched if the long option was not present or if idx is or exceeds the number of specifications of the provided long option. 0 may be specified for value if the long option does not have a value or if the value should not be stored. o size_t option(size_t *idx, string *value, int longOption) const: 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 *idx, while its option value is stored in *value. Both *value and *idx are left untouched if long option was not present. 0 may be specified for value if the long option does not have a value or if the value should not be stored. o void versionHelp(void (*usage)(std::string const &progname), char const *version, size_t minArgs, int helpFlag = 'h', int version- Flag = 'v') const: If versionFlag was specified, and the helpFlag was not specified the program's name (using basename()) and version is displayed to std::cout. Otherwise, if the helpFlag was provided or if there are fewer arguments than minArgs usage() is called with argument basename(). If either version- or help information is shown, the int value 1 is thrown as an exception. Note that versionhelp compares minArgs against nArgs. If minArgs should be compaired against the number of arguments up to a possi- ble `--' argument (i.e., beyondDashes' return value), then add nArgs() - beyondDashes() to the minArg argument. E.g., arg.versionHelp(usage, version, 2 + arg.nArgs() - arg.beyondDashes()); The address of the usage() function, the current version and the minimum number of arguments must be specified. Default argument values are provided for the option flags.THE NESTED CLASS FBB::Arg::LongOption Long options are defined using objects of the nested class FBB::Arg::LongOption. This class offers the following constructors: o FBB::Arg::LongOption(char const *name, FBB::Arg::Type type = None): This constructor is used to define a long option for which no corresponding short option is defined. The parameter name is the name of the long option (without prefixing the -- characters, which are required when specifying the long option). o FBB::Arg::LongOption(char const *name, int optionChar): This constructor is used to define a long option for which a corresponding short option is defined. The parameter name is the name of the long option (without prefixing the -- characters, which are required when specifying the long option). In a program, long options may be specified as follows: o First, construct an array FBB::Arg::LongOption longOptions[] = { c1, c2, ... cn } Where c1, c2, ..., cn are n constructor invocations of FBB::Arg::LongOption() constructors o Next, pass longOptions, LongOptions + n as 2nd and 3rd arguments to initialize()EXAMPLEThe following example illustrates defining long options and shows an initialization. It is not a full-fletched example in the sense of a small runnable program. #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'), }; Arg::LongOption const *const longEnd = longOptions + sizeof(longOptions) / sizeof(Arg::LongOption); } int main(int argc, char **argv) try { Arg &arg = Arg::initialize("df:hv", longOptions, longEnd, argc, argv); // code using arg, etc. } catch(Errno const &err) // handle exceptions { cerr << err.what() << endl; return err.which(); } catch(int x) { return x; }FILESbobcat/arg - defines the class interfaceSEE ALSObobcat(7)BUGSNone Reported.DISTRIBUTION FILESo bobcat_3.01.00-x.dsc: detached signature; o bobcat_3.01.00-x.tar.gz: source archive; o bobcat_3.01.00-x_i386.changes: change log; o libbobcat1_3.01.00-x_*.deb: debian package holding the libraries; o libbobcat1-dev_3.01.00-x_*.deb: debian package holding the libraries, headers and manual pages; o http://sourceforge.net/projects/bobcat: public archive location;BOBCATBobcat is an acronym of `Brokken's Own Base Classes And Templates'.COPYRIGHTThis is free software, distributed under the terms of the GNU General Public License (GPL).AUTHORFrank B. Brokken (f.b.brokken@rug.nl). libbobcat1-dev_3.01.00-x.tar.gz 2005-2012 FBB::Arg(3bobcat)