diff options
Diffstat (limited to 'ace/Arg_Shifter.h')
-rw-r--r-- | ace/Arg_Shifter.h | 229 |
1 files changed, 117 insertions, 112 deletions
diff --git a/ace/Arg_Shifter.h b/ace/Arg_Shifter.h index 4ae9b7a1262..2e61342d97f 100644 --- a/ace/Arg_Shifter.h +++ b/ace/Arg_Shifter.h @@ -1,18 +1,15 @@ // This may look like C, but it's really -*- C++ -*- -// $Id$ - -// ======================================================================== -// -// = LIBRARY -// ace -// -// = FILENAME -// Arg_Shifter.h -// -// = AUTHOR -// Seth Widoff -// -// ======================================================================== + +//============================================================================= +/** + * @file Arg_Shifter.h + * + * $Id$ + * + * @author Seth Widoff + */ +//============================================================================= + #ifndef ACE_ARG_SHIFTER_H #define ACE_ARG_SHIFTER_H @@ -21,146 +18,154 @@ #include "ace/OS.h" +/** + * @class ACE_Arg_Shifter + * + * @brief This ADT shifts known args to the back of the argv vector, so + * deeper levels of argument parsing can locate the yet + * unprocessed arguments at the beginning of the vector. + * + * The <ACE_Arg_Shifter> copies the pointers of the argv vector + * into a temporary array. As the <ACE_Arg_Shifter> iterates over + * the temp, is places known arguments in the rear of the argv + * and unknown ones in the beginning. So, after having visited + * all the arguments in the temp vector, <ACE_Arg_Shifter> has + * placed all the unknown arguments in their original order at + * the front of argv. + */ class ACE_Export ACE_Arg_Shifter { - // = TITLE - // This ADT shifts known args to the back of the argv vector, so - // deeper levels of argument parsing can locate the yet - // unprocessed arguments at the beginning of the vector. - // - // = DESCRIPTION - // The <ACE_Arg_Shifter> copies the pointers of the argv vector - // into a temporary array. As the <ACE_Arg_Shifter> iterates over - // the temp, is places known arguments in the rear of the argv - // and unknown ones in the beginning. So, after having visited - // all the arguments in the temp vector, <ACE_Arg_Shifter> has - // placed all the unknown arguments in their original order at - // the front of argv. public: // = Initialization and termination methods. + /** + * Initialize the <ACE_Arg_Shifter> to the vector over which to + * iterate, also providing the temporary array if the client doesn't + * want the arg_shifter to dynamically allocate its own. If internal + * dynamic allocation fails, the <ACE_Arg_Shifter> will set all the + * indices to the end of the vector, forbidding iteration. Following + * iteration over argv, the argc value will contain the number of + * unconsumed arguments. + */ ACE_Arg_Shifter (int& argc, ACE_TCHAR **argv, ACE_TCHAR **temp = 0); - // Initialize the <ACE_Arg_Shifter> to the vector over which to - // iterate, also providing the temporary array if the client doesn't - // want the arg_shifter to dynamically allocate its own. If internal - // dynamic allocation fails, the <ACE_Arg_Shifter> will set all the - // indices to the end of the vector, forbidding iteration. Following - // iteration over argv, the argc value will contain the number of - // unconsumed arguments. + /// Destructor. ~ACE_Arg_Shifter (void); - // Destructor. + /// Get the current head of the vector. ACE_TCHAR *get_current (void) const; - // Get the current head of the vector. + /** + * If the <flag> matches the current_arg of arg shifter + * this method will attempt to return the associated + * parameter value + * + * Safe to call without checking that a current arg exists + * + * In the following examples, a pointer to the char* "value" is ret + * + * eg: main -foobar value, main -FooBar value + * main -FOOBARvalue + * + * all of the above will all match the <flag> == -FooBar + * and will return a char* to "value" + * + * main -foobar 4 would succeed and return a char* to "4" + * main -foobar -4 does not succeed (-4 is not a parameter) + * but instead, would return 0 + * + * 0 is returned: + * If the current argument does not match flag + * If there is no parameter found after a 'matched' flag + * + * If the flag is matched and the flag and paramter DO NOT RUN + * together, the flag is consumed, the parameter is returned, + * and the new current argument is the parameter value. + * ie '-foobarflag VALUE' leaves the new cur arg == "VALUE" + * + * If the flag is matched and the flag and parameter RUN + * together '-foobarflagVALUE', the flag is NOT consumed + * and the cur arg is left pointing to the entire flag/value pair + */ ACE_TCHAR *get_the_parameter (const ACE_TCHAR* flag); - // If the <flag> matches the current_arg of arg shifter - // this method will attempt to return the associated - // parameter value - // - // Safe to call without checking that a current arg exists - // - // In the following examples, a pointer to the char* "value" is ret - // - // eg: main -foobar value, main -FooBar value - // main -FOOBARvalue - // - // all of the above will all match the <flag> == -FooBar - // and will return a char* to "value" - // - // main -foobar 4 would succeed and return a char* to "4" - // main -foobar -4 does not succeed (-4 is not a parameter) - // but instead, would return 0 - // - // 0 is returned: - // If the current argument does not match flag - // If there is no parameter found after a 'matched' flag - // - // If the flag is matched and the flag and paramter DO NOT RUN - // together, the flag is consumed, the parameter is returned, - // and the new current argument is the parameter value. - // ie '-foobarflag VALUE' leaves the new cur arg == "VALUE" - // - // If the flag is matched and the flag and parameter RUN - // together '-foobarflagVALUE', the flag is NOT consumed - // and the cur arg is left pointing to the entire flag/value pair + /** + * Check if the current argument matches (case insensitive) <flag> + * + * ------------------------------------------------------------ + * + * Case A: Perfect Match (case insensitive) + * 0 is returned. + * + * ie: when current_arg = "-foobar" or "-FOOBAR" or "-fooBAR" + * this->cur_arg_strncasecmp ("-FooBar); + * will return 0 + * + * ------------------------------------------------------------ + * + * Case B: Perfect Match (case insensitive) but the current_arg + * is longer than the flag. Returns a number equal to the index + * in the char* indicating the start of the extra characters + * + * ie: when current_arg = "-foobar98023" + * this->cur_arg_strncasecmp ("-FooBar); + * will return 7 + * + * Notice: this number will always be > 0 + * + * ------------------------------------------------------------ + * + * Case C: If neither of Case A or B is met (no match) + * then -1 is returned + */ int cur_arg_strncasecmp (const ACE_TCHAR *flag); - // Check if the current argument matches (case insensitive) <flag> - // - // ------------------------------------------------------------ - // - // Case A: Perfect Match (case insensitive) - // 0 is returned. - // - // ie: when current_arg = "-foobar" or "-FOOBAR" or "-fooBAR" - // this->cur_arg_strncasecmp ("-FooBar); - // will return 0 - // - // ------------------------------------------------------------ - // - // Case B: Perfect Match (case insensitive) but the current_arg - // is longer than the flag. Returns a number equal to the index - // in the char* indicating the start of the extra characters - // - // ie: when current_arg = "-foobar98023" - // this->cur_arg_strncasecmp ("-FooBar); - // will return 7 - // - // Notice: this number will always be > 0 - // - // ------------------------------------------------------------ - // - // Case C: If neither of Case A or B is met (no match) - // then -1 is returned + /// Consume <number> argument(s) by sticking them/it on the end of + /// the vector. int consume_arg (int number = 1); - // Consume <number> argument(s) by sticking them/it on the end of - // the vector. + /// Place <number> arguments in the same relative order ahead of the + /// known arguemnts in the vector. int ignore_arg (int number = 1); - // Place <number> arguments in the same relative order ahead of the - // known arguemnts in the vector. + /// Returns the number of args left to see in the vector. int is_anything_left (void) const; - // Returns the number of args left to see in the vector. + /// Returns 1 if there's a next item in the vector and it begins with + /// '-'. int is_option_next (void) const; - // Returns 1 if there's a next item in the vector and it begins with - // '-'. + /// Returns 1 if there's a next item in the vector and it doesn't + /// begin with '-'. int is_parameter_next (void) const; - // Returns 1 if there's a next item in the vector and it doesn't - // begin with '-'. + /// Returns the number of irrelevant args seen. int num_ignored_args (void) const; - // Returns the number of irrelevant args seen. private: + /// The size of the argument vector. int& argc_; - // The size of the argument vector. + /// The size of argv_. int total_size_; - // The size of argv_. + /// The temporary array over which we traverse. ACE_TCHAR **temp_; - // The temporary array over which we traverse. + /// The array in which the arguments are reordered. ACE_TCHAR **argv_; - // The array in which the arguments are reordered. + /// The element in <temp_> we're currently examining. int current_index_; - // The element in <temp_> we're currently examining. + /// The index of <argv_> in which we'll stick the next unknown + /// argument. int back_; - // The index of <argv_> in which we'll stick the next unknown - // argument. + /// The index of <argv_> in which we'll stick the next known + /// argument. int front_; - // The index of <argv_> in which we'll stick the next known - // argument. }; #include "ace/post.h" |