Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

ACE_Arg_Shifter Class Reference

This ADT operates on a specified set of arguments (argv). As known arguments are scanned, they are shifted 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. More...

#include <Arg_Shifter.h>

List of all members.

Public Methods

 ACE_Arg_Shifter (int &argc, const ACE_TCHAR **argv, const ACE_TCHAR **temp=0)
 ACE_Arg_Shifter (int &argc, ACE_TCHAR **argv, ACE_TCHAR **temp=0)
 Same behavior as the preceding constructor, but without the "const" qualifier. More...

 ~ACE_Arg_Shifter (void)
 Destructor. More...

const ACE_TCHARget_current (void) const
 Get the current head of the vector. More...

const ACE_TCHARget_the_parameter (const ACE_TCHAR *flag)
int cur_arg_strncasecmp (const ACE_TCHAR *flag)
int consume_arg (int number=1)
 Consume number argument(s) by sticking them/it on the end of the vector. More...

int ignore_arg (int number=1)
 Place number arguments in the same relative order ahead of the known arguments in the vector. More...

int is_anything_left (void) const
 Returns the number of args left to see in the vector. More...

int is_option_next (void) const
 Returns 1 if there's a next item in the vector and it begins with '-'. More...

int is_parameter_next (void) const
 Returns 1 if there's a next item in the vector and it doesn't begin with '-'. More...

int num_ignored_args (void) const
 Returns the number of irrelevant args seen. More...


Private Methods

 ACE_Arg_Shifter (const ACE_Arg_Shifter &)
 Copy Constructor should not be used. More...

ACE_Arg_Shifter operator= (const ACE_Arg_Shifter &)
 Assignment '=' operator should not be used. More...

void init (void)
 Refactor the constructor logic. More...


Private Attributes

int & argc_
 The size of the argument vector. More...

int total_size_
 The size of argv_. More...

const ACE_TCHAR ** temp_
 The temporary array over which we traverse. More...

const ACE_TCHAR ** argv_
 The array in which the arguments are reordered. More...

int current_index_
 The element in <temp_> we're currently examining. More...

int back_
 The index of <argv_> in which we'll stick the next unknown argument. More...

int front_
 The index of <argv_> in which we'll stick the next known argument. More...


Detailed Description

This ADT operates on a specified set of arguments (argv). As known arguments are scanned, they are shifted 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 copied vector, it places known arguments in the rear of the vector, leaving the unknown ones in the beginning. So, after having visited all the arguments in the temporary vector, ACE_Arg_Shifter has placed all the unknown arguments in their original order at the front of original argv.

Definition at line 40 of file Arg_Shifter.h.


Constructor & Destructor Documentation

ACE_Arg_Shifter::ACE_Arg_Shifter int &    argc,
const ACE_TCHAR **    argv,
const ACE_TCHAR **    temp = 0
 

Initialize the ACE_Arg_Shifter to the vector over which to iterate. Optionally, also provide the temporary array for use in shifting the arguments. If ACE_Arg_Shifter must allocate the temporary vector internally and dynamic allocation fails, the ACE_Arg_Shifter will set all indicators to end of the vector, forbidding iteration. Following iteration over argv, the argc value will be updated to contain the number of unconsumed arguments.

Parameters:
argc  The number of strings in argv. argc will be updated to reflect the number of unconsumed arguments.
argv  The argument vector to shift. The string pointers in the vector will be reordered to place the argc unconsumed arguments at the front of the vector.
temp  A vector of ACE_TCHAR pointers at least argc elements long. The vector will be used for argument shifting as the specified argv vector is consumed. The vector must not be modified while this object exists. If this argument is 0 (the default) the object will allocate and free the temporary vector transparently.

Definition at line 12 of file Arg_Shifter.cpp.

References ACE_TCHAR, and init.

00015   : argc_ (argc),
00016     total_size_ (argc),
00017     temp_ (temp),
00018     argv_ (argv),
00019     current_index_ (0),
00020     back_ (argc - 1),
00021     front_ (0)
00022 {
00023   this->init ();
00024 }

ACE_Arg_Shifter::ACE_Arg_Shifter int &    argc,
ACE_TCHAR **    argv,
ACE_TCHAR **    temp = 0
 

Same behavior as the preceding constructor, but without the "const" qualifier.

Definition at line 26 of file Arg_Shifter.cpp.

References ACE_TCHAR, and init.

00029   : argc_ (argc),
00030     total_size_ (argc),
00031     temp_ ((const ACE_TCHAR **) temp),
00032     argv_ ((const ACE_TCHAR **) argv),
00033     current_index_ (0),
00034     back_ (argc - 1),
00035     front_ (0)
00036 {
00037   this->init ();
00038 }

