ACE_Arg_Shifter_T< CHAR_TYPE > Class Template 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>

Collaboration diagram for ACE_Arg_Shifter_T< CHAR_TYPE >:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 ACE_Arg_Shifter_T (int &argc, const CHAR_TYPE **argv, const CHAR_TYPE **temp=0)
 ACE_Arg_Shifter_T (int &argc, CHAR_TYPE **argv, CHAR_TYPE **temp=0)
 ~ACE_Arg_Shifter_T (void)
 Destructor.
const CHAR_TYPE * get_current (void) const
 Get the current head of the vector.
const CHAR_TYPE * get_the_parameter (const CHAR_TYPE *flag)
int cur_arg_strncasecmp (const CHAR_TYPE *flag)
int consume_arg (int number=1)
int ignore_arg (int number=1)
int is_anything_left (void) const
 Returns the number of args left to see in the vector.
int is_option_next (void) const
int is_parameter_next (void) const
int num_ignored_args (void) const
 Returns the number of irrelevant args seen.

Private Member Functions

 ACE_Arg_Shifter_T (const ACE_Arg_Shifter_T< CHAR_TYPE > &)
 Copy Constructor should not be used.
ACE_Arg_Shifter_T operator= (const ACE_Arg_Shifter_T< CHAR_TYPE > &)
 Assignment '=' operator should not be used.
void init (void)
 Refactor the constructor logic.

Private Attributes

int & argc_
 The size of the argument vector.
int total_size_
 The size of argv_.
const CHAR_TYPE ** temp_
 The temporary array over which we traverse.
const CHAR_TYPE ** argv_
 The array in which the arguments are reordered.
int current_index_
 The element in <temp_> we're currently examining.
int back_
int front_

Detailed Description

template<typename CHAR_TYPE>
class ACE_Arg_Shifter_T< CHAR_TYPE >

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 45 of file Arg_Shifter.h.

Constructor & Destructor Documentation

