diff options
| -rw-r--r-- | ChangeLog | 17 | ||||
| -rw-r--r-- | ace/ARGV.cpp | 18 | ||||
| -rw-r--r-- | ace/ARGV.h | 175 | ||||
| -rw-r--r-- | ace/ARGV.inl | 12 | ||||
| -rw-r--r-- | ace/OS_NS_unistd.cpp | 4 | ||||
| -rw-r--r-- | ace/OS_NS_unistd.h | 4 |
6 files changed, 142 insertions, 88 deletions
diff --git a/ChangeLog b/ChangeLog index 712e9447ba5..6cd2bb28b43 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,19 @@ +Mon May 1 19:49:45 UTC 2006 Steve Huston <shuston@riverace.com> + + * ace/ARGV.{h i cpp}: Filled out more of the documentation in this + class, specifically mentioning that the class will enforce the + "whitespace separates tokens, except when quoted" rule of command + line parsing that's consistent with ACE_Get_Opt, etc. Also removed + documentation of non-existant restrictions such as after using + add(), can't use buf(). + Removed the State enum since the only value ever used was ITERATIVE, + and changed "int state_" to "bool iterative_" (and removed the + state() accessor). Changed substitute_env_args_ from int to bool. + + * ace/OS_NS_unistd.{h cpp} (argv_to_string, string_to_argv): Changed + the substitute_env_args parameter from "int" to "bool" to better + reflect what it is, a yes/no indicator. + Mon May 1 06:53:12 UTC 2006 Johnny Willemsen <jwillemsen@remedy.nl> * include/makeinclude/platform_sunos5_g++.GNU: @@ -96,6 +112,7 @@ Fri Apr 28 15:42:59 UTC 2006 Phil Mesnier <mesnier_p@ociweb.com> * ace/Service_Gestalt.h: Cleaned up the long-lines of the UNIMPLEMENTED functions. +>>>>>>> 4.10246 Fri Apr 28 15:26:53 UTC 2006 Steve Huston <shuston@riverace.com> * ace/Timer_Queue_Adapters.h: Clarified the use and restrictions with diff --git a/ace/ARGV.cpp b/ace/ARGV.cpp index 703db37986f..7ea5dd93694 100644 --- a/ace/ARGV.cpp +++ b/ace/ARGV.cpp @@ -66,9 +66,9 @@ ACE_ARGV::argv_to_string (ACE_TCHAR **argv, ACE_TCHAR *&buf) } ACE_ARGV::ACE_ARGV (const ACE_TCHAR buf[], - int substitute_env_args) + bool substitute_env_args) : substitute_env_args_ (substitute_env_args), - state_ (TO_PTR_ARRAY), + iterative_ (false), argc_ (0), argv_ (0), buf_ (0), @@ -93,9 +93,9 @@ ACE_ARGV::ACE_ARGV (const ACE_TCHAR buf[], } ACE_ARGV::ACE_ARGV (ACE_TCHAR *argv[], - int substitute_env_args) + bool substitute_env_args) : substitute_env_args_ (substitute_env_args), - state_ (TO_STRING), + iterative_ (false), argc_ (0), argv_ (0), buf_ (0), @@ -112,9 +112,9 @@ ACE_ARGV::ACE_ARGV (ACE_TCHAR *argv[], ACE_ARGV::ACE_ARGV (ACE_TCHAR *first_argv[], ACE_TCHAR *second_argv[], - int substitute_env_args) + bool substitute_env_args) : substitute_env_args_ (substitute_env_args), - state_ (TO_STRING), + iterative_ (false), argc_ (0), argv_ (0), buf_ (0), @@ -159,9 +159,9 @@ ACE_ARGV::ACE_ARGV (ACE_TCHAR *first_argv[], } -ACE_ARGV::ACE_ARGV (int substitute_env_args) +ACE_ARGV::ACE_ARGV (bool substitute_env_args) : substitute_env_args_ (substitute_env_args), - state_ (ITERATIVE), + iterative_ (true), argc_ (0), argv_ (0), buf_ (0), @@ -178,7 +178,7 @@ ACE_ARGV::add (const ACE_TCHAR *next_arg) { // Only allow this to work in the "iterative" verion -- the // ACE_ARGVs created with the one argument constructor. - if (this->state_ != ITERATIVE) + if (!this->iterative_) { errno = EINVAL; return -1; diff --git a/ace/ARGV.h b/ace/ARGV.h index f7c0468b151..1f3350fd24e 100644 --- a/ace/ARGV.h +++ b/ace/ARGV.h @@ -30,121 +30,167 @@ ACE_BEGIN_VERSIONED_NAMESPACE_DECL * @class ACE_ARGV * * @brief Builds a counted argument vector (ala argc/argv) from either - * a string or a set of separate tokens. Can substitute environment - * variable values for tokens that are environment variable references. + * a string or a set of separate tokens. This class preserves whitespace + * within tokens only if the whitespace-containing token is enclosed in + * either single (') or double (") quotes. This is consistent with the + * expected behavior if an argument vector obtained using this class is + * passed to, for example, ACE_Get_Opt. + * + * This class can substitute environment variable values for tokens that + * are environment variable references (e.g., @c $VAR). This only works + * if the token is an environment variable reference and nothing else; it + * doesn't substitute environment variable references within a token. + * For example, @c $HOME/file will not substitute the value of the HOME + * environment variable. */ class ACE_Export ACE_ARGV { public: // = Initialization and termination. /** - * Splits the specified string into an argument vector, split at whitespace. + * Splits the specified string into an argument vector. Arguments in the + * string are delimited by whitespace. Whitespace-containing arguments + * must be enclosed in quotes, either single (') or double ("). * - * @param buf An ACE_TCHAR array to split into tokens for the vector. + * @param buf A nul-terminated ACE_TCHAR array to split into arguments + * for the vector. * * @param substitute_env_args If non-zero, any token that is an - * an environment variable reference ($VAR) will have + * environment variable reference (e.g., @c $VAR) will have * its environment variable value in the resultant vector - * in place of the environment variable name. This only works - * if the token is an environment variable reference and - * nothing else; it doesn't substitute environment variable - * references within a token. For example, @c $HOME/file will - * not substitute the value of the HOME environment variable. + * in place of the environment variable name. */ ACE_ARGV (const ACE_TCHAR buf[], - int substitute_env_args = 1); + bool substitute_env_args = true); /** - * Converts @a argv into a linear string. If @a substitute_env_args - * is enabled then we'll substitute the environment variables for - * each $ENV encountered in the string. The <buf> operation is not - * allowed on an ACE_ARGV created this way. + * Initializes the argument vector from a set of arguments. Any environment + * variable references are translated (if applicable) during execution of + * this method. + * + * @param argv An array of tokens to initialize the object with. The + * array must be terminated with a 0 pointer. All needed + * data is copied from @a argv during this call; the pointers + * in @a argv are not needed after this call, and the memory + * referred to by @a argv is not referenced by this object. + * + * @param substitute_env_args If non-zero, any element of @a argv that is + * an environment variable reference (e.g., @c $VAR) will have + * its environment variable value in the resultant vector + * in place of the environment variable name. */ ACE_ARGV (ACE_TCHAR *argv[], - int substitute_env_args = 1); + bool substitute_env_args = true); /** - * Creates an ACE_ARGV which is the concatenation of the first_argv - * and the second argv. The argv arguments should be null pointer - * terminated. + * Initializes the argument vector from two combined argument vectors. + * + * @param first_argv An array of tokens to initialize the object with. + * The array must be terminated with a 0 pointer. + * @param second_argv An array of tokens that is concatenated with the + * the tokens in @a first_argv. The array must be + * terminated with a 0 pointer. + * @param substitute_env_args If non-zero, any element of @a first_argv + * or @a second_argv that is an environment variable + * reference (e.g., @c $VAR) will have its environment + * variable value in the resultant vector in place + * of the environment variable name. */ ACE_ARGV (ACE_TCHAR *first_argv[], ACE_TCHAR *second_argv[], - int substitute_env_args =1); + bool substitute_env_args = true); /** - * Entry point for creating an ACE_TCHAR *[] command line - * iteratively via the <add> method. When this constructor is used, - * the <ITERATIVE> state is enabled. The <argv> and <buf> methods - * are allowed, and the result is recreated when called multiple - * times. The subscript operator is not allowed. + * Initialize this object so arguments can be added later using one + * of the add methods. This is referred to as the @i iterative method + * of adding arguments to this object. */ - ACE_ARGV (int substitute_env_args = 1); + ACE_ARGV (bool substitute_env_args = true); /// Destructor. ~ACE_ARGV (void); - // = Accessor arguments. - /// Returns the <index>th string in the ARGV array. + /** @name Accessor methods + * + * These methods access the argument vector contained in this object. + */ + //@{ + /** + * Returns the specified element of the current argument vector. + * + * @param index Index to the desired element. + * + * @retval Pointer to the indexed string. + * @retval 0 if @a index is out of bounds. + */ const ACE_TCHAR *operator[] (size_t index); /** - * Returns the @c argv array. Caller should not delete this memory - * since the ACE_ARGV destructor will delete it. If the caller - * modifies the array in the iterative mode, the changes are not - * saved to the queue. + * Returns the current argument vector. The returned pointers are to data + * maintained internally to this class. Do not change or delete either the + * pointers or the memory to which they refer. */ ACE_TCHAR **argv (void); - /// Returns @c argc. + /// Returns the current number of arguments. int argc (void) const; - /// Returns the @c buf. Caller should not delete this memory since - /// the ACE_ARGV destructor will delete it. + /** + * Returns a single string form of the current arguments. The returned + * pointer refers to memory maintained internally to this class. Do not + * change or delete it. + */ const ACE_TCHAR *buf (void); - /// Dump the state of an object. + //@} + + /// Dump the state of this object. void dump (void) const; - /// Declare the dynamic allocation hooks. + // Declare the dynamic allocation hooks. ACE_ALLOC_HOOK_DECLARE; - /// Add another argument. This only works in the <ITERATIVE> state. - /// Note that this method does not copy <next_arg>, nor does it - /// assume ownership of managing its memory, i.e., the caller is - /// responsible for memory management. Returns -1 on failure and 0 - /// on success. + /** + * Add another argument. This only works in the iterative mode. + * + * @note This method copies the specified pointer, but not the data + * contained in the referenced memory. Thus, if the content of + * the memory referred to by @a next_arg are changed after this + * method returns, the results are undefined. + * + * @param next_arg Pointer to the next argument to add to the vector. + * + * @retval 0 on success; -1 on failure. Most likely @c errno values are: + * - EINVAL: This object is not in iterative mode. + * - ENOMEM: Not enough memory available to save @a next_arg. + */ int add (const ACE_TCHAR *next_arg); /** - * Add another @a argv array. The @a argv parameter must be NULL - * terminated. This only works in the <ITERATIVE> state. Returns - * -1 on failure and 0 on success. + * Add an array of arguments. This only works in the iterative mode. + * + * @note This method copies the specified pointers, but not the data + * contained in the referenced memory. Thus, if the content of + * the memory referred to by any of the @a argv elements is + * changed after this method returns, the results are undefined. + * + * @param argv Pointers to the arguments to add to the vector. + * @a argv must be terminated by a 0 pointer. + * + * @retval 0 on success; -1 on failure. Most likely @c errno values are: + * - EINVAL: This object is not in iterative mode. + * - ENOMEM: Not enough memory available to save @a next_arg. */ int add (ACE_TCHAR *argv[]); - /// What state is this ACE_ARGV in? - int state (void) const; - - // These are the states possible via the different constructors. - enum States - { - /// ACE_ARGV converts buf[] to ACE_TCHAR *argv[] - TO_STRING = 1, - /// ACE_ARGV converts ACE_TCHAR *argv[] to buf[] - TO_PTR_ARRAY = 2, - /// Builds buf[] or ACE_TCHAR *argv[] iteratively with <add>. - ITERATIVE = 3 - }; - private: - /// Copy Constructor not implemented + /// Copy constructor not implemented. ACE_ARGV (const ACE_ARGV&); - /// Assignment '=' operator not implemented + /// Assignment operator not implemented. ACE_ARGV operator= (const ACE_ARGV&); - /// Creates buf_ from the queue, deletes previous buf_. + /// Creates buf_ from the queue of added args, deletes previous buf_. int create_buf_from_queue (void); /// Converts buf_ into the ACE_TCHAR *argv[] format. @@ -155,10 +201,9 @@ private: int argv_to_string (ACE_TCHAR **argv, ACE_TCHAR *&buf); /// Replace args with environment variable values? - int substitute_env_args_; + bool substitute_env_args_; - /// Current state marker. - int state_; + bool iterative_; /// Number of arguments in the ARGV array. int argc_; diff --git a/ace/ARGV.inl b/ace/ARGV.inl index 47711a486ee..599b1193e0d 100644 --- a/ace/ARGV.inl +++ b/ace/ARGV.inl @@ -14,21 +14,13 @@ ACE_ARGV::argc (void) const return this->argc_; } -// Return the state of this ACE_ARGV -ACE_INLINE int -ACE_ARGV::state(void) const -{ - ACE_TRACE ("ACE_ARGV::state"); - return this->state_; -} - // Return the arguments in a space-separated string ACE_INLINE const ACE_TCHAR * ACE_ARGV::buf (void) { ACE_TRACE ("ACE_ARGV::buf"); - if (this->buf_ == 0 && this->state_ == ITERATIVE) + if (this->buf_ == 0 && this->iterative_) this->create_buf_from_queue (); return (const ACE_TCHAR *) this->buf_; @@ -44,7 +36,7 @@ ACE_ARGV::argv (void) // Try to create the argv_ if it isn't there if (this->argv_ == 0) { - if (this->state_ == ITERATIVE && this->buf_ == 0) + if (this->iterative_ && this->buf_ == 0) this->create_buf_from_queue (); // Convert buf_ to argv_ diff --git a/ace/OS_NS_unistd.cpp b/ace/OS_NS_unistd.cpp index e23686974c7..b39f0e527e3 100644 --- a/ace/OS_NS_unistd.cpp +++ b/ace/OS_NS_unistd.cpp @@ -39,7 +39,7 @@ ACE_BEGIN_VERSIONED_NAMESPACE_DECL int ACE_OS::argv_to_string (ACE_TCHAR **argv, ACE_TCHAR *&buf, - int substitute_env_args) + bool substitute_env_args) { if (argv == 0 || argv[0] == 0) return 0; @@ -620,7 +620,7 @@ int ACE_OS::string_to_argv (ACE_TCHAR *buf, int &argc, ACE_TCHAR **&argv, - int substitute_env_args) + bool substitute_env_args) { // Reset the number of arguments argc = 0; diff --git a/ace/OS_NS_unistd.h b/ace/OS_NS_unistd.h index 680c97b7aed..831646bf47e 100644 --- a/ace/OS_NS_unistd.h +++ b/ace/OS_NS_unistd.h @@ -64,7 +64,7 @@ namespace ACE_OS extern ACE_Export int argv_to_string (ACE_TCHAR **argv, ACE_TCHAR *&buf, - int substitute_env_args = 1); + bool substitute_env_args = true); #if !defined (ACE_LACKS_CHDIR) ACE_NAMESPACE_INLINE_FUNCTION @@ -298,7 +298,7 @@ namespace ACE_OS int string_to_argv (ACE_TCHAR *buf, int &argc, ACE_TCHAR **&argv, - int substitute_env_args = 1); + bool substitute_env_args = true); ACE_NAMESPACE_INLINE_FUNCTION void swab (const void *src, void *dest, ssize_t n); |