---

ACE_ARGV Class Reference

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. More...

#include <ARGV.h>

Collaboration diagram for ACE_ARGV:

[legend]List of all members.

Public Types
enum	States { TO_STRING = 1, TO_PTR_ARRAY = 2, ITERATIVE = 3 }
Public Methods
	ACE_ARGV (const ACE_TCHAR buf[], int substitute_env_args=1)
	ACE_ARGV (ACE_TCHAR *argv[], int substitute_env_args=1)
	ACE_ARGV (ACE_TCHAR *first_argv[], ACE_TCHAR *second_argv[], int substitute_env_args=1)
	ACE_ARGV (int substitute_env_args=1)
	~ACE_ARGV (void)
	Destructor. More...
const ACE_TCHAR *	operator[] (size_t index)
	Returns the <index>th string in the ARGV array. More...
ACE_TCHAR **	argv (void)
int	argc (void) const
	Returns <argc>. More...
const ACE_TCHAR *	buf (void)
	Returns the <buf>. Caller should not delete this memory since the <ARGV> destructor will delete it. More...
void	dump (void) const
	Dump the state of an object. More...
int	add (const ACE_TCHAR *next_arg)
	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. More...
int	add (ACE_TCHAR *argv[])
int	state (void) const
	What state is this ACE_ARGV in? More...
Public Attributes
	ACE_ALLOC_HOOK_DECLARE
	Declare the dynamic allocation hooks. More...
Private Methods
int	create_buf_from_queue (void)
	Creates buf_ from the queue, deletes previous buf_. More...
int	string_to_argv (void)
	Converts buf_ into the ACE_TCHAR *argv[] format. More...
int	argv_to_string (ACE_TCHAR **argv, ACE_TCHAR *&buf)
	Returns the string created from argv in buf and returns the number of arguments. More...
Private Attributes
int	substitute_env_args_
	Replace args with environment variable values? More...
int	state_
	Current state marker. More...
int	argc_
	Number of arguments in the ARGV array. More...
ACE_TCHAR **	argv_
	The array of string arguments. More...
ACE_TCHAR *	buf_
	Buffer containing the <argv> contents. More...
size_t	length_
	Total length of the arguments in the queue, not counting separating spaces. More...
ACE_Unbounded_Queue< ACE_TCHAR * >	queue_
	Queue which keeps user supplied arguments. This is only active in the "iterative" mode. More...

---

Detailed Description

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.

Definition at line 34 of file ARGV.h.

---

Member Enumeration Documentation

enum ACE_ARGV::States

