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

ARGV.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //==========================================================================
00004 /**
00005  *  @file    ARGV.h
00006  *
00007  *  $Id: ARGV.h,v 1.1.1.4.2.1 2003/04/16 16:41:14 taoadmin 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/OS.h"
00025 #include "ace/Unbounded_Queue.h"
00026 
00027 /**
00028  * @class ACE_ARGV
00029  *
00030  * @brief Builds a counted argument vector (ala argc/argv) from either
00031  * a string or a set of separate tokens. Can substitute environment
00032  * variable values for tokens that are environment variable references.
00033  */
00034 class ACE_Export ACE_ARGV
00035 {
00036 public:
00037   // = Initialization and termination.
00038   /**
00039    * Splits the specified string into an argument vector, split at whitespace.
00040    *
00041    * @param buf   An ACE_TCHAR array to split into tokens for the vector.
00042    *
00043    * @param substitute_env_args  If non-zero, any token that is an
00044    *              an environment variable reference ($VAR) will have
00045    *              its environment variable value in the resultant vector
00046    *              in place of the environment variable name. This only works
00047    *              if the token is an environment variable reference and
00048    *              nothing else; it doesn't substitute environment variable
00049    *              references within a token. For example, @c $HOME/file will
00050    *              not substitute the value of the HOME environment variable.
00051    */
00052   ACE_ARGV (const ACE_TCHAR buf[],
00053             int substitute_env_args = 1);
00054 
00055   /**
00056    * Converts <argv> into a linear string.  If <substitute_env_args>
00057    * is enabled then we'll substitute the environment variables for
00058    * each $ENV encountered in the string.  The <buf> operation is not
00059    * allowed on an ACE_ARGV created this way.
00060    */
00061   ACE_ARGV (ACE_TCHAR *argv[],
00062             int substitute_env_args = 1);
00063 
00064   /**
00065    * Creates an ACE_ARGV which is the concatenation of the first_argv
00066    * and the second argv. The argv arguments should be null pointer
00067    * terminated.
00068    */
00069   ACE_ARGV (ACE_TCHAR *first_argv[],
00070             ACE_TCHAR *second_argv[],
00071             int substitute_env_args =1);
00072 
00073   /**
00074    * Entry point for creating an ACE_TCHAR *[] command line
00075    * iteratively via the <add> method.  When this constructor is used,
00076    * the <ITERATIVE> state is enabled.  The <argv> and <buf> methods
00077    * are allowed, and the result is recreated when called multiple
00078    * times.  The subscript operator is not allowed.
00079    */
00080   ACE_ARGV (int substitute_env_args = 1);
00081 
00082   /// Destructor.
00083   ~ACE_ARGV (void);
00084 
00085   // = Accessor arguments.
00086   /// Returns the <index>th string in the ARGV array.
00087   const ACE_TCHAR *operator[] (size_t index);
00088 
00089   /**
00090    * Returns the <argv> array.  Caller should not delete this memory
00091    * since the <ARGV> destructor will delete it.  If the caller
00092    * modifies the array in the iterative mode, the changes are not
00093    * saved to the queue.
00094    */
00095   ACE_TCHAR **argv (void);
00096 
00097   /// Returns <argc>.
00098   int argc (void) const;
00099 
00100   /// Returns the <buf>.  Caller should not delete this memory since
00101   /// the <ARGV> destructor will delete it.
00102   const ACE_TCHAR *buf (void);
00103 
00104   /// Dump the state of an object.
00105   void dump (void) const;
00106 
00107   /// Declare the dynamic allocation hooks.
00108   ACE_ALLOC_HOOK_DECLARE;
00109 
00110   /// Add another argument.  This only works in the <ITERATIVE> state.
00111   /// Note that this method does not copy <next_arg>, nor does it 
00112   /// assume ownership of managing its memory, i.e., the caller is
00113   /// responsible for memory management.  Returns -1 on failure and 0
00114   /// on success.  
00115   int add (const ACE_TCHAR *next_arg);
00116 
00117   /**
00118    * Add another <argv> array.  The <argv> parameter must be NULL
00119    * terminated.  This only works in the <ITERATIVE> state.  Returns
00120    * -1 on failure and 0 on success.
00121    */
00122   int add (ACE_TCHAR *argv[]);
00123 
00124   /// What state is this ACE_ARGV in?
00125   int state (void) const;
00126 
00127   // These are the states possible via the different constructors.
00128   enum States
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   };
00137 
00138 private:
00139 
00140   /// Creates buf_ from the queue, deletes previous buf_.
00141   int create_buf_from_queue (void);
00142 
00143   /// Converts buf_ into the ACE_TCHAR *argv[] format.
00144   int string_to_argv (void);
00145 
00146   /// Returns the string created from argv in buf and
00147   /// returns the number of arguments.
00148   int argv_to_string (ACE_TCHAR **argv, ACE_TCHAR *&buf);
00149 
00150   /// Replace args with environment variable values?
00151   int substitute_env_args_;
00152 
00153   /// Current state marker.
00154   int state_;
00155 
00156   /// Number of arguments in the ARGV array.
00157   int argc_;
00158 
00159   /// The array of string arguments.
00160   ACE_TCHAR **argv_;
00161 
00162   /// Buffer containing the <argv> contents.
00163   ACE_TCHAR *buf_;
00164 
00165   /// Total length of the arguments in the queue, not counting
00166   /// separating spaces
00167   size_t length_;
00168 
00169   /// Queue which keeps user supplied arguments.  This is only
00170   /// active in the "iterative" mode.
00171   ACE_Unbounded_Queue<ACE_TCHAR *> queue_;
00172 };
00173 
00174 #if defined (__ACE_INLINE__)
00175 #include "ace/ARGV.i"
00176 #endif /* __ACE_INLINE__ */
00177 
00178 #include "ace/post.h"
00179 #endif /* ACE_ARGUMENT_VECTOR_H */

Generated on Mon Jun 16 11:19:03 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002