ACE_ARGV_T< CHAR_TYPE > Class Template Reference

Builds a counted argument vector (ala argc/argv) from either 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. More...

#include <ARGV.h>

Collaboration diagram for ACE_ARGV_T< CHAR_TYPE >:

[legend]List of all members.

Public Member Functions
	ACE_ARGV_T (const CHAR_TYPE buf[], bool substitute_env_args=true)
	ACE_ARGV_T (CHAR_TYPE *argv[], bool substitute_env_args=true, bool quote_args=false)
	ACE_ARGV_T (CHAR_TYPE *first_argv[], CHAR_TYPE *second_argv[], bool substitute_env_args=true, bool quote_args=false)
	ACE_ARGV_T (bool substitute_env_args=true)
	~ACE_ARGV_T (void)
	Destructor.
void	dump (void) const
	Dump the state of this object.
int	add (const CHAR_TYPE *next_arg, bool quote_arg=false)
int	add (CHAR_TYPE *argv[], bool quote_args=false)
Accessor methods
These methods access the argument vector contained in this object.
const CHAR_TYPE *	operator[] (size_t index)
CHAR_TYPE **	argv (void)
int	argc (void) const
	Returns the current number of arguments.
const CHAR_TYPE *	buf (void)
Public Attributes
	ACE_ALLOC_HOOK_DECLARE
Private Member Functions
	ACE_ARGV_T (const ACE_ARGV_T< CHAR_TYPE > &)
	Copy constructor not implemented.
ACE_ARGV_T	operator= (const ACE_ARGV_T< CHAR_TYPE > &)
	Assignment operator not implemented.
int	create_buf_from_queue (void)
	Creates buf_ from the queue of added args, deletes previous buf_.
int	string_to_argv (void)
	Converts buf_ into the CHAR_TYPE *argv[] format.
Private Attributes
bool	substitute_env_args_
	Replace args with environment variable values?
bool	iterative_
int	argc_
	Number of arguments in the ARGV array.
CHAR_TYPE **	argv_
	The array of string arguments.
CHAR_TYPE *	buf_
	Buffer containing the contents.
size_t	length_
ACE_Unbounded_Queue< ACE_ARGV_Queue_Entry_T< CHAR_TYPE > >	queue_

---

Detailed Description

template<typename CHAR_TYPE>
class ACE_ARGV_T< CHAR_TYPE >

Builds a counted argument vector (ala argc/argv) from either 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., $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, $HOME/file will not substitute the value of the HOME environment variable.

Definition at line 95 of file ARGV.h.

---

Constructor & Destructor Documentation

