CLASS DEFINITIONS

For the most "up to date" explanation of each class (and of its members), please refer to the relevant include files (which are thoroughly commented) mentioned in the FILES section. The most common facilities of the most commonly used classes are described in the following subsections.

  Class CmdLineArgIter
    Class CmdLineArgIter is an abstract base class for iterating over string arguments from the command-line (or from some other input source). It has two member functions (both of which are pure virtual):

    const char * operator()(void);
        This member function returns the current string argument and then advances to the next string argument. If no arguments are left then NULL is returned.

    int  is_temporary(void)  const;
        This member function is used to indicate the "type" of storage that is used for the values returned by operator(). Some iterators will have operator() return values that will stay around at least as long as the iterator itself; if this is the case, then this member function will return 0. Other iterators may reuse the same storage on successive calls to operator(); if this is the case, this this member function will return a non-zero value.

    There are three predefined subclasses of CmdLineArgIter: CmdArgvIter, CmdStrtokIter, and CmdIstreamIter. class CmdArgvIter : public CmdLineArgIter { public:
       CmdArgvIter(const char * const argv[]);
       CmdArgvIter(int argc, const char * const argv[]);
          // Restart using a different string array.
       void reset(const char * const argv[]);
       void reset(int argc, const char * const argv[]);
       const char * operator()(void);
       int is_temporary(void) const; } ; This class iterates over string arguments that originate from a NULL terminated vector of strings (such as argv), and may be constructed with just an array, or with an array and an item count. class CmdStrTokIter : public CmdLineArgIter { public:
       CmdStrTokIter(const char * tokens, const char * delimiters =NULL);
          // Reset using a new token-string and delimiter set.
       void reset(const char * tokens, const char * delimiters =NULL);
          // Get the current delimiter set
       const char * delimiters(void) const;
          // Change the current delimiter set
       void delimiters(const char * new_delimiters);
       const char * operator()(void);
       int is_temporary(void) const; } ; This class iterates over string arguments that come from a single string that contains multiple tokens which are delimited by one or more characters from the given delimiter set. The strtok(3C) library function is used to extract tokens from the string. If a delimiter set of NULL is given then whitespace will be assumed. class CmdIstreamIter : public CmdLineArgIter { public:
       CmdIstreamIter(istream & input);
       const char * operator()(void);
       int is_temporary(void) const; } ; This class iterates over string arguments that come from an input stream. Each line of the input stream is considered to be a set of white-space separated tokens. If the the first non-white character on a line is `#' (`!' for VMS systems) then the line is considered a comment and is ignored. If a line is more than 1022 characters in length then we treat it as if it were several lines of length 1022 or less.

  Class CmdArg
    A CmdArg is an abstract command-line argument. At this level (being the base class), all a command argument contains is the "interface" (on the command-line) of the argument, and some information (after the command-line has been parsed) that says "how" the argument appeared (if it was specified). The interface of a CmdArg consists of the following:

        •   a character name

        •   a keyword name

        •   a value name (if the argument takes a value)

        •   an argument description

        •   a set of flags describing the syntax of the argument.

        •   a set of flags to record how (and if) the argument appeared on the command-line.
    When constructing a CmdArg, the most common syntax-flags can be inferred from the syntax used in the argument description, and the argument value name. If the first non-white character of the argument description is a semicolon (`;'), then the argument is considered to be "secret" and is NOT printed in usage messages. When specifying a value name, one may enclose the value name in between square brackets (`[' and `]') to indicate the value is optional. Also, one may follow the actual value name with an ellipsis (" ...") to indicate that the value corresponds to a LIST of values. Other more esoteric syntax flags may be specified explicitly by using one or more of the bitmasks of type CmdArg::CmdArgSyntax as the last argument to the constructor; if these syntax-flags are NOT supplied, then reasonable defaults will be used. The different types of constructors for a CmdArg are as follows:
       // Create an option that takes a value.
       //
       // The default flags are to assume that the argument is
       // optional and that the value is required.
       //
       // Examples:
       // // [-c number] or [--count number]
       // CmdArg('c', "count", "number",
       // "specify the # of copies to use);
       //
       // // [-d [level]] or [--debug [level]]
       // CmdArg('d', "debug", "[level]",
       // "turn on debugging and optionally"
       // "specify the debug level");
       //
       // // [-l items ...] or [--list items ...]
       // CmdArg('l', "list", "items ...",
       // "specify a list of items.");
       // CmdArg(char optchar,
           const char * keyword,
           const char * value,
           const char * description,
           unsigned syntax_flags =CmdArg::isOPTVALREQ);
       // Create an option that takes no value.
       //
       // The default syntax-flags are to assume that the
       // argument is optional.
       //
       // Example:
       // // -m or --mode
       // CmdArg('m', "mode", "turn on this mode");
       // CmdArg(char optchar,
           const char * keyword,
           const char * description,
           unsigned syntax_flags =CmdArg::isOPT);
       // Create a positional argument.
       //
       // The default flags are to assume that the argument is
       // positional and that the argument value is required.
       //
       // Examples:
       // CmdArg("file", "file to read");
       //
       // CmdArg("[file]", "optional file to read");
       //
       // CmdArg("file ...", "list of files to read");
       //
       // CmdArg("[file ...]", "optional list of files to read");
       // CmdArg(const char * value,
           const char * description,
           unsigned syntax_flags =CmdArg::isPOSVALREQ); After a command-argument has been declared, you may wish to ask several questions regarding how (and if) it was specified. For example: was the argument given? If it was given, was a value supplied? These questions (and others) may answered using the flags() member function:
         unsigned CmdArg::flags(void) const; This member function returns a set of bitmasks of type CmdArg::CmdArgFlags which are defined in <cmdline.h>. The most common flags are CmdArg::GIVEN (which is set if the argument was given) and CmdArg::VALGIVEN (which is set if a value was supplied for the argument). There are other member functions to return each of the attributes that a CmdArg was constructed with. These member functions (and others) are discussed in <cmdline.h>. Classes that are derived from CmdArg will not have all three of the above destructors. Some derived classes (such as CmdArgBool) only correspond to non-positional arguments that take no value. Other derived classes (such as CmdArgInt and CmdArgStr) always permit a value to be given. Some predefined subclasses of CmdArg which represent the most commonly used types of command-line arguments may be found in <cmdargs.h>.

  Class CmdLine
    Class CmdLine is the class that represents a command-line object. A command-line object is a parsing machine (with machine states), whose parsing behavior may be configured at run-time by specifying various flags of type CmdLine::CmdFlags. A command-line object also contains a command-name and a list of CmdArg objects that correspond to the various arguments that are allowed to occur on the command-line. It is not necessary to supply a command-name at construction time, but one SHOULD be specified before parsing a command-line or printing a usage message. Similarly, CmdArgs are not required at construction time and may even be added on the fly. All desired arguments should be added before any parsing happens and before printing usage. The order in which CmdArgs are added to a CmdLine is important because for positional parameters, this specifies the order in which they are expected to appear on the command-line. The constructors for a CmdLine are as follows (those constructors that take a variable number of parameters must have NULL specified as the final parameter):
            // construct a command (and optionally specify a name)
         CmdLine(const char * name =NULL);
            // construct a command with a name, and arguments
         CmdLine(const char * name, CmdArg * ...);
            // construct a command command with arguments, but no name
         CmdLine(CmdArg * cmdarg, CmdArg * ...); The command name may be set (or queried) after construction by using the name() member function. Command arguments may be added after construction by using the append() member function. The most common requests to make of a CmdLine object is to ask it to parse its arguments, to query it's status, to print the command usage, and to print an error message. These may be accomplished with the following member functions:
       // Print usage to the given outstream or to
       // the default error outstream.
       // ostream & usage(ostream & os) const; ostream & usage(void) const;
       // Print the command-name, followed by ": " and return the
       // outstream for the user to supply the remainder of the
       // error message.
       //
       // Example:
       // cmd.error() << "can't use -x with -y." << endl ;
       // ostream & error(void) const;
       // Obtain the current status of the command. The status will be
       // zero if everything is okay; otherwise it will correspond
       // to a combination of CmdLine::CmdStatus bitmasks telling us
       // precisely what went wrong.
       // unsigned status(void) const;
       // Parse arguments from the given string argument iterator.
       // The return value will be the resultant CmdLine status
       // (which may also be obtained using status()).
       // unsigned parse(CmdLineArgIter & arg_iter); If you wish to modify parsing behavior to something other than the default, there are four more member functions that you will need to know how to use. Each of these member functions deals with bitmasks of the type CmdLine::CmdFlags.
       // Flags that define parsing behavior
       // The default flags (for Unix) are OPTS_FIRST. enum CmdFlags {
       ANY_CASE_OPTS = 0x001, // Ignore character-case for short-options

       PROMPT_USER = 0x002, // Prompt the user for missing required args

       NO_ABORT = 0x004, // Don't exit upon syntax error

       OPTS_FIRST = 0x008, // No options after positional parameters

       OPTS_ONLY = 0x010, // Don't accept long-options

       KWDS_ONLY = 0x020, // Don't accept short-options

       TEMP = 0x040, // Assume all arg-strings are temporary

       QUIET = 0x080, // Don't print syntax error messages

       NO_GUESSING = 0x100, // Don't guess if cant match an option.
                            // Unless this flag is given, then
                            // when we see an unmatched option,
                            // we will try to see if it matches
                            // a keyword (and vice-versa).

       ALLOW_PLUS = 0x200, // Allow "+" (as well as "--") as a prefix
                            // indicating long-options. } ;
       // Get the current set of command-flags unsigned flags(void) const;
       // Specify a new set of command-flags void flags(unsigned newflags);
       // Set only the given command-flags, leave the others alone void set(unsigned flags);
       // Clear only the given command-flags, leave the others alone void clear(unsigned flags =~0); These are the basic member functions of a CmdLine object. The are others as well but these should provide most of the desired functionality. For more detailed information, please see <cmdline.h>.