Enumeration values: TO_STRING  ACE_ARGV converts buf[] to ACE_TCHAR *argv[]. TO_PTR_ARRAY  ACE_ARGV converts ACE_TCHAR *argv[] to buf[]. ITERATIVE  Builds buf[] or ACE_TCHAR *argv[] iteratively with <add>. Definition at line 128 of file ARGV.h. { /// 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 };

---

Constructor & Destructor Documentation

ACE_ARGV::ACE_ARGV (  const ACE_TCHAR    buf[], int    substitute_env_args = 1 )

Splits the specified string into an argument vector, split at whitespace. Parameters: buf  An ACE_TCHAR array to split into tokens for the vector. substitute_env_args  If non-zero, any token that is an an environment variable reference ($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, $HOME/file will not substitute the value of the HOME environment variable. Definition at line 61 of file ARGV.cpp. References ACE_ERROR, ACE_LIB_TEXT, ACE_NEW, ACE_TCHAR, ACE_TRACE, buf, LM_ERROR, ACE_OS_String::strcpy, string_to_argv, and ACE_OS_String::strlen. : substitute_env_args_ (substitute_env_args), state_ (TO_PTR_ARRAY), argc_ (0), argv_ (0), buf_ (0), length_ (0), queue_ () { ACE_TRACE ("ACE_ARGV::ACE_ARGV ACE_TCHAR[] to ACE_TCHAR *[]"); if (buf == 0 || buf[0] == 0) return; // Make an internal copy of the string. ACE_NEW (this->buf_, ACE_TCHAR[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_LIB_TEXT ("%p\n"), ACE_LIB_TEXT ("string_to_argv"))); }

ACE_ARGV::ACE_ARGV (  ACE_TCHAR *    argv[], int    substitute_env_args = 1 )

Converts <argv> into a linear string. If <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. Definition at line 88 of file ARGV.cpp. References ACE_LIB_TEXT, ACE_NEW, ACE_TCHAR, ACE_TRACE, argc_, argv, buf_, ACE_OS::getenv, ACE_OS_String::strecpy, ACE_OS_String::strlen, and substitute_env_args_. : substitute_env_args_ (substitute_env_args), state_ (TO_STRING), argc_ (0), argv_ (0), buf_ (0), length_ (0), queue_ () { ACE_TRACE ("ACE_ARGV::ACE_ARGV ACE_TCHAR*[] to ACE_TCHAR[]"); if (argv == 0 || argv[0] == 0) return; size_t buf_len = 0; // Determine the length of the buffer. for (int i = 0; argv[i] != 0; i++) { #if !defined (ACE_LACKS_ENV) ACE_TCHAR *temp = 0; // Account for environment variables. if (this->substitute_env_args_ && (argv[i][0] == '$' && (temp = ACE_OS::getenv (&argv[i][1])) != 0)) buf_len += ACE_OS::strlen (temp); else #endif /* !ACE_LACKS_ENV */ buf_len += ACE_OS::strlen (argv[i]); // Add one for the extra space between each string. buf_len++; } // Step through all argv params and copy each one into buf; separate // each param with white space. ACE_NEW (this->buf_, ACE_TCHAR[buf_len + 1]); ACE_TCHAR *end = this->buf_; int j; for (j = 0; argv[j] != 0; j++) { #if !defined (ACE_LACKS_ENV) ACE_TCHAR *temp = 0; // Account for environment variables. if (this->substitute_env_args_ && (argv[j][0] == '$' && (temp = ACE_OS::getenv (&argv[j][1])) != 0)) end = ACE_OS::strecpy (end, temp); else #endif /* ACE_LACKS_ENV */ end = ACE_OS::strecpy (end, argv[j]); // Replace the null char that strecpy copies with white space as // a separator. *(end - 1) = ACE_LIB_TEXT (' '); } // Remember how many arguments there are this->argc_ = j; // Null terminate the string. *end = '\0'; }

ACE_ARGV::ACE_ARGV (  ACE_TCHAR *    first_argv[], ACE_TCHAR *    second_argv[], int    substitute_env_args = 1 )

Creates an ACE_ARGV which is the concatenation of the first_argv and the second argv. The argv arguments should be null pointer terminated. Definition at line 160 of file ARGV.cpp. References ACE_NEW, ACE_TCHAR, ACE_TRACE, argc_, argv_to_string, ACE_OS_String::strcat, ACE_OS_String::strcpy, and ACE_OS_String::strlen. : substitute_env_args_ (substitute_env_args), state_ (TO_STRING), argc_ (0), argv_ (0), buf_ (0), length_ (0), queue_ () { ACE_TRACE ("ACE_ARGV::ACE_ARGV ACE_TCHAR*[] + ACE_TCHAR *[] to ACE_TCHAR[]"); int first_argc; int second_argc; ACE_TCHAR *first_buf; ACE_TCHAR *second_buf; // convert the first argv to a string first_argc = this->argv_to_string (first_argv,first_buf); // convert the second argv to a string second_argc = this->argv_to_string (second_argv,second_buf); // 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_, ACE_TCHAR[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; }

ACE_ARGV::ACE_ARGV (  int    substitute_env_args = 1 )

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. Definition at line 209 of file ARGV.cpp. References ACE_TRACE. : substitute_env_args_ (substitute_env_args), state_ (ITERATIVE), argc_ (0), argv_ (0), buf_ (0), length_ (0), queue_ () { ACE_TRACE ("ACE_ARGV::ACE_ARGV Iterative"); // Nothing to do yet -- the user puts in arguments via add () }

ACE_ARGV::~ACE_ARGV (  void    )

Destructor. Definition at line 273 of file ARGV.cpp. References ACE_TRACE, argv_, buf_, and ACE_OS_Memory::free. { ACE_TRACE ("ACE_ARGV::~ACE_ARGV"); 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_; }

---

Member Function Documentation

int ACE_ARGV::add (  ACE_TCHAR *    argv[] )

Add another <argv> array. The <argv> parameter must be NULL terminated. This only works in the <ITERATIVE> state. Returns -1 on failure and 0 on success. Definition at line 262 of file ARGV.cpp. References ACE_TCHAR, add, and argv. { for (int i = 0; argv[i] != 0; i++) if (this->add (argv[i]) == -1) return -1; return 0; }

int ACE_ARGV::add (  const ACE_TCHAR *    next_arg )

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. Definition at line 224 of file ARGV.cpp. References ACE_ERROR_RETURN, ACE_LIB_TEXT, ACE_TCHAR, argc_, argv_, buf_, ACE_Unbounded_Queue< ACE_TCHAR * >::enqueue_tail, ACE_OS_Memory::free, ITERATIVE, length_, LM_ERROR, queue_, state_, and ACE_OS_String::strlen. Referenced by add. { // Only allow this to work in the "iterative" verion -- the // ACE_ARGVs created with the one argument constructor. if (this->state_ != ITERATIVE) { errno = EINVAL; return -1; } // Put the new argument at the end of the queue. if (this->queue_.enqueue_tail ((ACE_TCHAR *) next_arg) == -1) ACE_ERROR_RETURN ((LM_ERROR, ACE_LIB_TEXT ("Can't add more to ARGV queue")), -1); this->length_ += ACE_OS::strlen (next_arg); 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; }

ACE_INLINE int ACE_ARGV::argc (  void    )  const

Returns <argc>. Definition at line 6 of file ARGV.i. References ACE_TRACE, and argc_. Referenced by ace_yyparse, and ACE_Service_Config::initialize. { ACE_TRACE ("ACE_ARGV::argc"); return this->argc_; }

ACE_INLINE ACE_TCHAR ** ACE_ARGV::argv (  void    )

Returns the <argv> array. Caller should not delete this memory since the <ARGV> destructor will delete it. If the caller modifies the array in the iterative mode, the changes are not saved to the queue. Definition at line 35 of file ARGV.i. References ACE_TCHAR, ACE_TRACE, argv_, buf_, create_buf_from_queue, ITERATIVE, state_, and string_to_argv. Referenced by ACE_ARGV, ace_yyparse, add, argv_to_string, dump, ACE_Service_Config::initialize, and operator[]. { ACE_TRACE ("ACE_ARGV::argv"); // Try to create the argv_ if it isn't there if (this->argv_ == 0) { if (this->state_ == ITERATIVE && this->buf_ == 0) this->create_buf_from_queue (); // Convert buf_ to argv_ if (this->string_to_argv () == -1) return (ACE_TCHAR **) 0; } return (ACE_TCHAR **) this->argv_; }

int ACE_ARGV::argv_to_string (  ACE_TCHAR **    argv, ACE_TCHAR *&    buf )  [private]

Returns the string created from argv in buf and returns the number of arguments. Definition at line 56 of file ARGV.cpp. References ACE_TCHAR, argv, ACE_OS::argv_to_string, and buf. Referenced by ACE_ARGV. { return ACE_OS::argv_to_string (argv, buf); }

ACE_INLINE const ACE_TCHAR * ACE_ARGV::buf (  void    )

Returns the <buf>. Caller should not delete this memory since the <ARGV> destructor will delete it. Definition at line 22 of file ARGV.i. References ACE_TCHAR, ACE_TRACE, buf_, create_buf_from_queue, ITERATIVE, and state_. Referenced by ACE_ARGV, and argv_to_string. { ACE_TRACE ("ACE_ARGV::buf"); if (this->buf_ == 0 && this->state_ == ITERATIVE) this->create_buf_from_queue (); return (const ACE_TCHAR *) this->buf_; }

int ACE_ARGV::create_buf_from_queue (  void    )  [private]

Creates buf_ from the queue, deletes previous buf_. Definition at line 289 of file ARGV.cpp. References ACE_NEW_RETURN, ACE_TCHAR, ACE_TRACE, ACE_Unbounded_Queue_Iterator::advance, argc_, buf_, ACE_Unbounded_Queue_Iterator::done, ACE_OS_String::memcpy, ACE_Unbounded_Queue_Iterator::next, and ACE_OS_String::strlen. Referenced by argv, and buf. { ACE_TRACE ("ACE_ARGV::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_, ACE_TCHAR[this->length_ + this->argc_], -1); // Get an iterator over the queue ACE_Unbounded_Queue_Iterator<ACE_TCHAR *> iter (this->queue_); ACE_TCHAR **arg; ACE_TCHAR *ptr = this->buf_; size_t len; int more = 0; while (!iter.done ()) { // Get next argument from the queue. iter.next (arg); more = iter.advance (); len = ACE_OS::strlen (*arg); // Copy the argument into buf_ ACE_OS::memcpy ((void *) ptr, (const void *) (*arg), len * sizeof (ACE_TCHAR)); // Move the pointer down. ptr += len; // Put in an argument separating space. if (more != 0) *ptr++ = ' '; } // Put in the NUL terminator *ptr = '\0'; return 0; }

void ACE_ARGV::dump (  void    )  const

Dump the state of an object. Definition at line 19 of file ARGV.cpp. References ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, ACE_LIB_TEXT, ACE_TRACE, argc_, argv, and LM_DEBUG. { ACE_TRACE ("ACE_ARGV::dump"); ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this)); ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("argc_ = %d"), this->argc_)); ACE_ARGV *this_obj = ACE_const_cast (ACE_ARGV *, this); for (int i = 0; i < this->argc_; i++) ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("\nargv_[%i] = %s"), i, this_obj->argv ()[i])); ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("\nbuf = %s\n"), this->buf_)); ACE_DEBUG ((LM_DEBUG, ACE_LIB_TEXT ("\n"))); ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP)); }