template<typename CHAR_TYPE> ACE_ARGV_T< CHAR_TYPE >::ACE_ARGV_T (  const CHAR_TYPE  buf[], bool  substitute_env_args = true )

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 ("). Parameters: buf  A nul-terminated CHAR_TYPE array to split into arguments for the vector. substitute_env_args  If non-zero, any token that is an environment variable reference (e.g., $VAR) will have its environment variable value in the resultant vector in place of the environment variable name. Definition at line 79 of file ARGV.cpp. References ACE_ERROR, ACE_NEW, ACE_TEXT, ACE_TRACE, LM_ERROR, ACE_OS::strcpy(), and ACE_ARGV_T< CHAR_TYPE >::string_to_argv(). : substitute_env_args_ (substitute_env_args), iterative_ (false), argc_ (0), argv_ (0), buf_ (0), length_ (0), queue_ () { ACE_TRACE ("ACE_ARGV_T::ACE_ARGV_T CHAR_TYPE[] to CHAR_TYPE *[]"); if (buf == 0 || buf[0] == 0) return; // Make an internal copy of the string. ACE_NEW (this->buf_, CHAR_TYPE[ACE_OS::strlen (buf) + 1]); ACE_OS::strcpy (this->buf_, buf); // Create this->argv_. if (this->string_to_argv () == -1) ACE_ERROR ((LM_ERROR, ACE_TEXT ("%p\n"), ACE_TEXT ("string_to_argv"))); }

template<typename CHAR_TYPE> ACE_ARGV_T< CHAR_TYPE >::ACE_ARGV_T (  CHAR_TYPE *  argv[], bool  substitute_env_args = true, bool  quote_args = false )

Initializes the argument vector from a set of arguments. Any environment variable references are translated (if applicable) during execution of this method. Parameters: 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 argv during this call; the pointers in argv are not needed after this call, and the memory referred to by argv is not referenced by this object. substitute_env_args  If non-zero, any element of argv that is an environment variable reference (e.g., $VAR) will have its environment variable value in the resultant vector in place of the environment variable name. quote_args  If non-zero each argument argv[i] needs to be enclosed in double quotes ('"'). Definition at line 107 of file ARGV.cpp. References ACE_TRACE, and ACE_OS::argv_to_string(). : substitute_env_args_ (substitute_env_args), iterative_ (false), argc_ (0), argv_ (0), buf_ (0), length_ (0), queue_ () { ACE_TRACE ("ACE_ARGV_T::ACE_ARGV_T CHAR_TYPE*[] to CHAR_TYPE[]"); if (argv == 0 || argv[0] == 0) return; this->argc_ = ACE_OS::argv_to_string (argv, this->buf_, substitute_env_args, quote_arg); }

template<typename CHAR_TYPE> ACE_ARGV_T< CHAR_TYPE >::ACE_ARGV_T (  CHAR_TYPE *  first_argv[], CHAR_TYPE *  second_argv[], bool  substitute_env_args = true, bool  quote_args = false )

Initializes the argument vector from two combined argument vectors. Parameters: first_argv  An array of tokens to initialize the object with. The array must be terminated with a 0 pointer. second_argv  An array of tokens that is concatenated with the the tokens in first_argv. The array must be terminated with a 0 pointer. substitute_env_args  If non-zero, any element of first_argv or second_argv that is an environment variable reference (e.g., $VAR) will have its environment variable value in the resultant vector in place of the environment variable name. quote_args  If non-zero each arguments first_argv[i] and second_argv[i] needs to be enclosed in double quotes ('"'). Definition at line 130 of file ARGV.cpp. References ACE_NEW, ACE_TRACE, ACE_OS::argv_to_string(), ACE_OS::strcat(), ACE_OS::strcpy(), and ACE_OS::strlen(). : substitute_env_args_ (substitute_env_args), iterative_ (false), argc_ (0), argv_ (0), buf_ (0), length_ (0), queue_ () { ACE_TRACE ("ACE_ARGV_T::ACE_ARGV_T CHAR_TYPE*[] + CHAR_TYPE *[] to CHAR_TYPE[]"); int first_argc = 0; int second_argc = 0; CHAR_TYPE *first_buf = 0; CHAR_TYPE *second_buf = 0; // convert the first argv to a string if (first_argv != 0 && first_argv[0] != 0) { first_argc = ACE_OS::argv_to_string (first_argv, first_buf, substitute_env_args, quote_args); } // convert the second argv to a string if (second_argv != 0 && second_argv[0] != 0) { second_argc = ACE_OS::argv_to_string (second_argv, second_buf, substitute_env_args, quote_args); } // Add the number of arguments in both the argvs. this->argc_ = first_argc + second_argc; size_t buf_len = ACE_OS::strlen (first_buf) + ACE_OS::strlen (second_buf) + 1; // Allocate memory to the lenght of the combined argv string. ACE_NEW (this->buf_, CHAR_TYPE[buf_len + 1]); // copy the first argv string to the buffer ACE_OS::strcpy (this->buf_, first_buf); // concatenate the second argv string to the buffer ACE_OS::strcat (this->buf_, second_buf); // Delete the first and second buffers delete [] first_buf; delete [] second_buf; }

template<typename CHAR_TYPE> ACE_ARGV_T< CHAR_TYPE >::ACE_ARGV_T (  bool  substitute_env_args = true  )

Initialize this object so arguments can be added later using one of the add methods. This is referred to as the iterative method of adding arguments to this object. Definition at line 190 of file ARGV.cpp. References ACE_TRACE. : substitute_env_args_ (substitute_env_args), iterative_ (true), argc_ (0), argv_ (0), buf_ (0), length_ (0), queue_ () { ACE_TRACE ("ACE_ARGV_T::ACE_ARGV_T Iterative"); // Nothing to do yet -- the user puts in arguments via add () }

template<typename CHAR_TYPE> ACE_ARGV_T< CHAR_TYPE >::~ACE_ARGV_T (  void   )

Destructor. Definition at line 268 of file ARGV.cpp. References ACE_TRACE, ACE_ARGV_T< CHAR_TYPE >::buf_, and ACE_OS::free(). { ACE_TRACE ("ACE_ARGV_T::~ACE_ARGV_T"); if (this->argv_ != 0) for (int i = 0; this->argv_[i] != 0; i++) ACE_OS::free ((void *) this->argv_[i]); delete [] this->argv_; delete [] this->buf_; }

template<typename CHAR_TYPE> ACE_ARGV_T< CHAR_TYPE >::ACE_ARGV_T (  const ACE_ARGV_T< CHAR_TYPE > &   )  [private]

Copy constructor not implemented.

---

Member Function Documentation

template<typename CHAR_TYPE> int ACE_ARGV_T< CHAR_TYPE >::add (  CHAR_TYPE *  argv[], bool  quote_args = false )

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 argv elements is changed after this method returns, the results are undefined. Parameters: argv  Pointers to the arguments to add to the vector. argv must be terminated by a 0 pointer. quote_args  If non-zero each argument argv[i] needs to be enclosed in double quotes ('"'). Return values: 0  on success; -1 on failure. Most likely errno values are: EINVAL: This object is not in iterative mode. ENOMEM: Not enough memory available to save next_arg. Definition at line 256 of file ARGV.cpp. References ACE_ARGV_T< CHAR_TYPE >::add(). { for (int i = 0; argv[i] != 0; i++) if (this->add (argv[i], quote_args) == -1) return -1; return 0; }

template<typename CHAR_TYPE> int ACE_ARGV_T< CHAR_TYPE >::add (  const CHAR_TYPE *  next_arg, bool  quote_arg = false )

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 next_arg are changed after this method returns, the results are undefined. Parameters: next_arg  Pointer to the next argument to add to the vector. quote_arg  The argument next_arg need to be quoted while adding to the vector. Return values: 0  on success; -1 on failure. Most likely errno values are: EINVAL: This object is not in iterative mode. ENOMEM: Not enough memory available to save next_arg. Definition at line 206 of file ARGV.cpp. References ACE_ERROR_RETURN, ACE_TEXT, ACE_ARGV_T< CHAR_TYPE >::buf_, ACE_Unbounded_Queue< ACE_ARGV_Queue_Entry_T< CHAR_TYPE > >::enqueue_tail(), ACE_OS::free(), ACE_ARGV_T< CHAR_TYPE >::iterative_, ACE_ARGV_T< CHAR_TYPE >::length_, LM_ERROR, ACE_OS::strchr(), and ACE_OS::strlen(). Referenced by ACE_ARGV_T< CHAR_TYPE >::add(), and ACE_Service_Config::parse_args_i(). { // Only allow this to work in the "iterative" verion -- the // ACE_ARGVs created with the one argument constructor. if (!this->iterative_) { errno = EINVAL; return -1; } this->length_ += ACE_OS::strlen (next_arg); if (quote_arg && ACE_OS::strchr (next_arg, ' ') != 0) { this->length_ += 2; if (ACE_OS::strchr (next_arg, '"') != 0) for (const CHAR_TYPE * p = next_arg; *p != '\0'; ++p) if (*p == '"') ++this->length_; } else { quote_arg = false; } // Put the new argument at the end of the queue. if (this->queue_.enqueue_tail (ACE_ARGV_Queue_Entry_T<CHAR_TYPE> (next_arg, quote_arg)) == -1) ACE_ERROR_RETURN ((LM_ERROR, ACE_TEXT ("Can't add more to ARGV queue")), -1); ++this->argc_; // Wipe argv_ and buf_ away so that they will be recreated if the // user calls argv () or buf (). if (this->argv_ != 0) { for (int i = 0; this->argv_[i] != 0; i++) ACE_OS::free ((void *) this->argv_[i]); delete [] this->argv_; this->argv_ = 0; } delete [] this->buf_; this->buf_ = 0; return 0; }

template<typename CHAR_TYPE> ACE_INLINE int ACE_ARGV_T< CHAR_TYPE >::argc (  void   )  const

Returns the current number of arguments. Definition at line 43 of file ARGV.inl. References ACE_TRACE, and ACE_ARGV_T< CHAR_TYPE >::argv(). Referenced by ace_yyparse(), ACE_Service_Gestalt::initialize(), ACE_Service_Gestalt::initialize_i(), and ACE_Service_Config::parse_args_i(). { ACE_TRACE ("ACE_ARGV_T::argc"); // Try to create the argv_ if it isn't there ACE_ARGV_T<CHAR_TYPE> *nonconst_this = const_cast <ACE_ARGV_T<CHAR_TYPE> *> (this); (void) nonconst_this->argv (); return this->argc_; }

template<typename CHAR_TYPE> ACE_INLINE CHAR_TYPE ** ACE_ARGV_T< CHAR_TYPE >::argv (  void   )

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. Definition at line 70 of file ARGV.inl. References ACE_TRACE, ACE_ARGV_T< CHAR_TYPE >::buf_, ACE_ARGV_T< CHAR_TYPE >::create_buf_from_queue(), ACE_ARGV_T< CHAR_TYPE >::iterative_, and ACE_ARGV_T< CHAR_TYPE >::string_to_argv(). Referenced by ace_yyparse(), ACE_ARGV_T< CHAR_TYPE >::argc(), ACE_ARGV_T< CHAR_TYPE >::dump(), ACE_Service_Gestalt::initialize(), ACE_Service_Gestalt::initialize_i(), ACE_ARGV_T< CHAR_TYPE >::operator[](), and ACE_Service_Config::parse_args_i(). { ACE_TRACE ("ACE_ARGV_T::argv"); // Try to create the argv_ if it isn't there if (this->argv_ == 0) { if (this->iterative_ && this->buf_ == 0) this->create_buf_from_queue (); // Convert buf_ to argv_ if (this->string_to_argv () == -1) return (CHAR_TYPE **) 0; } return (CHAR_TYPE **) this->argv_; }

template<typename CHAR_TYPE> ACE_INLINE const CHAR_TYPE * ACE_ARGV_T< CHAR_TYPE >::buf (  void   )

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. Definition at line 56 of file ARGV.inl. References ACE_TRACE, ACE_ARGV_T< CHAR_TYPE >::buf_, ACE_ARGV_T< CHAR_TYPE >::create_buf_from_queue(), and ACE_ARGV_T< CHAR_TYPE >::iterative_. { ACE_TRACE ("ACE_ARGV_T::buf"); if (this->buf_ == 0 && this->iterative_) this->create_buf_from_queue (); return (const CHAR_TYPE *) this->buf_; }

template<typename CHAR_TYPE> int ACE_ARGV_T< CHAR_TYPE >::create_buf_from_queue (  void   )  [private]

Creates buf_ from the queue of added args, deletes previous buf_. Definition at line 285 of file ARGV.cpp. References ACE_NEW_RETURN, ACE_TRACE, ACE_Unbounded_Queue_Iterator< T >::advance(), ACE_ARGV_Queue_Entry_T< CHAR_TYPE >::arg_, ACE_ARGV_T< CHAR_TYPE >::buf_, ACE_Unbounded_Queue_Iterator< T >::done(), ACE_OS::memcpy(), ACE_Unbounded_Queue_Iterator< T >::next(), ACE_ARGV_Queue_Entry_T< CHAR_TYPE >::quote_arg_, ACE_OS::strchr(), and ACE_OS::strlen(). Referenced by ACE_ARGV_T< CHAR_TYPE >::argv(), and ACE_ARGV_T< CHAR_TYPE >::buf(). { ACE_TRACE ("ACE_ARGV_T::create_buf_from_queue"); // If the are no arguments, don't do anything if (this->argc_ <= 0) return -1; delete [] this->buf_; ACE_NEW_RETURN (this->buf_, CHAR_TYPE[this->length_ + this->argc_], -1); // Get an iterator over the queue ACE_Unbounded_Queue_Iterator<ACE_ARGV_Queue_Entry_T<CHAR_TYPE> > iter (this->queue_); ACE_ARGV_Queue_Entry_T<CHAR_TYPE> *arg = 0; CHAR_TYPE *ptr = this->buf_; size_t len; while (!iter.done ()) { // Get next argument from the queue. iter.next (arg); iter.advance (); if (arg->quote_arg_) { *ptr++ = '"'; if (ACE_OS::strchr (arg->arg_, '"') != 0) { for (const CHAR_TYPE * p = arg->arg_; *p != '\0'; ++p) { if (*p == '"') *ptr++ = '\\'; *ptr++ = *p; } } else { len = ACE_OS::strlen (arg->arg_); // Copy the argument into buf_ ACE_OS::memcpy ((void *) ptr, (const void *) (arg->arg_), len * sizeof (CHAR_TYPE)); // Move the pointer down. ptr += len; } *ptr++ = '"'; } else { len = ACE_OS::strlen (arg->arg_); // Copy the argument into buf_ ACE_OS::memcpy ((void *) ptr, (const void *) (arg->arg_), len * sizeof (CHAR_TYPE)); // Move the pointer down. ptr += len; } // Put in an argument separating space. *ptr++ = ' '; } // Put in the NUL terminator ptr[-1] = '\0'; return 0; }

template<typename CHAR_TYPE> void ACE_ARGV_T< CHAR_TYPE >::dump (  void   )  const

Dump the state of this object. Definition at line 39 of file ARGV.cpp. References ACE_ARGV, ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, ACE_TEXT, ACE_TRACE, ACE_ARGV_T< CHAR_TYPE >::argv(), and LM_DEBUG. { #if defined (ACE_HAS_DUMP) ACE_TRACE ("ACE_ARGV_T::dump"); ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this)); ACE_DEBUG ((LM_DEBUG, ACE_TEXT ("argc_ = %d"), this->argc_)); ACE_ARGV *this_obj = const_cast<ACE_ARGV *> (this); for (int i = 0; i < this->argc_; i++) ACE_DEBUG ((LM_DEBUG, ACE_TEXT ("\nargv_[%i] = %s"), i, this_obj->argv ()[i])); ACE_DEBUG ((LM_DEBUG, ACE_TEXT ("\nbuf = %s\n"), this->buf_)); ACE_DEBUG ((LM_DEBUG, ACE_TEXT ("\n"))); ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP)); #endif /* ACE_HAS_DUMP */ }

template<typename CHAR_TYPE> ACE_ARGV_T ACE_ARGV_T< CHAR_TYPE >::operator= (  const ACE_ARGV_T< CHAR_TYPE > &   )  [private]

Assignment operator not implemented.

template<typename CHAR_TYPE> ACE_INLINE const CHAR_TYPE * ACE_ARGV_T< CHAR_TYPE >::operator[] (  size_t  index  )

Returns the specified element of the current argument vector. Parameters: index  Index to the desired element. Return values: Pointer  to the indexed string. 0  if index is out of bounds. Definition at line 92 of file ARGV.inl. References ACE_TRACE, and ACE_ARGV_T< CHAR_TYPE >::argv(). { ACE_TRACE ("ACE_ARGV_T::operator[]"); // Don't go out of bounds. if (i >= static_cast<size_t> (this->argc_)) return 0; return (const CHAR_TYPE *) this->argv ()[i]; }

template<typename CHAR_TYPE> int ACE_ARGV_T< CHAR_TYPE >::string_to_argv (  void   )  [private]

Converts buf_ into the CHAR_TYPE *argv[] format. Definition at line 68 of file ARGV.cpp. References ACE_TRACE, and ACE_OS::string_to_argv(). Referenced by ACE_ARGV_T< CHAR_TYPE >::ACE_ARGV_T(), and ACE_ARGV_T< CHAR_TYPE >::argv(). { ACE_TRACE ("ACE_ARGV_T::string_to_argv"); return ACE_OS::string_to_argv (this->buf_, this->argc_, this->argv_, this->substitute_env_args_); }

---

Member Data Documentation

template<typename CHAR_TYPE> ACE_ARGV_T< CHAR_TYPE >::ACE_ALLOC_HOOK_DECLARE

Definition at line 209 of file ARGV.h.

template<typename CHAR_TYPE> int ACE_ARGV_T< CHAR_TYPE >::argc_ [private]

Number of arguments in the ARGV array. Definition at line 269 of file ARGV.h.

template<typename CHAR_TYPE> CHAR_TYPE** ACE_ARGV_T< CHAR_TYPE >::argv_ [private]

The array of string arguments. Definition at line 272 of file ARGV.h.

template<typename CHAR_TYPE> CHAR_TYPE* ACE_ARGV_T< CHAR_TYPE >::buf_ [private]

Buffer containing the contents. Definition at line 275 of file ARGV.h. Referenced by ACE_ARGV_T< CHAR_TYPE >::add(), ACE_ARGV_T< CHAR_TYPE >::argv(), ACE_ARGV_T< CHAR_TYPE >::buf(), ACE_ARGV_T< CHAR_TYPE >::create_buf_from_queue(), and ACE_ARGV_T< CHAR_TYPE >::~ACE_ARGV_T().

template<typename CHAR_TYPE> bool ACE_ARGV_T< CHAR_TYPE >::iterative_ [private]

Definition at line 266 of file ARGV.h. Referenced by ACE_ARGV_T< CHAR_TYPE >::add(), ACE_ARGV_T< CHAR_TYPE >::argv(), and ACE_ARGV_T< CHAR_TYPE >::buf().

template<typename CHAR_TYPE> size_t ACE_ARGV_T< CHAR_TYPE >::length_ [private]

Total length of the arguments in the queue, not counting separating spaces Definition at line 279 of file ARGV.h. Referenced by ACE_ARGV_T< CHAR_TYPE >::add().

template<typename CHAR_TYPE> ACE_Unbounded_Queue<ACE_ARGV_Queue_Entry_T<CHAR_TYPE> > ACE_ARGV_T< CHAR_TYPE >::queue_ [private]

Queue which keeps user supplied arguments. This is only active in the "iterative" mode. Definition at line 283 of file ARGV.h.

template<typename CHAR_TYPE> bool ACE_ARGV_T< CHAR_TYPE >::substitute_env_args_ [private]

Replace args with environment variable values? Definition at line 264 of file ARGV.h.

---

The documentation for this class was generated from the following files:

• ARGV.h
• ARGV.cpp
• ARGV.inl

---