ACE_Arg_Shifter::~ACE_Arg_Shifter void   
 

Destructor.

Definition at line 66 of file Arg_Shifter.cpp.

References temp_.

00067 {
00068   // Delete the temporary vector.
00069   delete [] temp_;
00070 }

ACE_Arg_Shifter::ACE_Arg_Shifter const ACE_Arg_Shifter &    [private]
 

Copy Constructor should not be used.


Member Function Documentation

int ACE_Arg_Shifter::consume_arg int    number = 1
 

Consume number argument(s) by sticking them/it on the end of the vector.

Definition at line 145 of file Arg_Shifter.cpp.

References argv_, back_, current_index_, is_anything_left, and temp_.

Referenced by get_the_parameter.

00146 {
00147   int retval = 0;
00148 
00149   // Stick knowns at the end of the vector (consumed).
00150   if (this->is_anything_left() >= number)
00151     {
00152       for (int i = 0, j = this->back_ - (number - 1);
00153            i < number;
00154            ++i, ++j, ++this->current_index_)
00155         this->argv_[j] = this->temp_[this->current_index_];
00156 
00157       this->back_ -= number;
00158       retval = 1;
00159     }
00160 
00161   return retval;
00162 }

int ACE_Arg_Shifter::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

Definition at line 112 of file Arg_Shifter.cpp.

References ACE_LIB_TEXT, ACE_TCHAR, current_index_, is_anything_left, ACE_OS_String::strlen, ACE_OS_String::strncasecmp, ACE_OS_String::strspn, and temp_.

Referenced by get_the_parameter.

00113 {
00114   // Check for a current argument
00115   if (this->is_anything_left())
00116     {
00117       size_t flag_length = ACE_OS_String::strlen (flag);
00118 
00119       // Check for presence of the flag
00120       if (ACE_OS_String::strncasecmp(this->temp_[current_index_],
00121                                      flag,
00122                                      flag_length) == 0)
00123         {
00124           if (ACE_OS_String::strlen(temp_[current_index_]) ==
00125               flag_length)
00126             {
00127               // match and lengths are equal
00128               return 0;
00129             }
00130           else
00131             {
00132               // matches, with more info to boot!
00133               size_t remaining = ACE_OS_String::strspn
00134                 (this->temp_[current_index_] + flag_length,
00135                  ACE_LIB_TEXT (" ")) + flag_length;
00136               return ACE_static_cast (int, remaining);
00137             }
00138         }
00139     }
00140   // failure
00141   return -1;
00142 }

const ACE_TCHAR * ACE_Arg_Shifter::get_current void    const
 

Get the current head of the vector.

Definition at line 73 of file Arg_Shifter.cpp.

References ACE_TCHAR, current_index_, is_anything_left, and temp_.

00074 {
00075   const ACE_TCHAR * retval = 0;
00076 
00077   if (this->is_anything_left ())
00078     retval =  this->temp_[current_index_];
00079 
00080   return retval;
00081 }

const ACE_TCHAR * ACE_Arg_Shifter::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

Definition at line 84 of file Arg_Shifter.cpp.

References ACE_TCHAR, consume_arg, cur_arg_strncasecmp, current_index_, is_anything_left, is_parameter_next, and temp_.

00085 {
00086   // the return 0's abound because this method
00087   // would otherwise be a deep if { } else { }
00088 
00089   // check to see if any arguments still exist
00090   if (!this->is_anything_left())
00091     return 0;
00092 
00093   // check to see if the flag is the argument
00094   int offset = this->cur_arg_strncasecmp (flag);
00095   if (offset == -1)
00096     return 0;
00097 
00098   if (offset == 0)
00099     {
00100       this->consume_arg ();
00101 
00102       if (!this->is_parameter_next())
00103         {
00104           return 0;
00105         }
00106     }
00107   // the paramter is in the middle somewhere...
00108   return this->temp_[current_index_] + offset;
00109 }

int ACE_Arg_Shifter::ignore_arg int    number = 1
 

Place number arguments in the same relative order ahead of the known arguments in the vector.

Definition at line 165 of file Arg_Shifter.cpp.

References argc_, argv_, current_index_, front_, is_anything_left, and temp_.

00166 {
00167   int retval = 0;
00168 
00169   // Keep unknowns at the head of the vector.
00170   if (this->is_anything_left () >= number)
00171     {
00172       for (int i = 0;
00173            i < number;
00174            i++, this->current_index_++, this->front_++)
00175         this->argv_[this->front_] = this->temp_[this->current_index_];
00176 
00177       retval = 1;
00178       this->argc_ += number;
00179     }
00180 
00181   return retval;
00182 }

