00001 // -*- C++ -*- 00002 00003 //========================================================================== 00004 /** 00005 * @file ARGV.h 00006 * 00007 * ARGV.h,v 4.39 2006/06/09 10:08:48 jwillemsen Exp 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/Unbounded_Queue.h" 00025 00026 // Open versioned namespace, if enabled by the user. 00027 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00028 00029 /** 00030 * @class ACE_ARGV_T 00031 * 00032 * @brief Builds a counted argument vector (ala argc/argv) from either 00033 * a string or a set of separate tokens. This class preserves whitespace 00034 * within tokens only if the whitespace-containing token is enclosed in 00035 * either single (') or double (") quotes. This is consistent with the 00036 * expected behavior if an argument vector obtained using this class is 00037 * passed to, for example, ACE_Get_Opt. 00038 * 00039 * This class can substitute environment variable values for tokens that 00040 * are environment variable references (e.g., @c $VAR). This only works 00041 * if the token is an environment variable reference and nothing else; it 00042 * doesn't substitute environment variable references within a token. 00043 * For example, @c $HOME/file will not substitute the value of the HOME 00044 * environment variable. 00045 */ 00046 template <typename CHAR_TYPE> 00047 class ACE_ARGV_T 00048 { 00049 public: 00050 // = Initialization and termination. 00051 /** 00052 * Splits the specified string into an argument vector. Arguments in the 00053 * string are delimited by whitespace. Whitespace-containing arguments 00054 * must be enclosed in quotes, either single (') or double ("). 00055 * 00056 * @param buf A nul-terminated CHAR_TYPE array to split into arguments 00057 * for the vector. 00058 * 00059 * @param substitute_env_args If non-zero, any token that is an 00060 * environment variable reference (e.g., @c $VAR) will have 00061 * its environment variable value in the resultant vector 00062 * in place of the environment variable name. 00063 */ 00064 ACE_ARGV_T (const CHAR_TYPE buf[], 00065 bool substitute_env_args = true); 00066 00067 /** 00068 * Initializes the argument vector from a set of arguments. Any environment 00069 * variable references are translated (if applicable) during execution of 00070 * this method. 00071 * 00072 * @param argv An array of tokens to initialize the object with. The 00073 * array must be terminated with a 0 pointer. All needed 00074 * data is copied from @a argv during this call; the pointers 00075 * in @a argv are not needed after this call, and the memory 00076 * referred to by @a argv is not referenced by this object. 00077 * 00078 * @param substitute_env_args If non-zero, any element of @a argv that is 00079 * an environment variable reference (e.g., @c $VAR) will have 00080 * its environment variable value in the resultant vector 00081 * in place of the environment variable name. 00082 */ 00083 ACE_ARGV_T (CHAR_TYPE *argv[], 00084 bool substitute_env_args = true); 00085 00086 /** 00087 * Initializes the argument vector from two combined argument vectors. 00088 * 00089 * @param first_argv An array of tokens to initialize the object with. 00090 * The array must be terminated with a 0 pointer. 00091 * @param second_argv An array of tokens that is concatenated with the 00092 * the tokens in @a first_argv. The array must be 00093 * terminated with a 0 pointer. 00094 * @param substitute_env_args If non-zero, any element of @a first_argv 00095 * or @a second_argv that is an environment variable 00096 * reference (e.g., @c $VAR) will have its environment 00097 * variable value in the resultant vector in place 00098 * of the environment variable name. 00099 */ 00100 ACE_ARGV_T (CHAR_TYPE *first_argv[], 00101 CHAR_TYPE *second_argv[], 00102 bool substitute_env_args = true); 00103 00104 /** 00105 * Initialize this object so arguments can be added later using one 00106 * of the add methods. This is referred to as the @i iterative method 00107 * of adding arguments to this object. 00108 */ 00109 ACE_ARGV_T (bool substitute_env_args = true); 00110 00111 /// Destructor. 00112 ~ACE_ARGV_T (void); 00113 00114 /** @name Accessor methods 00115 * 00116 * These methods access the argument vector contained in this object. 00117 */ 00118 //@{ 00119 /** 00120 * Returns the specified element of the current argument vector. 00121 * 00122 * @param index Index to the desired element. 00123 * 00124 * @retval Pointer to the indexed string. 00125 * @retval 0 if @a index is out of bounds. 00126 */ 00127 const CHAR_TYPE *operator[] (size_t index); 00128 00129 /** 00130 * Returns the current argument vector. The returned pointers are to data 00131 * maintained internally to this class. Do not change or delete either the 00132 * pointers or the memory to which they refer. 00133 */ 00134 CHAR_TYPE **argv (void); 00135 00136 /// Returns the current number of arguments. 00137 int argc (void) const; 00138 00139 /** 00140 * Returns a single string form of the current arguments. The returned 00141 * pointer refers to memory maintained internally to this class. Do not 00142 * change or delete it. 00143 */ 00144 const CHAR_TYPE *buf (void); 00145 00146 //@} 00147 00148 /// Dump the state of this object. 00149 void dump (void) const; 00150 00151 // Declare the dynamic allocation hooks. 00152 ACE_ALLOC_HOOK_DECLARE; 00153 00154 /** 00155 * Add another argument. This only works in the iterative mode. 00156 * 00157 * @note This method copies the specified pointer, but not the data 00158 * contained in the referenced memory. Thus, if the content of 00159 * the memory referred to by @a next_arg are changed after this 00160 * method returns, the results are undefined. 00161 * 00162 * @param next_arg Pointer to the next argument to add to the vector. 00163 * 00164 * @retval 0 on success; -1 on failure. Most likely @c errno values are: 00165 * - EINVAL: This object is not in iterative mode. 00166 * - ENOMEM: Not enough memory available to save @a next_arg. 00167 */ 00168 int add (const CHAR_TYPE *next_arg); 00169 00170 /** 00171 * Add an array of arguments. This only works in the iterative mode. 00172 * 00173 * @note This method copies the specified pointers, but not the data 00174 * contained in the referenced memory. Thus, if the content of 00175 * the memory referred to by any of the @a argv elements is 00176 * changed after this method returns, the results are undefined. 00177 * 00178 * @param argv Pointers to the arguments to add to the vector. 00179 * @a argv must be terminated by a 0 pointer. 00180 * 00181 * @retval 0 on success; -1 on failure. Most likely @c errno values are: 00182 * - EINVAL: This object is not in iterative mode. 00183 * - ENOMEM: Not enough memory available to save @a next_arg. 00184 */ 00185 int add (CHAR_TYPE *argv[]); 00186 00187 private: 00188 /// Copy constructor not implemented. 00189 ACE_UNIMPLEMENTED_FUNC (ACE_ARGV_T (const ACE_ARGV_T<CHAR_TYPE>&)) 00190 00191 /// Assignment operator not implemented. 00192 ACE_UNIMPLEMENTED_FUNC (ACE_ARGV_T operator= (const ACE_ARGV_T<CHAR_TYPE>&)) 00193 00194 /// Creates buf_ from the queue of added args, deletes previous buf_. 00195 int create_buf_from_queue (void); 00196 00197 /// Converts buf_ into the CHAR_TYPE *argv[] format. 00198 int string_to_argv (void); 00199 00200 /// Returns the string created from argv in buf and 00201 /// returns the number of arguments. 00202 int argv_to_string (CHAR_TYPE **argv, CHAR_TYPE *&buf); 00203 00204 /// Replace args with environment variable values? 00205 bool substitute_env_args_; 00206 00207 bool iterative_; 00208 00209 /// Number of arguments in the ARGV array. 00210 int argc_; 00211 00212 /// The array of string arguments. 00213 CHAR_TYPE **argv_; 00214 00215 /// Buffer containing the <argv> contents. 00216 CHAR_TYPE *buf_; 00217 00218 /// Total length of the arguments in the queue, not counting 00219 /// separating spaces 00220 size_t length_; 00221 00222 /// Queue which keeps user supplied arguments. This is only 00223 /// active in the "iterative" mode. 00224 ACE_Unbounded_Queue<CHAR_TYPE *> queue_; 00225 }; 00226 00227 typedef ACE_ARGV_T<ACE_TCHAR> ACE_ARGV; 00228 00229 // Close versioned namespace, if enabled by the user. 00230 ACE_END_VERSIONED_NAMESPACE_DECL 00231 00232 #if defined (__ACE_INLINE__) 00233 #include "ace/ARGV.inl" 00234 #endif /* __ACE_INLINE__ */ 00235 00236 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) 00237 #include "ace/ARGV.cpp" 00238 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */ 00239 00240 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA) 00241 #pragma implementation ("ARGV.cpp") 00242 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */ 00243 00244 #include /**/ "ace/post.h" 00245 #endif /* ACE_ARGUMENT_VECTOR_H */