diff --git a/include/tclap/Arg.h b/include/tclap/Arg.h index 52365d1..06dc59a 100644 --- a/include/tclap/Arg.h +++ b/include/tclap/Arg.h @@ -44,11 +44,18 @@ class Arg { private: + /** + * Indicates whether the rest of the arguments should be ignored. + */ static bool _ignoreRest; protected: + /** + * The delimiter that separates an argument flag/name from the + * value. + */ static char _delimiter; /** @@ -113,17 +120,55 @@ class Arg void _checkWithVisitor() const; public: - + + /** + * Begin ignoring arguments since the "--" argument was specified. + */ static void beginIgnoring() { Arg::_ignoreRest = true; } + + /** + * Whether to ignore the rest. + */ static bool ignoreRest() { return Arg::_ignoreRest; } + + /** + * The char used as a place holder when SwitchArgs are combined. + * Currently set to '*', which shouldn't cause many problems since + * *'s are expanded by most shells on the command line. + */ + static const char blankChar; + + /** + * The char that indicates the beginning of a flag. Currently '-'. + */ + static const char flagStartChar; + + /** + * The sting that indicates the beginning of a flag. Currently "-". + * Should be identical to flagStartChar. + */ + static const string flagStartString; + + /** + * The sting that indicates the beginning of a name. Currently "--". + * Should be flagStartChar twice. + */ + static const string nameStartString; /** * Sets the delimiter for all arguments. + * \param c - The character that delimits flags/names from values. */ static void setDelimiter( char c ) { Arg::_delimiter = c; } /** * Primary constructor. + * \param flag - The flag identifying the argument. + * \param name - The name identifying the argument. + * \param desc - The description of the argument, used in the usage. + * \param req - Whether the argument is required. + * \param valreq - Whether the a value is required for the argument. + * \param v - The visitor checked by the argument. Defaults to NULL. */ Arg(const string& flag, const string& name, @@ -140,14 +185,16 @@ class Arg /** * Copy constructor. + * \param a - The Arg to be copied. */ - Arg(const Arg&); + Arg(const Arg& a); /** * Operator =. * Assignment operator. + * \param a - The Arg to be assigned to this. */ - Arg& operator=(const Arg&); + Arg& operator=(const Arg& a); /** * Destructor. @@ -171,8 +218,9 @@ class Arg /** * Operator ==. * Equality operator. Must be virtual to handle unlabeled args. + * \param a - The Arg to be compared to this. */ - virtual bool operator==(const Arg&); + virtual bool operator==(const Arg& a); /** * Returns the argument flag. @@ -214,6 +262,8 @@ class Arg * This is generally called by the processArg() method. This * method could be re-implemented by a child to change how * arguments are specified on the command line. + * \param s - The string to be compared to the flag/name to determine + * whether the arg matches. */ virtual bool argMatches( const string& s ) const; @@ -225,19 +275,32 @@ class Arg /** * Returns a short ID for the usage. + * \param valueId - The value used in the id. */ virtual string shortID( const string& valueId = "val" ) const; /** * Returns a long ID for the usage. + * \param valueId - The value used in the id. */ virtual string longID( const string& valueId = "val" ) const; /** * Trims a value off of the flag. + * \param flag - The string from which the flag and value will be + * trimmed. Contains the flag once the value has been trimmed. + * \param value - Where the value trimmed from the string will + * be stored. */ virtual void trimFlag( string& flag, string& value ) const; + /** + * Checks whether a given string has blank chars, indicating that + * it is a combined SwitchArg. If so, return true, otherwise return + * false. + */ + bool _hasBlanks( const string& s ) const; + }; diff --git a/include/tclap/ArgException.h b/include/tclap/ArgException.h index 87fb496..ab675c2 100644 --- a/include/tclap/ArgException.h +++ b/include/tclap/ArgException.h @@ -29,20 +29,42 @@ using namespace std; namespace TCLAP { +/** + * A simple class that defines and argument exception. Should be caught + * whenever a CmdLine is created and parsed. + */ class ArgException { public: - + + /** + * Constructor. + * \param text - The text of the exception. + * \param id - The text identifying the argument source + * of the exception. + */ ArgException( const string& text = "undefined exception", const string& id = "undefined" ) : _errorText(text), _argId( id ) {}; + /** + * Copy constructor. + * \param e - The ArgException that will be copied. + */ ArgException(const ArgException& e) : _errorText(e._errorText), _argId(e._argId) {}; - ~ArgException(){}; + /** + * Destructor. + */ + ~ArgException() {}; + /** + * Assignment operator. + * \param e - The ArgException that will be assigned + * to this. + */ ArgException& operator=( const ArgException& e ) { if ( this != &e ) @@ -53,7 +75,14 @@ class ArgException return *this; }; + /** + * Returns the error text. + */ string error() { return ( _errorText ); }; + + /** + * Returns the argument id. + */ string argId() { if ( _argId == "undefined" ) @@ -64,7 +93,14 @@ class ArgException private: + /** + * The text of the exception message. + */ string _errorText; + + /** + * The argument related to this exception. + */ string _argId; }; diff --git a/include/tclap/CmdLine.h b/include/tclap/CmdLine.h index ac542c5..b23f5b4 100644 --- a/include/tclap/CmdLine.h +++ b/include/tclap/CmdLine.h @@ -45,22 +45,88 @@ namespace TCLAP { class CmdLine { protected: + + /** + * The list of arguments that will be tested against the + * command line. + */ list _argList; + + /** + * The name of the program. Set to argv[0]. + */ string _progName; + + /** + * A message used to describe the program. Used in the usage output. + */ string _message; + + /** + * The version to be displayed with the --version switch. + */ string _version; - int _maxLength; + + /** + * The number of arguments that are required to be present on + * the command line. This is set dynamically, based on the + * Args added to the CmdLine object. + */ int _numRequired; + + /** + * The character that is used to separate the argument flag/name + * from the value. Defaults to ' ' (space). + */ char _delimiter; + /** + * Checks whether a name/flag string matches entirely matches + * the Arg::blankChar. Used when multiple switches are combined + * into a single argument. + * \param s - The message to be used in the usage. + */ + bool _emptyCombined(const string& s); + public: + + /** + * Command line constructor. Defines how the arguments will be + * parsed. + * \param message - The message to be used in the usage + * output. + * \param delimiter - The character that is used to separate + * the argument flag/name from the value. Defaults to ' ' (space). + * \param version - The version number to be used in the + * --version switch. + */ CmdLine(const string& message, const char delimiter = ' ', const string& version = "none" ); + /** + * Adds an argument to the list of arguments to be parsed. + * \param a - Argument to be added. + */ void add( Arg& a ); + + /** + * Prints the usage to stdout and exits. + * \param exitVal - Value to exit with. + */ void usage( int exitVal = 0 ); + + /** + * Prints the version to stdout and exits. + * \param exitVal - Value to exit with. + */ void version( int exitVal = 0 ); + + /** + * Parses the command line. + * \param argc - Number of arguments. + * \param argv - Array of arguments. + */ void parse(int argc, char** argv); }; diff --git a/include/tclap/HelpVisitor.h b/include/tclap/HelpVisitor.h index 8c70c03..9ee0b86 100644 --- a/include/tclap/HelpVisitor.h +++ b/include/tclap/HelpVisitor.h @@ -26,14 +26,29 @@ namespace TCLAP { +/** + * A Visitor object that calls the usage method of a given CmdLine. + */ class HelpVisitor: public Visitor { protected: + + /** + * The CmdLine that will be called for the usage method. + */ CmdLine* _cmd; public: + + /** + * Constructor. + * \param cmd - The CmdLine that will called for usage method. + */ HelpVisitor(CmdLine* cmd) : Visitor(), _cmd( cmd ) {}; + /** + * Calls the usage method of the CmdLine. + */ void visit() { _cmd->usage(0); } }; diff --git a/include/tclap/IgnoreRestVisitor.h b/include/tclap/IgnoreRestVisitor.h index fa67856..574614a 100644 --- a/include/tclap/IgnoreRestVisitor.h +++ b/include/tclap/IgnoreRestVisitor.h @@ -28,11 +28,22 @@ namespace TCLAP { +/** + * A Vistor that tells the CmdLine to begin ignoring arguments after + * this one is parsed. + */ class IgnoreRestVisitor: public Visitor { public: + + /** + * Constructor. + */ IgnoreRestVisitor() : Visitor() {}; + /** + * Sets Arg::_ignoreRest. + */ void visit() { Arg::beginIgnoring(); } }; diff --git a/include/tclap/MultiArg.h b/include/tclap/MultiArg.h index fc39aa8..c129a1c 100644 --- a/include/tclap/MultiArg.h +++ b/include/tclap/MultiArg.h @@ -32,19 +32,53 @@ using namespace std; namespace TCLAP { +/** + * An argument that allows multiple values of type T to be specified. Very + * similar to a ValueArg, except a vector of values will be returned + * instead of just one. + */ template class MultiArg : public Arg { protected: + /** + * The list of values parsed from the CmdLine. + */ vector _values; + /** + * The description of type T to be used in the usage. + */ string _typeDesc; + /** + * Extracts the value from the string. + * Attempts to parse string as type T, if this fails an exception + * is thrown. + * \param val - The string to be read. + */ void _extractValue( const string& val ); public: + /** + * Constructor. + * \param flag - The one character flag that identifies this + * argument on the command line. + * \param name - A one word name for the argument. Can be + * used as a long flag on the command line. + * \param desc - A description of what the argument is for or + * does. + * \param req - Whether the argument is required on the command + * line. + * \param typeDesc - A short, human readable description of the + * type that this object expects. This is used in the generation + * of the USAGE statement. The goal is to be helpful to the end user + * of the program. + * \param v - An optional visitor. You probably should not + * use this unless you have a very good reason. + */ MultiArg( const string& flag, const string& name, const string& desc, @@ -52,18 +86,44 @@ class MultiArg : public Arg const string& typeDesc, Visitor* v = NULL); + /** + * Destructor. + */ ~MultiArg(); + /** + * Handles the processing of the argument. + * This re-implements the Arg version of this method to set the + * _value of the argument appropriately. It knows the difference + * between labeled and unlabeled. + * \param i - Pointer the the current argument in the list. + * \param args - Mutable list of strings. Passed from main(). + */ virtual bool processArg(int* i, vector& args); + /** + * Returns a vector of type T containing the values parsed from + * the command line. + */ const vector& getValue() ; + /** + * Returns the a short id string. Used in the usage. + * \param val - value to be used. + */ virtual string shortID(const string& val="val") const; + + /** + * Returns the a long id string. Used in the usage. + * \param val - value to be used. + */ virtual string longID(const string& val="val") const; }; - +/** + * + */ template MultiArg::MultiArg(const string& flag, const string& name, @@ -75,18 +135,30 @@ MultiArg::MultiArg(const string& flag, _typeDesc( typeDesc ) { }; +/** + * + */ template MultiArg::~MultiArg() { }; +/** + * + */ template const vector& MultiArg::getValue() { return _values; }; +/** + * + */ template bool MultiArg::processArg(int *i, vector& args) { if ( _ignoreable && Arg::ignoreRest() ) return false; + if ( _hasBlanks( args[*i] ) ) + return false; + string flag = args[*i]; string value = ""; @@ -116,6 +188,9 @@ bool MultiArg::processArg(int *i, vector& args) return false; } +/** + * + */ template void MultiArg::_extractValue( const string& val ) { @@ -130,6 +205,9 @@ void MultiArg::_extractValue( const string& val ) _checkWithVisitor(); } +/** + * + */ template string MultiArg::shortID(const string& val) const { @@ -138,6 +216,9 @@ string MultiArg::shortID(const string& val) const return id; } +/** + * + */ template string MultiArg::longID(const string& val) const { diff --git a/include/tclap/SwitchArg.h b/include/tclap/SwitchArg.h index 1d78a44..7bf064f 100644 --- a/include/tclap/SwitchArg.h +++ b/include/tclap/SwitchArg.h @@ -33,31 +33,68 @@ using namespace std; namespace TCLAP { +/** + * A simple switch argument. If the switch is set on the command line, then + * the getValue method will return the opposite of the default value for the + * switch. + */ class SwitchArg : public Arg { protected: + /** + * The value of the switch. + */ bool _value; public: + /** + * SwitchArg constructor. + * \param flag - The one character flag that identifies this + * argument on the command line. + * \param name - A one word name for the argument. Can be + * used as a long flag on the command line. + * \param desc - A description of what the argument is for or + * does. + * \param def - The default value for this Switch. + * \param v - An optional visitor. You probably should not + * use this unless you have a very good reason. + */ SwitchArg(const string& flag, const string& name, const string& desc, - bool _default, + bool def, Visitor* v = NULL); + /** + * Destructor. + */ ~SwitchArg(); + /** + * Handles the processing of the argument. + * This re-implements the Arg version of this method to set the + * _value of the argument appropriately. + * \param i - Pointer the the current argument in the list. + * \param args - Mutable list of strings. Passed + * in from main(). + */ virtual bool processArg(int* i, vector& args); + /** + * Checks a string to see if any of the chars in the string + * match the flag for this Switch. + */ bool combinedSwitchesMatch(string& combined); + /** + * Returns bool, whether or not the switch has been set. + */ bool getValue() ; }; - } #endif diff --git a/include/tclap/UnlabeledMultiArg.h b/include/tclap/UnlabeledMultiArg.h index 7e00a48..558f266 100644 --- a/include/tclap/UnlabeledMultiArg.h +++ b/include/tclap/UnlabeledMultiArg.h @@ -32,21 +32,63 @@ using namespace std; namespace TCLAP { +/** + * Just like a MultiArg, except that the arguments are unlabeled. Basically, + * this Arg will slurp up everything that hasn't been matched to another + * Arg. + */ template class UnlabeledMultiArg : public MultiArg { public: - + + /** + * Constructor. + * \param name - The name of the Arg. Note that this is used for + * identification, not as a long flag. + * \param desc - A description of what the argument is for or + * does. + * \param typeDesc - A short, human readable description of the + * type that this object expects. This is used in the generation + * of the USAGE statement. The goal is to be helpful to the end user + * of the program. + * \param ignoreable - Whether or not this argument can be ignored + * using the "--" flag. + * \param v - An optional visitor. You probably should not + * use this unless you have a very good reason. + */ UnlabeledMultiArg( const string& name, const string& desc, const string& typeDesc, bool ignoreable = false, Visitor* v = NULL ); + /** + * Handles the processing of the argument. + * This re-implements the Arg version of this method to set the + * _value of the argument appropriately. It knows the difference + * between labeled and unlabeled. + * \param i - Pointer the the current argument in the list. + * \param args - Mutable list of strings. Passed from main(). + */ virtual bool processArg(int* i, vector& args); + /** + * Returns the a short id string. Used in the usage. + * \param val - value to be used. + */ virtual string shortID(const string& val="val") const; + + /** + * Returns the a long id string. Used in the usage. + * \param val - value to be used. + */ virtual string longID(const string& val="val") const; + + /** + * Opertor ==. + * \param a - The Arg to be compared to this. + */ virtual bool operator==(const Arg& a) const; }; @@ -65,8 +107,12 @@ UnlabeledMultiArg::UnlabeledMultiArg(const string& name, template bool UnlabeledMultiArg::processArg(int *i, vector& args) { + + if ( _hasBlanks( args[*i] ) ) + return false; + // never ignore an unlabeled multi arg - + _extractValue( args[*i] ); return true; } diff --git a/include/tclap/UnlabeledValueArg.h b/include/tclap/UnlabeledValueArg.h index 0fd6b4a..bba1c3b 100644 --- a/include/tclap/UnlabeledValueArg.h +++ b/include/tclap/UnlabeledValueArg.h @@ -123,11 +123,15 @@ UnlabeledValueArg::UnlabeledValueArg(const string& name, template bool UnlabeledValueArg::processArg(int *i, vector& args) { - // never ignore an unlabeled arg if ( _alreadySet ) return false; + + if ( _hasBlanks( args[*i] ) ) + return false; + // never ignore an unlabeled arg + _extractValue( args[*i] ); _alreadySet = true; return true; diff --git a/include/tclap/ValueArg.h b/include/tclap/ValueArg.h index 48425b1..52763b6 100644 --- a/include/tclap/ValueArg.h +++ b/include/tclap/ValueArg.h @@ -66,10 +66,10 @@ class ValueArg : public Arg * Extracts the value from the string. * Attempts to parse string as type T, if this fails an exception * is thrown. - * \param val - string value to be parsed. + * \param val - value to be parsed. */ void _extractValue( const string& val ); - + public: /** @@ -126,11 +126,13 @@ class ValueArg : public Arg /** * Specialization of shortID. + * \param val - value to be used. */ virtual string shortID(const string& val = "val") const; /** * Specialization of longID. + * \param val - value to be used. */ virtual string longID(const string& val = "val") const; @@ -175,8 +177,10 @@ bool ValueArg::processArg(int *i, vector& args) if ( _ignoreable && Arg::ignoreRest() ) return false; - string flag = args[*i]; + if ( _hasBlanks( args[*i] ) ) + return false; + string flag = args[*i]; string value = ""; trimFlag( flag, value ); diff --git a/include/tclap/VersionVisitor.h b/include/tclap/VersionVisitor.h index 83341e6..074f286 100644 --- a/include/tclap/VersionVisitor.h +++ b/include/tclap/VersionVisitor.h @@ -27,14 +27,30 @@ namespace TCLAP { +/** + * A Vistor that will call the version method of the given CmdLine and + * then exit. + */ class VersionVisitor: public Visitor { protected: + + /** + * The CmdLine of interest. + */ CmdLine* _cmd; public: + + /** + * Constructor. + * \param cmd - The CmdLine whose version method will be called. + */ VersionVisitor(CmdLine* cmd) : Visitor(), _cmd( cmd ) {}; + /** + * Prints the version to stdout. + */ void visit() { _cmd->version(0); } }; diff --git a/include/tclap/Visitor.h b/include/tclap/Visitor.h index c705a9d..b6f5441 100644 --- a/include/tclap/Visitor.h +++ b/include/tclap/Visitor.h @@ -25,10 +25,21 @@ namespace TCLAP { +/** + * A base class that defines the interface for visitors. + */ class Visitor { public: + + /** + * Constructor. Does nothing. + */ Visitor() {}; + + /** + * Does nothing. Should be overridden by child. + */ virtual void visit() {}; };