Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

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:

Collaboration graph
[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_TCHARoperator[] (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_TCHARbuf (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_TCHARbuf_
 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.

00129   {
00130     /// ACE_ARGV converts buf[] to ACE_TCHAR *argv[]
00131     TO_STRING = 1,
00132     /// ACE_ARGV converts ACE_TCHAR *argv[] to buf[]
00133     TO_PTR_ARRAY = 2,
00134     /// Builds buf[] or ACE_TCHAR *argv[] iteratively with <add>.
00135     ITERATIVE = 3
00136   };


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.

00063   : substitute_env_args_ (substitute_env_args),
00064     state_ (TO_PTR_ARRAY),
00065     argc_ (0),
00066     argv_ (0),
00067     buf_ (0),
00068     length_ (0),
00069     queue_ ()
00070 {
00071   ACE_TRACE ("ACE_ARGV::ACE_ARGV ACE_TCHAR[] to ACE_TCHAR *[]");
00072 
00073   if (buf == 0 || buf[0] == 0)
00074     return;
00075 
00076   // Make an internal copy of the string.
00077   ACE_NEW (this->buf_,
00078            ACE_TCHAR[ACE_OS::strlen (buf) + 1]);
00079   ACE_OS::strcpy (this->buf_, buf);
00080 
00081   // Create this->argv_.
00082   if (this->string_to_argv () == -1)
00083     ACE_ERROR ((LM_ERROR,
00084                 ACE_LIB_TEXT ("%p\n"),
00085                 ACE_LIB_TEXT ("string_to_argv")));
00086 }

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

00090   : substitute_env_args_ (substitute_env_args),
00091     state_ (TO_STRING),
00092     argc_ (0),
00093     argv_ (0),
00094     buf_ (0),
00095     length_ (0),
00096     queue_ ()
00097 {
00098   ACE_TRACE ("ACE_ARGV::ACE_ARGV ACE_TCHAR*[] to ACE_TCHAR[]");
00099 
00100   if (argv == 0 || argv[0] == 0)
00101     return;
00102 
00103   size_t buf_len = 0;
00104 
00105   // Determine the length of the buffer.
00106 
00107   for (int i = 0; argv[i] != 0; i++)
00108     {
00109 #if !defined (ACE_LACKS_ENV)
00110       ACE_TCHAR *temp = 0;
00111 
00112       // Account for environment variables.
00113       if (this->substitute_env_args_
00114           && (argv[i][0] == '$'
00115           && (temp = ACE_OS::getenv (&argv[i][1])) != 0))
00116         buf_len += ACE_OS::strlen (temp);
00117       else
00118 #endif /* !ACE_LACKS_ENV */
00119         buf_len += ACE_OS::strlen (argv[i]);
00120 
00121       // Add one for the extra space between each string.
00122       buf_len++;
00123     }
00124 
00125   // Step through all argv params and copy each one into buf; separate
00126   // each param with white space.
00127 
00128   ACE_NEW (this->buf_,
00129            ACE_TCHAR[buf_len + 1]);
00130 
00131   ACE_TCHAR *end = this->buf_;
00132   int j;
00133 
00134   for (j = 0; argv[j] != 0; j++)
00135     {
00136 #if !defined (ACE_LACKS_ENV)
00137       ACE_TCHAR *temp = 0;
00138 
00139       // Account for environment variables.
00140       if (this->substitute_env_args_
00141           && (argv[j][0] == '$'
00142           && (temp = ACE_OS::getenv (&argv[j][1])) != 0))
00143         end = ACE_OS::strecpy (end, temp);
00144       else
00145 #endif /* ACE_LACKS_ENV */
00146         end = ACE_OS::strecpy (end, argv[j]);
00147 
00148       // Replace the null char that strecpy copies with white space as
00149       // a separator.
00150       *(end - 1) = ACE_LIB_TEXT (' ');
00151     }
00152 
00153   // Remember how many arguments there are
00154   this->argc_ = j;
00155 
00156   // Null terminate the string.
00157   *end = '\0';
00158 }

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.

00163   : substitute_env_args_ (substitute_env_args),
00164     state_ (TO_STRING),
00165     argc_ (0),
00166     argv_ (0),
00167     buf_ (0),
00168     length_ (0),
00169     queue_ ()
00170 {
00171   ACE_TRACE ("ACE_ARGV::ACE_ARGV ACE_TCHAR*[] + ACE_TCHAR *[] to ACE_TCHAR[]");
00172 
00173   int first_argc;
00174   int second_argc;
00175 
00176   ACE_TCHAR *first_buf;
00177   ACE_TCHAR *second_buf;
00178 
00179   // convert the first argv to a string
00180   first_argc = this->argv_to_string (first_argv,first_buf);
00181 
00182   // convert the second argv to a string
00183   second_argc = this->argv_to_string (second_argv,second_buf);
00184 
00185   // Add the number of arguments in both the argvs.
00186   this->argc_ = first_argc + second_argc;
00187 
00188   size_t buf_len =
00189     ACE_OS::strlen (first_buf) + ACE_OS::strlen (second_buf) + 1;
00190 
00191   // Allocate memory to the lenght of the combined argv string.
00192   ACE_NEW (this->buf_,
00193            ACE_TCHAR[buf_len + 1]);
00194 
00195   // copy the first argv string to the buffer
00196   ACE_OS::strcpy (this->buf_, first_buf);
00197 
00198   // concatenate the second argv string to the buffer
00199   ACE_OS::strcat (this->buf_, second_buf);
00200 
00201   //   Delete the first and second buffers
00202 
00203   delete [] first_buf;
00204 
00205   delete [] second_buf;
00206 }

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.

00210   : substitute_env_args_ (substitute_env_args),
00211     state_ (ITERATIVE),
00212     argc_ (0),
00213     argv_ (0),
00214     buf_ (0),
00215     length_ (0),
00216     queue_ ()
00217 {
00218   ACE_TRACE ("ACE_ARGV::ACE_ARGV Iterative");
00219 
00220   // Nothing to do yet -- the user puts in arguments via add ()
00221 }

ACE_ARGV::~ACE_ARGV void   
 

Destructor.

Definition at line 273 of file ARGV.cpp.

References ACE_TRACE, argv_, buf_, and ACE_OS_Memory::free.

00274 {
00275   ACE_TRACE ("ACE_ARGV::~ACE_ARGV");
00276 
00277   if (this->argv_ != 0)
00278     for (int i = 0; this->argv_[i] != 0; i++)
00279       ACE_OS::free ((void *) this->argv_[i]);
00280 
00281   delete [] this->argv_;
00282   delete [] this->buf_;
00283 }


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.

00263 {
00264   for (int i = 0; argv[i] != 0; i++)
00265     if (this->add (argv[i]) == -1)
00266       return -1;
00267 
00268   return 0;
00269 }

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.

00225 {
00226   // Only allow this to work in the "iterative" verion -- the
00227   // ACE_ARGVs created with the one argument constructor.
00228   if (this->state_ != ITERATIVE)
00229     {
00230       errno = EINVAL;
00231       return -1;
00232     }
00233 
00234   // Put the new argument at the end of the queue.
00235   if (this->queue_.enqueue_tail ((ACE_TCHAR *) next_arg) == -1)
00236     ACE_ERROR_RETURN ((LM_ERROR,
00237                        ACE_LIB_TEXT ("Can't add more to ARGV queue")),
00238                       -1);
00239 
00240   this->length_ += ACE_OS::strlen (next_arg);
00241 
00242   this->argc_++;
00243 
00244   // Wipe argv_ and buf_ away so that they will be recreated if the
00245   // user calls argv () or buf ().
00246   if (this->argv_ != 0)
00247     {
00248       for (int i = 0; this->argv_[i] != 0; i++)
00249         ACE_OS::free ((void *) this->argv_[i]);
00250 
00251       delete [] this->argv_;
00252       this->argv_ = 0;
00253     }
00254 
00255   delete [] this->buf_;
00256   this->buf_ = 0;
00257 
00258   return 0;
00259 }

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.

00007 {
00008   ACE_TRACE ("ACE_ARGV::argc");
00009   return this->argc_;
00010 }

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[].

00036 {
00037   ACE_TRACE ("ACE_ARGV::argv");
00038 
00039   // Try to create the argv_ if it isn't there
00040   if (this->argv_ == 0) 
00041     {
00042       if (this->state_ == ITERATIVE && this->buf_ == 0)
00043         this->create_buf_from_queue ();
00044 
00045       // Convert buf_ to argv_
00046       if (this->string_to_argv () == -1)
00047         return (ACE_TCHAR **) 0;
00048     }
00049 
00050   return (ACE_TCHAR **) this->argv_;
00051 }

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.

00057 {
00058   return ACE_OS::argv_to_string (argv, buf);
00059 }

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.

00023 {
00024   ACE_TRACE ("ACE_ARGV::buf");
00025 
00026   if (this->buf_ == 0 && this->state_ == ITERATIVE) 
00027     this->create_buf_from_queue ();
00028 
00029   return (const ACE_TCHAR *) this->buf_;
00030 }

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.

00290 {
00291   ACE_TRACE ("ACE_ARGV::create_buf_from_queue");
00292 
00293   // If the are no arguments, don't do anything
00294   if (this->argc_ <= 0)
00295     return -1;
00296 
00297   delete [] this->buf_;
00298 
00299   ACE_NEW_RETURN (this->buf_,
00300                   ACE_TCHAR[this->length_ + this->argc_],
00301                   -1);
00302 
00303   // Get an iterator over the queue
00304   ACE_Unbounded_Queue_Iterator<ACE_TCHAR *> iter (this->queue_);
00305 
00306   ACE_TCHAR **arg;
00307   ACE_TCHAR *ptr = this->buf_;
00308   size_t len;
00309   int more = 0;
00310 
00311   while (!iter.done ())
00312     {
00313       // Get next argument from the queue.
00314       iter.next (arg);
00315 
00316       more = iter.advance ();
00317 
00318       len = ACE_OS::strlen (*arg);
00319 
00320       // Copy the argument into buf_
00321       ACE_OS::memcpy ((void *) ptr,
00322                       (const void *) (*arg),
00323                       len * sizeof (ACE_TCHAR));
00324       // Move the pointer down.
00325       ptr += len;
00326 
00327       // Put in an argument separating space.
00328       if (more != 0)
00329         *ptr++ = ' ';
00330     }
00331 
00332   // Put in the NUL terminator
00333   *ptr = '\0';
00334 
00335   return 0;
00336 }

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.

00020 {
00021   ACE_TRACE ("ACE_ARGV::dump");
00022 
00023   ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this));
00024   ACE_DEBUG ((LM_DEBUG,  ACE_LIB_TEXT ("argc_ = %d"), this->argc_));
00025 
00026   ACE_ARGV *this_obj = ACE_const_cast (ACE_ARGV *, this);
00027 
00028   for (int i = 0; i < this->argc_; i++)
00029     ACE_DEBUG ((LM_DEBUG,
00030                 ACE_LIB_TEXT ("\nargv_[%i] = %s"),
00031                 i,
00032                 this_obj->argv ()[i]));
00033 
00034   ACE_DEBUG ((LM_DEBUG,  ACE_LIB_TEXT ("\nbuf = %s\n"), this->buf_));
00035   ACE_DEBUG ((LM_DEBUG,  ACE_LIB_TEXT ("\n")));
00036   ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP));
00037 }

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.

00057 {
00058   ACE_TRACE ("ACE_ARGV::operator[]");
00059 
00060   // Don't go out of bounds.
00061   if (i >= ACE_static_cast (size_t, this->argc_))
00062     return 0;
00063 
00064   return (const ACE_TCHAR *) this->argv ()[i];
00065 }

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

00015 {
00016   ACE_TRACE ("ACE_ARGV::state");
00017   return this->state_;
00018 }

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.

00046 {
00047   ACE_TRACE ("ACE_ARGV::string_to_argv");
00048 
00049   return ACE_OS::string_to_argv (this->buf_,
00050                                  this->argc_,
00051                                  this->argv_,
00052                                  this->substitute_env_args_);
00053 }


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:
Generated on Mon Jun 16 12:44:53 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002