void ACE_Arg_Shifter::init void    [private]
 

Refactor the constructor logic.

Definition at line 41 of file Arg_Shifter.cpp.

References ACE_NEW, ACE_TCHAR, argc_, argv_, current_index_, front_, temp_, and total_size_.

Referenced by ACE_Arg_Shifter.

00042 { 
00043   // If not provided with one, allocate a temporary array.  
00044   if (this->temp_ == 0)
00045     ACE_NEW (this->temp_,
00046              const ACE_TCHAR *[this->total_size_]);
00047 
00048   if (this->temp_ != 0)
00049     {
00050       // Fill the temporary array.
00051       this->argc_ = 0;
00052       for (int i = 0; i < this->total_size_; i++)
00053         {
00054           this->temp_[i] = this->argv_[i];
00055           this->argv_[i] = 0;
00056         }
00057     }
00058   else
00059     {
00060       // Allocation failed, prohibit iteration.
00061       this->current_index_ = this->argc_;
00062       this->front_ = this->argc_;
00063     }
00064 }

int ACE_Arg_Shifter::is_anything_left void    const
 

Returns the number of args left to see in the vector.

Definition at line 185 of file Arg_Shifter.cpp.

References current_index_, and total_size_.

Referenced by consume_arg, cur_arg_strncasecmp, get_current, get_the_parameter, ignore_arg, is_option_next, and is_parameter_next.

00186 {
00187   return this->total_size_ - this->current_index_;
00188 }

int ACE_Arg_Shifter::is_option_next void    const
 

Returns 1 if there's a next item in the vector and it begins with '-'.

Definition at line 191 of file Arg_Shifter.cpp.

References current_index_, is_anything_left, and temp_.

00192 {
00193   return this->is_anything_left () &&
00194     this->temp_[this->current_index_][0] == '-';
00195 }

int ACE_Arg_Shifter::is_parameter_next void    const
 

Returns 1 if there's a next item in the vector and it doesn't begin with '-'.

Definition at line 198 of file Arg_Shifter.cpp.

References current_index_, is_anything_left, and temp_.

Referenced by get_the_parameter.

00199 {
00200   return this->is_anything_left ()
00201     && this->temp_[this->current_index_][0] != '-';
00202 }

int ACE_Arg_Shifter::num_ignored_args void    const
 

Returns the number of irrelevant args seen.

Definition at line 205 of file Arg_Shifter.cpp.

References front_.

00206 {
00207   return this->front_;
00208 }

ACE_Arg_Shifter ACE_Arg_Shifter::operator= const ACE_Arg_Shifter &    [private]
 

Assignment '=' operator should not be used.


Member Data Documentation

int& ACE_Arg_Shifter::argc_ [private]
 

The size of the argument vector.

Definition at line 179 of file Arg_Shifter.h.

Referenced by ignore_arg, and init.

const ACE_TCHAR** ACE_Arg_Shifter::argv_ [private]
 

The array in which the arguments are reordered.

Definition at line 188 of file Arg_Shifter.h.

Referenced by consume_arg, ignore_arg, and init.

int ACE_Arg_Shifter::back_ [private]
 

The index of <argv_> in which we'll stick the next unknown argument.

Definition at line 195 of file Arg_Shifter.h.

Referenced by consume_arg.

int ACE_Arg_Shifter::current_index_ [private]
 

The element in <temp_> we're currently examining.

Definition at line 191 of file Arg_Shifter.h.

Referenced by consume_arg, cur_arg_strncasecmp, get_current, get_the_parameter, ignore_arg, init, is_anything_left, is_option_next, and is_parameter_next.

int ACE_Arg_Shifter::front_ [private]
 

The index of <argv_> in which we'll stick the next known argument.

Definition at line 199 of file Arg_Shifter.h.

Referenced by ignore_arg, init, and num_ignored_args.

const ACE_TCHAR** ACE_Arg_Shifter::temp_ [private]
 

The temporary array over which we traverse.

Definition at line 185 of file Arg_Shifter.h.

Referenced by consume_arg, cur_arg_strncasecmp, get_current, get_the_parameter, ignore_arg, init, is_option_next, is_parameter_next, and ~ACE_Arg_Shifter.

int ACE_Arg_Shifter::total_size_ [private]
 

The size of argv_.

Definition at line 182 of file Arg_Shifter.h.

Referenced by init, and is_anything_left.


The documentation for this class was generated from the following files:
Generated on Mon Jun 16 12:44:52 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002