ACE_INLINE const ACE_TCHAR * ACE_ARGV::operator[] (  size_t    index )

Returns the <index>th string in the ARGV array. Definition at line 56 of file ARGV.i. References ACE_TCHAR, ACE_TRACE, and argv. { ACE_TRACE ("ACE_ARGV::operator[]"); // Don't go out of bounds. if (i >= ACE_static_cast (size_t, this->argc_)) return 0; return (const ACE_TCHAR *) this->argv ()[i]; }

ACE_INLINE int ACE_ARGV::state (  void    )  const

What state is this ACE_ARGV in? Definition at line 14 of file ARGV.i. References ACE_TRACE, and state_. { ACE_TRACE ("ACE_ARGV::state"); return this->state_; }

int ACE_ARGV::string_to_argv (  void    )  [private]

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

---

Member Data Documentation

ACE_ARGV::ACE_ALLOC_HOOK_DECLARE

Declare the dynamic allocation hooks. Definition at line 108 of file ARGV.h.

int ACE_ARGV::argc_ [private]

Number of arguments in the ARGV array. Definition at line 157 of file ARGV.h. Referenced by ACE_ARGV, add, argc, create_buf_from_queue, and dump.

ACE_TCHAR** ACE_ARGV::argv_ [private]

The array of string arguments. Definition at line 160 of file ARGV.h. Referenced by add, argv, and ~ACE_ARGV.

ACE_TCHAR* ACE_ARGV::buf_ [private]

Buffer containing the <argv> contents. Definition at line 163 of file ARGV.h. Referenced by ACE_ARGV, add, argv, buf, create_buf_from_queue, and ~ACE_ARGV.

size_t ACE_ARGV::length_ [private]

Total length of the arguments in the queue, not counting separating spaces. Definition at line 167 of file ARGV.h. Referenced by add.

ACE_Unbounded_Queue<ACE_TCHAR *> ACE_ARGV::queue_ [private]

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

int ACE_ARGV::state_ [private]

Current state marker. Definition at line 154 of file ARGV.h. Referenced by add, argv, buf, and state.

int ACE_ARGV::substitute_env_args_ [private]

Replace args with environment variable values? Definition at line 151 of file ARGV.h. Referenced by ACE_ARGV.

---

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

• ARGV.h
• ARGV.cpp
• ARGV.i

---