ACE  6.3.3
Public Member Functions | Private Member Functions | Private Attributes | List of all members
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>

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. More...
 
const CHAR_TYPE * get_current (void) const
 Get the current head of the vector. More...
 
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. More...
 
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. More...
 

Private Member Functions

 ACE_Arg_Shifter_T (const ACE_Arg_Shifter_T< CHAR_TYPE > &)
 Copy Constructor should not be used. More...
 
ACE_Arg_Shifter_T operator= (const ACE_Arg_Shifter_T< CHAR_TYPE > &)
 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 CHAR_TYPE ** temp_
 The temporary array over which we traverse. More...
 
const CHAR_TYPE ** argv_
 The array in which the arguments are reordered. More...
 
int current_index_
 The element in <temp_> we're currently examining. More...
 
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.

Nomenclature: argument - a member of the argv array option - an argument starting with '-' flag - synonym for "option" parameter value - an argument not starting with '-' parameter - synonym for "parameter value"

The ACE_Arg_Shifter copies the pointers of the argv vector into a temporary array, emptying the original. As the ACE_Arg_Shifter iterates over the temporary array, it places known arguments in the rear of the original array and places the unknown ones in the beginning of the original array. It modifies argc to be the number of unknown arguments, so it looks to the caller as if the original array contains only unknown arguments. So, after ACE_Arg_Shifter has visited all the arguments in the temporary array, the original argv array appears to contain only the unknown arguments in their original order (but it actually has all the known arguments, too, beyond argc).

Constructor & Destructor Documentation

template<typename CHAR_TYPE >
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
argcThe number of strings in argv. argc will be updated to reflect the number of unconsumed arguments.
argvThe 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.
tempA 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.
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.

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

Destructor.

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.

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

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

Get the current head of the vector.

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 parameter 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

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.

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

Refactor the constructor logic.

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.

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 '-'.

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 '-'.

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

Returns the number of irrelevant args seen.

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.

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

The array in which the arguments are reordered.

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.

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

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

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. This is not really the "front" at all. It's the point after which the unknown arguments end and at which the known arguments begin.

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

The temporary array over which we traverse.

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

The size of argv_.


The documentation for this class was generated from the following files: