dep/ACE_wrappers/ace/Arg_Shifter.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file     Arg_Shifter.h
   6  *
   7  *  $Id: Arg_Shifter.h 80826 2008-03-04 14:51:23Z wotte $
   8  *
   9  *  @author Seth Widoff
  10  */
  11 //=============================================================================
  12
  13 #ifndef ACE_ARG_SHIFTER_H
  14 #define ACE_ARG_SHIFTER_H
  15
  16 #include /**/ "ace/pre.h"
  17
  18 #include /**/ "ace/ACE_export.h"
  19
  20 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  21 # pragma once
  22 #endif /* ACE_LACKS_PRAGMA_ONCE */
  23
  24 #include "ace/Global_Macros.h"
  25
  26 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  27
  28 /**
  29  * @class ACE_Arg_Shifter_T
  30  *
  31  * @brief This ADT operates on a specified set of arguments (@a argv).
  32  * As known arguments are scanned, they are shifted to the back of the
  33  * @a argv vector, so deeper levels of argument parsing can locate the yet
  34  * unprocessed arguments at the beginning of the vector.
  35  *
  36  * The @c ACE_Arg_Shifter copies the pointers of the @a argv vector
  37  * into a temporary array. As the @c ACE_Arg_Shifter iterates over
  38  * the copied vector, it places known arguments in the rear of the
  39  * vector, leaving the unknown ones in the beginning. So, after having
  40  * visited all the arguments in the temporary vector, @c ACE_Arg_Shifter
  41  * has placed all the unknown arguments in their original order at
  42  * the front of original @a argv.
  43  */
  44 template <typename CHAR_TYPE>
  45 class ACE_Arg_Shifter_T
  46 {
  47 public:
  48   // = Initialization and termination methods.
  49   /**
  50    * Initialize the ACE_Arg_Shifter to the vector over which to
  51    * iterate. Optionally, also provide the temporary array for
  52    * use in shifting the arguments. If ACE_Arg_Shifter must allocate
  53    * the temporary vector internally and dynamic allocation fails, the
  54    * ACE_Arg_Shifter will set all indicators to end of the vector,
  55    * forbidding iteration. Following iteration over @a argv, the
  56    * @a argc value will be updated to contain the number of
  57    * unconsumed arguments.
  58    * @param argc The number of strings in @a argv. @a argc will be
  59    *    updated to reflect the number of unconsumed arguments.
  60    * @param argv The argument vector to shift. The string pointers in
  61    *    the vector will be reordered to place the @a argc unconsumed
  62    *    arguments at the front of the vector.
  63    * @param temp A vector of @c CHAR_TYPE pointers at least @a argc
  64    *    elements long. The vector will be used for argument shifting as
  65    *    the specified @a argv vector is consumed. The vector must not
  66    *    be modified while this object exists. If this argument is 0
  67    *    (the default) the object will allocate and free the temporary
  68    *    vector transparently.
  69    */
  70   ACE_Arg_Shifter_T (int& argc,
  71                      const CHAR_TYPE **argv,
  72                      const CHAR_TYPE **temp = 0);
  73
  74   /// Same behavior as the preceding constructor, but without the
  75   /// "const" qualifier.
  76   ACE_Arg_Shifter_T (int& argc,
  77                      CHAR_TYPE **argv,
  78                      CHAR_TYPE **temp = 0);
  79
  80   /// Destructor.
  81   ~ACE_Arg_Shifter_T (void);
  82
  83   /// Get the current head of the vector.
  84   const CHAR_TYPE *get_current (void) const;
  85
  86   /**
  87    * If the @a flag matches the current_arg of arg shifter
  88    * this method will attempt to return the associated
  89    * parameter value
  90    *
  91    * Safe to call without checking that a current arg exists
  92    *
  93    * In the following examples, a pointer to the char* "value" is ret
  94    *
  95    * eg: main -foobar value, main -FooBar value
  96    *     main -FOOBARvalue
  97    *
  98    *     all of the above will all match the @a flag == -FooBar
  99    *     and will return a char* to "value"
 100    *
 101    *     main -foobar 4 would succeed and return a char* to "4"
 102    *     main -foobar -4 does not succeed (-4 is not a parameter)
 103    *          but instead, would return 0
 104    *
 105    * 0 is returned:
 106    *     If the current argument does not match flag
 107    *     If there is no parameter found after a 'matched' flag
 108    *
 109    * If the flag is matched and the flag and paramter DO NOT RUN
 110    * together, the flag is consumed, the parameter is returned,
 111    * and the new current argument is the parameter value.
 112    * ie '-foobarflag  VALUE' leaves the new cur arg == "VALUE"
 113    *
 114    * If the flag is matched and the flag and parameter RUN
 115    * together '-foobarflagVALUE', the flag is NOT consumed
 116    * and the cur arg is left pointing to the entire flag/value pair
 117    */
 118   const CHAR_TYPE *get_the_parameter (const CHAR_TYPE* flag);
 119
 120   /**
 121    * Check if the current argument matches (case insensitive) <flag>
 122    *
 123    * ------------------------------------------------------------
 124    *
 125    * Case A: Perfect Match (case insensitive)
 126    * 0 is returned.
 127    *
 128    *     ie: when current_arg = "-foobar" or "-FOOBAR" or "-fooBAR"
 129    *         this->cur_arg_strncasecmp ("-FooBar);
 130    *         will return 0
 131    *
 132    * ------------------------------------------------------------
 133    *
 134    * Case B: Perfect Match (case insensitive) but the current_arg
 135    * is longer than the flag. Returns a number equal to the index
 136    * in the char* indicating the start of the extra characters
 137    *
 138    *     ie: when current_arg = "-foobar98023"
 139    *         this->cur_arg_strncasecmp ("-FooBar);
 140    *         will return 7
 141    *
 142    * Notice: this number will always be > 0
 143    *
 144    * ------------------------------------------------------------
 145    *
 146    * Case C: If neither of Case A or B is met (no match)
 147    * then -1 is returned
 148    */
 149   int cur_arg_strncasecmp (const CHAR_TYPE *flag);
 150
 151   /// Consume @a number argument(s) by sticking them/it on the end of
 152   /// the vector.
 153   int consume_arg (int number = 1);
 154
 155   /// Place @a number arguments in the same relative order ahead of the
 156   /// known arguments in the vector.
 157   int ignore_arg (int number = 1);
 158
 159   /// Returns the number of args left to see in the vector.
 160   int is_anything_left (void) const;
 161
 162   /// Returns 1 if there's a next item in the vector and it begins with
 163   /// '-'.
 164   int is_option_next (void) const;
 165
 166   /// Returns 1 if there's a next item in the vector and it doesn't
 167   /// begin with '-'.
 168   int is_parameter_next (void) const;
 169
 170   /// Returns the number of irrelevant args seen.
 171   int num_ignored_args (void) const;
 172
 173 private:
 174   /// Copy Constructor should not be used.
 175   ACE_UNIMPLEMENTED_FUNC (ACE_Arg_Shifter_T (const ACE_Arg_Shifter_T<CHAR_TYPE>&))
 176
 177   /// Assignment '=' operator should not be used.
 178   ACE_UNIMPLEMENTED_FUNC (ACE_Arg_Shifter_T operator= (const ACE_Arg_Shifter_T<CHAR_TYPE>&))
 179
 180   /// Refactor the constructor logic.
 181   void init (void);
 182
 183   /// The size of the argument vector.
 184   int& argc_;
 185
 186   /// The size of argv_.
 187   int total_size_;
 188
 189   /// The temporary array over which we traverse.
 190   const CHAR_TYPE **temp_;
 191
 192   /// The array in which the arguments are reordered.
 193   const CHAR_TYPE **argv_;
 194
 195   /// The element in <temp_> we're currently examining.
 196   int current_index_;
 197
 198   /// The index of <argv_> in which we'll stick the next unknown
 199   /// argument.
 200   int back_;
 201
 202   /// The index of <argv_> in which we'll stick the next known
 203   /// argument.
 204   int front_;
 205 };
 206
 207 typedef ACE_Arg_Shifter_T<ACE_TCHAR> ACE_Arg_Shifter;
 208
 209 ACE_END_VERSIONED_NAMESPACE_DECL
 210
 211 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
 212 #include "ace/Arg_Shifter.cpp"
 213 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
 214
 215 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
 216 #pragma implementation ("Arg_Shifter.cpp")
 217 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
 218
 219 #include /**/ "ace/post.h"
 220
 221 #endif /* ACE_ARG_SHIFTER_H */