00001 // -*- C++ -*- 00002 00003 //========================================================================== 00004 /** 00005 * @file ARGV.h 00006 * 00007 * $Id: ARGV.h 81156 2008-03-30 20:56:47Z iliyan $ 00008 * 00009 * @author Doug Schmidt <schmidt@cs.wustl.edu> 00010 * @author Everett Anderson <eea1@cs.wustl.edu> 00011 */ 00012 //========================================================================== 00013 00014 #ifndef ACE_ARGUMENT_VECTOR_H 00015 #define ACE_ARGUMENT_VECTOR_H 00016 #include /**/ "ace/pre.h" 00017 00018 #include /**/ "ace/ACE_export.h" 00019 00020 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00021 # pragma once 00022 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00023 00024 #include "ace/Global_Macros.h" 00025 #include "ace/Unbounded_Queue.h" 00026 00027 // Open versioned namespace, if enabled by the user. 00028 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00029 00030 /** 00031 * @class ACE_ARGV_Queue_Entry_T 00032 * 00033 * @brief An entry in the queue which keeps user supplied arguments. 00034 */ 00035 template <typename CHAR_TYPE> 00036 class ACE_ARGV_Queue_Entry_T 00037 { 00038 public: 00039 // = Initialization and termination. 00040 /// Initialize a ACE_ARGV_Queue_Entry_T. 00041 ACE_ARGV_Queue_Entry_T (void); 00042 00043 /** 00044 * Initialize a ACE_ARGV_Queue_Entry_T. 00045 * 00046 * @param arg Pointer to an argument 00047 * 00048 * @param quote_arg The argument @a arg need to be quoted 00049 * while adding to the vector. 00050 */ 00051 ACE_ARGV_Queue_Entry_T (const CHAR_TYPE *arg, 00052 bool quote_arg); 00053 00054 /** 00055 * Initialize a ACE_ARGV_Queue_Entry_T. 00056 * 00057 * @param entry Pointer to a queue entry 00058 */ 00059 ACE_ARGV_Queue_Entry_T (const ACE_ARGV_Queue_Entry_T<CHAR_TYPE> &entry); 00060 00061 /// We need this destructor to keep some compilers from complaining. 00062 /// It's just a no-op, however. 00063 ~ACE_ARGV_Queue_Entry_T (void); 00064 00065 /// Dump the state of this object. 00066 void dump (void) const; 00067 00068 // Declare the dynamic allocation hooks. 00069 ACE_ALLOC_HOOK_DECLARE; 00070 00071 /// Pointer to the argument. 00072 const CHAR_TYPE * arg_; 00073 00074 /// The argument need to be quoted while adding to the vector. 00075 bool quote_arg_; 00076 }; 00077 00078 /** 00079 * @class ACE_ARGV_T 00080 * 00081 * @brief Builds a counted argument vector (ala argc/argv) from either 00082 * a string or a set of separate tokens. This class preserves whitespace 00083 * within tokens only if the whitespace-containing token is enclosed in 00084 * either single (') or double (") quotes. This is consistent with the 00085 * expected behavior if an argument vector obtained using this class is 00086 * passed to, for example, ACE_Get_Opt. 00087 * 00088 * This class can substitute environment variable values for tokens that 00089 * are environment variable references (e.g., @c $VAR). This only works 00090 * if the token is an environment variable reference and nothing else; it 00091 * doesn't substitute environment variable references within a token. 00092 * For example, @c $HOME/file will not substitute the value of the HOME 00093 * environment variable. 00094 */ 00095 template <typename CHAR_TYPE> 00096 class ACE_ARGV_T 00097 { 00098 public: 00099 // = Initialization and termination. 00100 /** 00101 * Splits the specified string into an argument vector. Arguments in the 00102 * string are delimited by whitespace. Whitespace-containing arguments 00103 * must be enclosed in quotes, either single (') or double ("). 00104 * 00105 * @param buf A nul-terminated CHAR_TYPE array to split into arguments 00106 * for the vector. 00107 * 00108 * @param substitute_env_args If non-zero, any token that is an 00109 * environment variable reference (e.g., @c $VAR) will have 00110 * its environment variable value in the resultant vector 00111 * in place of the environment variable name. 00112 */ 00113 explicit ACE_ARGV_T (const CHAR_TYPE buf[], 00114 bool substitute_env_args = true); 00115 00116 /** 00117 * Initializes the argument vector from a set of arguments. Any environment 00118 * variable references are translated (if applicable) during execution of 00119 * this method. In contrast with ACE_ARGV_T(CHAR_TYPE *[], bool, bool), this 00120 * ctor does not require argv to be 0-terminated as the number of arguments 00121 * is provided explicitely. 00122 * 00123 * @param argc The number of arguments in the argv array. 00124 * 00125 * @param argv An array of tokens to initialize the object with. All needed 00126 * data is copied from @a argv during this call; the pointers 00127 * in @a argv are not needed after this call, and the memory 00128 * referred to by @a argv is not referenced by this object. 00129 * 00130 * @param substitute_env_args If non-zero, any element of @a argv that is 00131 * an environment variable reference (e.g., @c $VAR) will have 00132 * its environment variable value in the resultant vector 00133 * in place of the environment variable name. 00134 * 00135 * @param quote_args If non-zero each argument @a argv[i] needs to 00136 * be enclosed in double quotes ('"'). 00137 */ 00138 explicit ACE_ARGV_T (int argc, 00139 CHAR_TYPE *argv[], 00140 bool substitute_env_args = true, 00141 bool quote_args = false); 00142 00143 /** 00144 * Initializes the argument vector from a set of arguments. Any environment 00145 * variable references are translated (if applicable) during execution of 00146 * this method. 00147 * 00148 * @param argv An array of tokens to initialize the object with. The 00149 * array must be terminated with a 0 pointer. All needed 00150 * data is copied from @a argv during this call; the pointers 00151 * in @a argv are not needed after this call, and the memory 00152 * referred to by @a argv is not referenced by this object. 00153 * 00154 * @param substitute_env_args If non-zero, any element of @a argv that is 00155 * an environment variable reference (e.g., @c $VAR) will have 00156 * its environment variable value in the resultant vector 00157 * in place of the environment variable name. 00158 * 00159 * @param quote_args If non-zero each argument @a argv[i] needs to 00160 * be enclosed in double quotes ('"'). 00161 */ 00162 explicit ACE_ARGV_T (CHAR_TYPE *argv[], 00163 bool substitute_env_args = true, 00164 bool quote_args = false); 00165 00166 /** 00167 * Initializes the argument vector from two combined argument vectors. 00168 * 00169 * @param first_argv An array of tokens to initialize the object with. 00170 * The array must be terminated with a 0 pointer. 00171 * @param second_argv An array of tokens that is concatenated with the 00172 * the tokens in @a first_argv. The array must be 00173 * terminated with a 0 pointer. 00174 * @param substitute_env_args If non-zero, any element of @a first_argv 00175 * or @a second_argv that is an environment variable 00176 * reference (e.g., @c $VAR) will have its environment 00177 * variable value in the resultant vector in place 00178 * of the environment variable name. 00179 * 00180 * @param quote_args If non-zero each arguments @a first_argv[i] and 00181 * @a second_argv[i] needs to be enclosed 00182 * in double quotes ('"'). 00183 */ 00184 ACE_ARGV_T (CHAR_TYPE *first_argv[], 00185 CHAR_TYPE *second_argv[], 00186 bool substitute_env_args = true, 00187 bool quote_args = false); 00188 00189 /** 00190 * Initialize this object so arguments can be added later using one 00191 * of the add methods. This is referred to as the @i iterative method 00192 * of adding arguments to this object. 00193 */ 00194 explicit ACE_ARGV_T (bool substitute_env_args = true); 00195 00196 /// Destructor. 00197 ~ACE_ARGV_T (void); 00198 00199 /** @name Accessor methods 00200 * 00201 * These methods access the argument vector contained in this object. 00202 */ 00203 //@{ 00204 /** 00205 * Returns the specified element of the current argument vector. 00206 * 00207 * @param index Index to the desired element. 00208 * 00209 * @retval Pointer to the indexed string. 00210 * @retval 0 if @a index is out of bounds. 00211 */ 00212 const CHAR_TYPE *operator[] (size_t index); 00213 00214 /** 00215 * Returns the current argument vector. The returned pointers are to data 00216 * maintained internally to this class. Do not change or delete either the 00217 * pointers or the memory to which they refer. 00218 */ 00219 CHAR_TYPE **argv (void); 00220 00221 /// Returns the current number of arguments. 00222 int argc (void) const; 00223 00224 /** 00225 * Returns a single string form of the current arguments. The returned 00226 * pointer refers to memory maintained internally to this class. Do not 00227 * change or delete it. 00228 */ 00229 const CHAR_TYPE *buf (void); 00230 00231 //@} 00232 00233 /// Dump the state of this object. 00234 void dump (void) const; 00235 00236 // Declare the dynamic allocation hooks. 00237 ACE_ALLOC_HOOK_DECLARE; 00238 00239 /** 00240 * Add another argument. This only works in the iterative mode. 00241 * 00242 * @note This method copies the specified pointer, but not the data 00243 * contained in the referenced memory. Thus, if the content of 00244 * the memory referred to by @a next_arg are changed after this 00245 * method returns, the results are undefined. 00246 * 00247 * @param next_arg Pointer to the next argument to add to the vector. 00248 * 00249 * @param quote_arg The argument @a next_arg need to be quoted while 00250 * adding to the vector. 00251 * 00252 * @retval 0 on success; -1 on failure. Most likely @c errno values are: 00253 * - EINVAL: This object is not in iterative mode. 00254 * - ENOMEM: Not enough memory available to save @a next_arg. 00255 */ 00256 int add (const CHAR_TYPE *next_arg, bool quote_arg = false); 00257 00258 /** 00259 * Add an array of arguments. This only works in the iterative mode. 00260 * 00261 * @note This method copies the specified pointers, but not the data 00262 * contained in the referenced memory. Thus, if the content of 00263 * the memory referred to by any of the @a argv elements is 00264 * changed after this method returns, the results are undefined. 00265 * 00266 * @param argv Pointers to the arguments to add to the vector. 00267 * @a argv must be terminated by a 0 pointer. 00268 * 00269 * @param quote_args If non-zero each argument @a argv[i] needs to 00270 * be enclosed in double quotes ('"'). 00271 * 00272 * @retval 0 on success; -1 on failure. Most likely @c errno values are: 00273 * - EINVAL: This object is not in iterative mode. 00274 * - ENOMEM: Not enough memory available to save @a next_arg. 00275 */ 00276 int add (CHAR_TYPE *argv[], bool quote_args = false); 00277 00278 private: 00279 /// Copy constructor not implemented. 00280 ACE_UNIMPLEMENTED_FUNC (ACE_ARGV_T (const ACE_ARGV_T<CHAR_TYPE>&)) 00281 00282 /// Assignment operator not implemented. 00283 ACE_UNIMPLEMENTED_FUNC (ACE_ARGV_T operator= (const ACE_ARGV_T<CHAR_TYPE>&)) 00284 00285 /// Creates buf_ from the queue of added args, deletes previous buf_. 00286 int create_buf_from_queue (void); 00287 00288 /// Converts buf_ into the CHAR_TYPE *argv[] format. 00289 int string_to_argv (void); 00290 00291 /// Replace args with environment variable values? 00292 bool substitute_env_args_; 00293 00294 bool iterative_; 00295 00296 /// Number of arguments in the ARGV array. 00297 int argc_; 00298 00299 /// The array of string arguments. 00300 CHAR_TYPE **argv_; 00301 00302 /// Buffer containing the <argv> contents. 00303 CHAR_TYPE *buf_; 00304 00305 /// Total length of the arguments in the queue, not counting 00306 /// separating spaces 00307 size_t length_; 00308 00309 /// Queue which keeps user supplied arguments. This is only 00310 /// active in the "iterative" mode. 00311 ACE_Unbounded_Queue<ACE_ARGV_Queue_Entry_T<CHAR_TYPE> > queue_; 00312 }; 00313 00314 typedef ACE_ARGV_Queue_Entry_T<ACE_TCHAR> ACE_ARGV_Queue_Entry; 00315 typedef ACE_ARGV_T<ACE_TCHAR> ACE_ARGV; 00316 00317 // Close versioned namespace, if enabled by the user. 00318 ACE_END_VERSIONED_NAMESPACE_DECL 00319 00320 #if defined (__ACE_INLINE__) 00321 #include "ace/ARGV.inl" 00322 #endif /* __ACE_INLINE__ */ 00323 00324 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) 00325 #include "ace/ARGV.cpp" 00326 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */ 00327 00328 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA) 00329 #pragma implementation ("ARGV.cpp") 00330 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */ 00331 00332 #include /**/ "ace/post.h" 00333 #endif /* ACE_ARGUMENT_VECTOR_H */