diff options
Diffstat (limited to 'ACE/ace/ARGV.h')
| -rw-r--r-- | ACE/ace/ARGV.h | 245 |
1 files changed, 245 insertions, 0 deletions
diff --git a/ACE/ace/ARGV.h b/ACE/ace/ARGV.h new file mode 100644 index 00000000000..5ab4ae296c1 --- /dev/null +++ b/ACE/ace/ARGV.h @@ -0,0 +1,245 @@ +// -*- C++ -*- + +//========================================================================== +/** + * @file ARGV.h + * + * $Id$ + * + * @author Doug Schmidt <schmidt@cs.wustl.edu> + * @author Everett Anderson <eea1@cs.wustl.edu> + */ +//========================================================================== + +#ifndef ACE_ARGUMENT_VECTOR_H +#define ACE_ARGUMENT_VECTOR_H +#include /**/ "ace/pre.h" + +#include "ace/ACE_export.h" + +#if !defined (ACE_LACKS_PRAGMA_ONCE) +# pragma once +#endif /* ACE_LACKS_PRAGMA_ONCE */ + +#include "ace/Unbounded_Queue.h" + +// Open versioned namespace, if enabled by the user. +ACE_BEGIN_VERSIONED_NAMESPACE_DECL + +/** + * @class ACE_ARGV_T + * + * @brief 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., @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. + */ +template <typename CHAR_TYPE> +class ACE_ARGV_T +{ +public: + // = Initialization and termination. + /** + * 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 A nul-terminated CHAR_TYPE array to split into arguments + * for the vector. + * + * @param substitute_env_args If non-zero, any token 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_T (const CHAR_TYPE buf[], + bool substitute_env_args = true); + + /** + * 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_T (CHAR_TYPE *argv[], + bool substitute_env_args = true); + + /** + * 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_T (CHAR_TYPE *first_argv[], + CHAR_TYPE *second_argv[], + 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 @i iterative method + * of adding arguments to this object. + */ + ACE_ARGV_T (bool substitute_env_args = true); + + /// Destructor. + ~ACE_ARGV_T (void); + + /** @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 CHAR_TYPE *operator[] (size_t index); + + /** + * 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. + */ + CHAR_TYPE **argv (void); + + /// Returns the current number of arguments. + int argc (void) const; + + /** + * 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 CHAR_TYPE *buf (void); + + //@} + + /// Dump the state of this object. + void dump (void) const; + + // Declare the dynamic allocation hooks. + ACE_ALLOC_HOOK_DECLARE; + + /** + * 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 CHAR_TYPE *next_arg); + + /** + * 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 (CHAR_TYPE *argv[]); + +private: + /// Copy constructor not implemented. + ACE_UNIMPLEMENTED_FUNC (ACE_ARGV_T (const ACE_ARGV_T<CHAR_TYPE>&)) + + /// Assignment operator not implemented. + ACE_UNIMPLEMENTED_FUNC (ACE_ARGV_T operator= (const ACE_ARGV_T<CHAR_TYPE>&)) + + /// Creates buf_ from the queue of added args, deletes previous buf_. + int create_buf_from_queue (void); + + /// Converts buf_ into the CHAR_TYPE *argv[] format. + int string_to_argv (void); + + /// Returns the string created from argv in buf and + /// returns the number of arguments. + int argv_to_string (CHAR_TYPE **argv, CHAR_TYPE *&buf); + + /// Replace args with environment variable values? + bool substitute_env_args_; + + bool iterative_; + + /// Number of arguments in the ARGV array. + int argc_; + + /// The array of string arguments. + CHAR_TYPE **argv_; + + /// Buffer containing the <argv> contents. + CHAR_TYPE *buf_; + + /// Total length of the arguments in the queue, not counting + /// separating spaces + size_t length_; + + /// Queue which keeps user supplied arguments. This is only + /// active in the "iterative" mode. + ACE_Unbounded_Queue<CHAR_TYPE *> queue_; +}; + +typedef ACE_ARGV_T<ACE_TCHAR> ACE_ARGV; + +// Close versioned namespace, if enabled by the user. +ACE_END_VERSIONED_NAMESPACE_DECL + +#if defined (__ACE_INLINE__) +#include "ace/ARGV.inl" +#endif /* __ACE_INLINE__ */ + +#if defined (ACE_TEMPLATES_REQUIRE_SOURCE) +#include "ace/ARGV.cpp" +#endif /* ACE_TEMPLATES_REQUIRE_SOURCE */ + +#if defined (ACE_TEMPLATES_REQUIRE_PRAGMA) +#pragma implementation ("ARGV.cpp") +#endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */ + +#include /**/ "ace/post.h" +#endif /* ACE_ARGUMENT_VECTOR_H */ |