template<typename CHAR_TYPE>
ACE_BEGIN_VERSIONED_NAMESPACE_DECL ACE_Arg_Shifter_T< CHAR_TYPE >::ACE_Arg_Shifter_T ( int &  argc,
const CHAR_TYPE **  argv,
const CHAR_TYPE **  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 CHAR_TYPE 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 18 of file Arg_Shifter.cpp.

References ACE::init().

00021   : argc_ (argc),
00022     total_size_ (argc),
00023     temp_ (temp),
00024     argv_ (argv),
00025     current_index_ (0),
00026     back_ (argc - 1),
00027     front_ (0)
00028 {
00029   this->init ();
00030 }

template<typename CHAR_TYPE>
ACE_Arg_Shifter_T< CHAR_TYPE >::ACE_Arg_Shifter_T ( int &  argc,
CHAR_TYPE **  argv,
CHAR_TYPE **  temp = 0 
)

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

Definition at line 33 of file Arg_Shifter.cpp.

References ACE_Arg_Shifter_T< CHAR_TYPE >::init().

00036   : argc_ (argc),
00037     total_size_ (argc),
00038     temp_ ((const CHAR_TYPE **) temp),
00039     argv_ ((const CHAR_TYPE **) argv),
00040     current_index_ (0),
00041     back_ (argc - 1),
00042     front_ (0)
00043 {
00044   this->init ();
00045 }

template<typename CHAR_TYPE>
ACE_Arg_Shifter_T< CHAR_TYPE >::~ACE_Arg_Shifter_T ( void   ) 

Destructor.

Definition at line 75 of file Arg_Shifter.cpp.

References ACE_Arg_Shifter_T< CHAR_TYPE >::temp_.

00076 {
00077   // Delete the temporary vector.
00078   delete [] temp_;
00079 }

template<typename CHAR_TYPE>
ACE_Arg_Shifter_T< CHAR_TYPE >::ACE_Arg_Shifter_T ( const ACE_Arg_Shifter_T< CHAR_TYPE > &   )  [private]

Copy Constructor should not be used.

Member Function Documentation

template<typename CHAR_TYPE>
int ACE_Arg_Shifter_T< CHAR_TYPE >::consume_arg ( int  number = 1  ) 

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

Definition at line 158 of file Arg_Shifter.cpp.

References ACE_Arg_Shifter_T< CHAR_TYPE >::argv_, ACE_Arg_Shifter_T< CHAR_TYPE >::back_, ACE_Arg_Shifter_T< CHAR_TYPE >::current_index_, and ACE_Arg_Shifter_T< CHAR_TYPE >::temp_.

Referenced by ACE_Arg_Shifter_T< CHAR_TYPE >::get_the_parameter().

00159 {
00160   int retval = 0;
00161 
00162   // Stick knowns at the end of the vector (consumed).
00163   if (this->is_anything_left() >= number)
00164     {
00165       for (int i = 0, j = this->back_ - (number - 1);
00166            i < number;
00167            ++i, ++j, ++this->current_index_)
00168         this->argv_[j] = this->temp_[this->current_index_];
00169 
00170       this->back_ -= number;
00171       retval = 1;
00172     }
00173 
00174   return retval;
00175 }

template<typename CHAR_TYPE>
int ACE_Arg_Shifter_T< CHAR_TYPE >::cur_arg_strncasecmp ( const CHAR_TYPE *  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 124 of file Arg_Shifter.cpp.

References ACE_TEXT, ACE_Arg_Shifter_T< CHAR_TYPE >::current_index_, ACE_OS::strlen(), ACE_OS::strncasecmp(), ACE_OS::strspn(), and ACE_Arg_Shifter_T< CHAR_TYPE >::temp_.

Referenced by ACE_Arg_Shifter_T< CHAR_TYPE >::get_the_parameter().

00125 {
00126   // Check for a current argument
00127   if (this->is_anything_left())
00128     {
00129       size_t const flag_length = ACE_OS::strlen (flag);
00130 
00131       // Check for presence of the flag
00132       if (ACE_OS::strncasecmp(this->temp_[current_index_],
00133                               flag,
00134                               flag_length) == 0)
00135         {
00136           if (ACE_OS::strlen(temp_[current_index_]) ==
00137               flag_length)
00138             {
00139               // match and lengths are equal
00140               return 0;
00141             }
00142           else
00143             {
00144               // matches, with more info to boot!
00145               size_t const remaining = ACE_OS::strspn
00146                 (this->temp_[current_index_] + flag_length,
00147                 ACE_TEXT (" ")) + flag_length;
00148               return static_cast<int> (remaining);
00149             }
00150         }
00151     }
00152   // failure
00153   return -1;
00154 }

template<typename CHAR_TYPE>
const CHAR_TYPE * ACE_Arg_Shifter_T< CHAR_TYPE >::get_current ( void   )  const

Get the current head of the vector.

Definition at line 83 of file Arg_Shifter.cpp.

References ACE_Arg_Shifter_T< CHAR_TYPE >::current_index_.

00084 {
00085   const CHAR_TYPE * retval = 0;
00086 
00087   if (this->is_anything_left ())
00088     retval =  this->temp_[current_index_];
00089 
00090   return retval;
00091 }

template<typename CHAR_TYPE>
const CHAR_TYPE * ACE_Arg_Shifter_T< CHAR_TYPE >::get_the_parameter ( const CHAR_TYPE *  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 95 of file Arg_Shifter.cpp.

References ACE_Arg_Shifter_T< CHAR_TYPE >::consume_arg(), ACE_Arg_Shifter_T< CHAR_TYPE >::cur_arg_strncasecmp(), ACE_Arg_Shifter_T< CHAR_TYPE >::current_index_, and ACE_Arg_Shifter_T< CHAR_TYPE >::temp_.

00096 {
00097   // the return 0's abound because this method
00098   // would otherwise be a deep if { } else { }
00099 
00100   // check to see if any arguments still exist
00101   if (!this->is_anything_left())
00102     return 0;
00103 
00104   // check to see if the flag is the argument
00105   int const offset = this->cur_arg_strncasecmp (flag);
00106   if (offset == -1)
00107     return 0;
00108 
00109   if (offset == 0)
00110     {
00111       this->consume_arg ();
00112 
00113       if (!this->is_parameter_next())
00114         {
00115           return 0;
00116         }
00117     }
00118   // the parameter is in the middle somewhere...
00119   return this->temp_[current_index_] + offset;
00120 }

template<typename CHAR_TYPE>
int ACE_Arg_Shifter_T< CHAR_TYPE >::ignore_arg ( int  number = 1  ) 

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

Definition at line 179 of file Arg_Shifter.cpp.

References ACE_Arg_Shifter_T< CHAR_TYPE >::current_index_, and ACE_Arg_Shifter_T< CHAR_TYPE >::front_.

00180 {
00181   int retval = 0;
00182 
00183   // Keep unknowns at the head of the vector.
00184   if (this->is_anything_left () >= number)
00185     {
00186       for (int i = 0;
00187            i < number;
00188            i++, this->current_index_++, this->front_++)
00189         this->argv_[this->front_] = this->temp_[this->current_index_];
00190 
00191       retval = 1;
00192       this->argc_ += number;
00193     }
00194 
00195   return retval;
00196 }

template<typename CHAR_TYPE>
void ACE_Arg_Shifter_T< CHAR_TYPE >::init ( void   )  [private]

Refactor the constructor logic.

Definition at line 49 of file Arg_Shifter.cpp.

References ACE_NEW, ACE_Arg_Shifter_T< CHAR_TYPE >::argc_, ACE_Arg_Shifter_T< CHAR_TYPE >::current_index_, ACE_Arg_Shifter_T< CHAR_TYPE >::front_, and ACE_Arg_Shifter_T< CHAR_TYPE >::total_size_.

Referenced by ACE_Arg_Shifter_T< CHAR_TYPE >::ACE_Arg_Shifter_T().

00050 {
00051   // If not provided with one, allocate a temporary array.
00052   if (this->temp_ == 0)
00053     ACE_NEW (this->temp_,
00054              const CHAR_TYPE *[this->total_size_]);
00055 
00056   if (this->temp_ != 0)
00057     {
00058       // Fill the temporary array.
00059       this->argc_ = 0;
00060       for (int i = 0; i < this->total_size_; i++)
00061         {
00062           this->temp_[i] = this->argv_[i];
00063           this->argv_[i] = 0;
00064         }
00065     }
00066   else
00067     {
00068       // Allocation failed, prohibit iteration.
00069       this->current_index_ = this->argc_;
00070       this->front_ = this->argc_;
00071     }
00072 }

template<typename CHAR_TYPE>
int ACE_Arg_Shifter_T< CHAR_TYPE >::is_anything_left ( void   )  const

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

Definition at line 200 of file Arg_Shifter.cpp.

References ACE_Arg_Shifter_T< CHAR_TYPE >::current_index_, and ACE_Arg_Shifter_T< CHAR_TYPE >::total_size_.

Referenced by ACE_Arg_Shifter_T< CHAR_TYPE >::is_option_next(), and ACE_Arg_Shifter_T< CHAR_TYPE >::is_parameter_next().

00201 {
00202   return this->total_size_ - this->current_index_;
00203 }

template<typename CHAR_TYPE>
int ACE_Arg_Shifter_T< CHAR_TYPE >::is_option_next ( void   )  const

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

Definition at line 207 of file Arg_Shifter.cpp.

References ACE_Arg_Shifter_T< CHAR_TYPE >::current_index_, ACE_Arg_Shifter_T< CHAR_TYPE >::is_anything_left(), and ACE_Arg_Shifter_T< CHAR_TYPE >::temp_.

00208 {
00209   return this->is_anything_left () &&
00210     this->temp_[this->current_index_][0] == '-';
00211 }

template<typename CHAR_TYPE>
int ACE_Arg_Shifter_T< CHAR_TYPE >::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 215 of file Arg_Shifter.cpp.

References ACE_Arg_Shifter_T< CHAR_TYPE >::current_index_, ACE_Arg_Shifter_T< CHAR_TYPE >::is_anything_left(), and ACE_Arg_Shifter_T< CHAR_TYPE >::temp_.

00216 {
00217   return this->is_anything_left ()
00218     && this->temp_[this->current_index_][0] != '-';
00219 }

template<typename CHAR_TYPE>
int ACE_Arg_Shifter_T< CHAR_TYPE >::num_ignored_args ( void   )  const

Returns the number of irrelevant args seen.

Definition at line 223 of file Arg_Shifter.cpp.

References ACE_Arg_Shifter_T< CHAR_TYPE >::front_.

00224 {
00225   return this->front_;
00226 }

template<typename CHAR_TYPE>
ACE_Arg_Shifter_T ACE_Arg_Shifter_T< CHAR_TYPE >::operator= ( const ACE_Arg_Shifter_T< CHAR_TYPE > &   )  [private]

Assignment '=' operator should not be used.

Member Data Documentation

template<typename CHAR_TYPE>
int& ACE_Arg_Shifter_T< CHAR_TYPE >::argc_ [private]

The size of the argument vector.

Definition at line 184 of file Arg_Shifter.h.

Referenced by ACE_Arg_Shifter_T< CHAR_TYPE >::init().

template<typename CHAR_TYPE>
const CHAR_TYPE** ACE_Arg_Shifter_T< CHAR_TYPE >::argv_ [private]

The array in which the arguments are reordered.

Definition at line 193 of file Arg_Shifter.h.

Referenced by ACE_Arg_Shifter_T< CHAR_TYPE >::consume_arg().

template<typename CHAR_TYPE>
int ACE_Arg_Shifter_T< CHAR_TYPE >::back_ [private]

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

Definition at line 200 of file Arg_Shifter.h.

Referenced by ACE_Arg_Shifter_T< CHAR_TYPE >::consume_arg().

template<typename CHAR_TYPE>
int ACE_Arg_Shifter_T< CHAR_TYPE >::current_index_ [private]

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

Definition at line 196 of file Arg_Shifter.h.

Referenced by ACE_Arg_Shifter_T< CHAR_TYPE >::consume_arg(), ACE_Arg_Shifter_T< CHAR_TYPE >::cur_arg_strncasecmp(), ACE_Arg_Shifter_T< CHAR_TYPE >::get_current(), ACE_Arg_Shifter_T< CHAR_TYPE >::get_the_parameter(), ACE_Arg_Shifter_T< CHAR_TYPE >::ignore_arg(), ACE_Arg_Shifter_T< CHAR_TYPE >::init(), ACE_Arg_Shifter_T< CHAR_TYPE >::is_anything_left(), ACE_Arg_Shifter_T< CHAR_TYPE >::is_option_next(), and ACE_Arg_Shifter_T< CHAR_TYPE >::is_parameter_next().

template<typename CHAR_TYPE>
int ACE_Arg_Shifter_T< CHAR_TYPE >::front_ [private]

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

Definition at line 204 of file Arg_Shifter.h.

Referenced by ACE_Arg_Shifter_T< CHAR_TYPE >::ignore_arg(), ACE_Arg_Shifter_T< CHAR_TYPE >::init(), and ACE_Arg_Shifter_T< CHAR_TYPE >::num_ignored_args().

template<typename CHAR_TYPE>
const CHAR_TYPE** ACE_Arg_Shifter_T< CHAR_TYPE >::temp_ [private]

The temporary array over which we traverse.

Definition at line 190 of file Arg_Shifter.h.

Referenced by ACE_Arg_Shifter_T< CHAR_TYPE >::consume_arg(), ACE_Arg_Shifter_T< CHAR_TYPE >::cur_arg_strncasecmp(), ACE_Arg_Shifter_T< CHAR_TYPE >::get_the_parameter(), ACE_Arg_Shifter_T< CHAR_TYPE >::is_option_next(), ACE_Arg_Shifter_T< CHAR_TYPE >::is_parameter_next(), and ACE_Arg_Shifter_T< CHAR_TYPE >::~ACE_Arg_Shifter_T().

template<typename CHAR_TYPE>
int ACE_Arg_Shifter_T< CHAR_TYPE >::total_size_ [private]

The size of argv_.

Definition at line 187 of file Arg_Shifter.h.

Referenced by ACE_Arg_Shifter_T< CHAR_TYPE >::init(), and ACE_Arg_Shifter_T< CHAR_TYPE >::is_anything_left().

The documentation for this class was generated from the following files:
Generated on Tue Feb 2 17:34:54 2010 for ACE by  doxygen 1.4.7