ACE/ace/ARGV.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    ARGV.h
   6  *
   7  *  @author Doug Schmidt <d.schmidt@vanderbilt.edu>
   8  *  @author Everett Anderson <eea1@cs.wustl.edu>
   9  */
  10 //==========================================================================
  11
  12 #ifndef ACE_ARGUMENT_VECTOR_H
  13 #define ACE_ARGUMENT_VECTOR_H
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/ACE_export.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "ace/Global_Macros.h"
  23 #include "ace/Unbounded_Queue.h"
  24
  25 // Open versioned namespace, if enabled by the user.
  26 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  27
  28 /**
  29  * @class ACE_ARGV_Queue_Entry_T
  30  *
  31  * @brief An entry in the queue which keeps user supplied arguments.
  32  */
  33 template <typename CHAR_TYPE>
  34 class ACE_ARGV_Queue_Entry_T
  35 {
  36 public:
  37   /// Initialize a ACE_ARGV_Queue_Entry_T.
  38   ACE_ARGV_Queue_Entry_T ();
  39
  40   /**
  41    * Initialize a ACE_ARGV_Queue_Entry_T.
  42    *
  43    * @param arg   Pointer to an argument
  44    *
  45    * @param quote_arg The argument @a arg need to be quoted
  46    *              while adding to the vector.
  47    */
  48   ACE_ARGV_Queue_Entry_T (const CHAR_TYPE *arg,
  49                           bool quote_arg);
  50
  51   /**
  52    * Initialize a ACE_ARGV_Queue_Entry_T.
  53    *
  54    * @param entry Pointer to a queue entry
  55    */
  56   ACE_ARGV_Queue_Entry_T (const ACE_ARGV_Queue_Entry_T<CHAR_TYPE> &entry);
  57
  58   ACE_ARGV_Queue_Entry_T (ACE_ARGV_Queue_Entry_T&&) = default;
  59   ACE_ARGV_Queue_Entry_T &operator = (const ACE_ARGV_Queue_Entry_T &) = default;
  60   ACE_ARGV_Queue_Entry_T &operator = (ACE_ARGV_Queue_Entry_T &&)  = default;
  61
  62   /// We need this destructor to keep some compilers from complaining.
  63   /// It's just a no-op, however.
  64   ~ACE_ARGV_Queue_Entry_T () = default;
  65
  66   /// Dump the state of this object.
  67   void dump () const;
  68
  69   // Declare the dynamic allocation hooks.
  70   ACE_ALLOC_HOOK_DECLARE;
  71
  72   /// Pointer to the argument.
  73   const CHAR_TYPE * arg_;
  74
  75   /// The argument need to be quoted while adding to the vector.
  76   bool quote_arg_;
  77 };
  78
  79 /**
  80  * @class ACE_ARGV_T
  81  *
  82  * @brief Builds a counted argument vector (ala argc/argv) from either
  83  * a string or a set of separate tokens. This class preserves whitespace
  84  * within tokens only if the whitespace-containing token is enclosed in
  85  * either single (') or double (") quotes. This is consistent with the
  86  * expected behavior if an argument vector obtained using this class is
  87  * passed to, for example, ACE_Get_Opt.
  88  *
  89  * This class can substitute environment variable values for tokens that
  90  * are environment variable references (e.g., @c $VAR). This only works
  91  * if the token is an environment variable reference and nothing else; it
  92  * doesn't substitute environment variable references within a token.
  93  * For example, @c $HOME/file will not substitute the value of the HOME
  94  * environment variable.
  95  */
  96 template <typename CHAR_TYPE>
  97 class ACE_ARGV_T
  98 {
  99 public:
 100   /**
 101    * Splits the specified string into an argument vector. Arguments in the
 102    * string are delimited by whitespace. Whitespace-containing arguments
 103    * must be enclosed in quotes, either single (') or double (").
 104    *
 105    * @param buf   A nul-terminated CHAR_TYPE array to split into arguments
 106    *              for the vector.
 107    *
 108    * @param substitute_env_args  If non-zero, any token that is an
 109    *              environment variable reference (e.g., @c $VAR) will have
 110    *              its environment variable value in the resultant vector
 111    *              in place of the environment variable name.
 112    */
 113   explicit ACE_ARGV_T (const CHAR_TYPE buf[],
 114                        bool substitute_env_args = true);
 115
 116   /**
 117    * Initializes the argument vector from a set of arguments. Any environment
 118    * variable references are translated (if applicable) during execution of
 119    * this method. In contrast with ACE_ARGV_T(CHAR_TYPE *[], bool, bool), this
 120    * ctor does not require argv to be 0-terminated as the number of arguments
 121    * is provided explicitely.
 122    *
 123    * @param argc  The number of arguments in the argv array.
 124    *
 125    * @param argv  An array of tokens to initialize the object with. All needed
 126    *              data is copied from @a argv during this call; the pointers
 127    *              in @a argv are not needed after this call, and the memory
 128    *              referred to by @a argv is not referenced by this object.
 129    *
 130    * @param substitute_env_args  If non-zero, any element of @a argv that is
 131    *              an environment variable reference (e.g., @c $VAR) will have
 132    *              its environment variable value in the resultant vector
 133    *              in place of the environment variable name.
 134    *
 135    * @param quote_args  If non-zero each argument @a argv[i] needs to
 136    *                    be enclosed in double quotes ('"').
 137    */
 138   explicit ACE_ARGV_T (int argc,
 139                        CHAR_TYPE *argv[],
 140                        bool substitute_env_args = true,
 141                        bool quote_args = false);
 142
 143   /**
 144    * Initializes the argument vector from a set of arguments. Any environment
 145    * variable references are translated (if applicable) during execution of
 146    * this method.
 147    *
 148    * @param argv  An array of tokens to initialize the object with. The
 149    *              array must be terminated with a 0 pointer. All needed
 150    *              data is copied from @a argv during this call; the pointers
 151    *              in @a argv are not needed after this call, and the memory
 152    *              referred to by @a argv is not referenced by this object.
 153    *
 154    * @param substitute_env_args  If non-zero, any element of @a argv that is
 155    *              an environment variable reference (e.g., @c $VAR) will have
 156    *              its environment variable value in the resultant vector
 157    *              in place of the environment variable name.
 158    *
 159    * @param quote_args  If non-zero each argument @a argv[i] needs to
 160    *                    be enclosed in double quotes ('"').
 161    */
 162   explicit ACE_ARGV_T (CHAR_TYPE *argv[],
 163                        bool substitute_env_args = true,
 164                        bool quote_args = false);
 165
 166   /**
 167    * Initializes the argument vector from two combined argument vectors.
 168    *
 169    * @param first_argv   An array of tokens to initialize the object with.
 170    *                     The array must be terminated with a 0 pointer.
 171    * @param second_argv  An array of tokens that is concatenated with the
 172    *                     the tokens in @a first_argv. The array must be
 173    *                     terminated with a 0 pointer.
 174    * @param substitute_env_args  If non-zero, any element of @a first_argv
 175    *              or @a second_argv that is an environment variable
 176    *              reference (e.g., @c $VAR) will have its environment
 177    *              variable value in the resultant vector in place
 178    *              of the environment variable name.
 179    *
 180    * @param quote_args  If non-zero each arguments @a first_argv[i] and
 181    *                    @a second_argv[i] needs to be enclosed
 182    *                    in double quotes ('"').
 183    */
 184   ACE_ARGV_T (CHAR_TYPE *first_argv[],
 185               CHAR_TYPE *second_argv[],
 186               bool substitute_env_args = true,
 187               bool quote_args = false);
 188
 189   /**
 190    * Initialize this object so arguments can be added later using one
 191    * of the add methods. This is referred to as the @i iterative method
 192    * of adding arguments to this object.
 193    */
 194   explicit ACE_ARGV_T (bool substitute_env_args = true);
 195
 196   /// Destructor.
 197   ~ACE_ARGV_T ();
 198
 199   /** @name Accessor methods
 200    *
 201    * These methods access the argument vector contained in this object.
 202    */
 203   //@{
 204   /**
 205    * Returns the specified element of the current argument vector.
 206    *
 207    * @param index   Index to the desired element.
 208    *
 209    * @retval Pointer to the indexed string.
 210    * @retval 0 if @a index is out of bounds.
 211    */
 212   const CHAR_TYPE *operator[] (size_t index);
 213
 214   /**
 215    * Returns the current argument vector. The returned pointers are to data
 216    * maintained internally to this class. Do not change or delete either the
 217    * pointers or the memory to which they refer.
 218    */
 219   CHAR_TYPE **argv ();
 220
 221   /// Returns the current number of arguments.
 222   int argc () const;
 223
 224   /**
 225    * Returns a single string form of the current arguments. The returned
 226    * pointer refers to memory maintained internally to this class. Do not
 227    * change or delete it.
 228    */
 229   const CHAR_TYPE *buf ();
 230
 231   //@}
 232
 233   /// Dump the state of this object.
 234   void dump () const;
 235
 236   // Declare the dynamic allocation hooks.
 237   ACE_ALLOC_HOOK_DECLARE;
 238
 239   /**
 240    * Add another argument. This only works in the iterative mode.
 241    *
 242    * @note This method copies the specified pointer, but not the data
 243    *       contained in the referenced memory. Thus, if the content of
 244    *       the memory referred to by @a next_arg are changed after this
 245    *       method returns, the results are undefined.
 246    *
 247    * @param next_arg    Pointer to the next argument to add to the vector.
 248    *
 249    * @param quote_arg   The argument @a next_arg need to be quoted while
 250    *                    adding to the vector.
 251    *
 252    * @retval 0 on success; -1 on failure. Most likely @c errno values are:
 253    *       - EINVAL: This object is not in iterative mode.
 254    *       - ENOMEM: Not enough memory available to save @a next_arg.
 255    */
 256   int add (const CHAR_TYPE *next_arg, bool quote_arg = false);
 257
 258   /**
 259    * Add an array of arguments. This only works in the iterative mode.
 260    *
 261    * @note This method copies the specified pointers, but not the data
 262    *       contained in the referenced memory. Thus, if the content of
 263    *       the memory referred to by any of the @a argv elements is
 264    *       changed after this method returns, the results are undefined.
 265    *
 266    * @param argv    Pointers to the arguments to add to the vector.
 267    *                @a argv must be terminated by a 0 pointer.
 268    *
 269    * @param quote_args  If non-zero each argument @a argv[i] needs to
 270    *                    be enclosed in double quotes ('"').
 271    *
 272    * @retval 0 on success; -1 on failure. Most likely @c errno values are:
 273    *       - EINVAL: This object is not in iterative mode.
 274    *       - ENOMEM: Not enough memory available to save @a next_arg.
 275    */
 276   int add (CHAR_TYPE *argv[], bool quote_args = false);
 277
 278 private:
 279   ACE_ARGV_T (const ACE_ARGV_T<CHAR_TYPE>&) = delete;
 280   ACE_ARGV_T operator= (const ACE_ARGV_T<CHAR_TYPE>&) = delete;
 281   ACE_ARGV_T (ACE_ARGV_T<CHAR_TYPE>&&) = delete;
 282   ACE_ARGV_T operator= (ACE_ARGV_T<CHAR_TYPE>&&) = delete;
 283
 284   /// Creates buf_ from the queue of added args, deletes previous buf_.
 285   int create_buf_from_queue ();
 286
 287   /// Converts buf_ into the CHAR_TYPE *argv[] format.
 288   int string_to_argv ();
 289
 290   /// Replace args with environment variable values?
 291   bool substitute_env_args_;
 292
 293   bool iterative_;
 294
 295   /// Number of arguments in the ARGV array.
 296   int argc_;
 297
 298   /// The array of string arguments.
 299   CHAR_TYPE **argv_;
 300
 301   /// Buffer containing the argv contents.
 302   CHAR_TYPE *buf_;
 303
 304   /// Total length of the arguments in the queue, not counting
 305   /// separating spaces
 306   size_t length_;
 307
 308   /// Queue which keeps user supplied arguments.  This is only
 309   /// active in the "iterative" mode.
 310   ACE_Unbounded_Queue<ACE_ARGV_Queue_Entry_T<CHAR_TYPE> > queue_;
 311 };
 312
 313 typedef ACE_ARGV_Queue_Entry_T<ACE_TCHAR> ACE_ARGV_Queue_Entry;
 314 typedef ACE_ARGV_T<ACE_TCHAR> ACE_ARGV;
 315
 316 // Close versioned namespace, if enabled by the user.
 317 ACE_END_VERSIONED_NAMESPACE_DECL
 318
 319 #if defined (__ACE_INLINE__)
 320 #include "ace/ARGV.inl"
 321 #endif /* __ACE_INLINE__ */
 322
 323 #include "ace/ARGV.cpp"
 324
 325 #include /**/ "ace/post.h"
 326 #endif /* ACE_ARGUMENT_VECTOR_H */