ACE  6.3.3
Public Member Functions | Public Attributes | Private Member Functions | Private Attributes | List of all members
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 >:
Collaboration graph
[legend]

Public Member Functions

 ACE_ARGV_T (const CHAR_TYPE buf[], bool substitute_env_args=true)
 
 ACE_ARGV_T (int argc, CHAR_TYPE *argv[], bool substitute_env_args=true, bool quote_args=false)
 
 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. More...
 
void dump (void) const
 Dump the state of this object. More...
 
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. More...
 
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. More...
 
ACE_ARGV_T operator= (const ACE_ARGV_T< CHAR_TYPE > &)
 Assignment operator not implemented. More...
 
int create_buf_from_queue (void)
 Creates buf_ from the queue of added args, deletes previous buf_. More...
 
int string_to_argv (void)
 Converts buf_ into the CHAR_TYPE *argv[] format. More...
 

Private Attributes

bool substitute_env_args_
 Replace args with environment variable values? More...
 
bool iterative_
 
int argc_
 Number of arguments in the ARGV array. More...
 
CHAR_TYPE ** argv_
 The array of string arguments. More...
 
CHAR_TYPE * buf_
 Buffer containing the <argv> contents. More...
 
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.

Constructor & Destructor Documentation

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

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
bufA nul-terminated CHAR_TYPE array to split into arguments for the vector.
substitute_env_argsIf 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.
template<typename CHAR_TYPE >
ACE_ARGV_T< CHAR_TYPE >::ACE_ARGV_T ( int  argc,
CHAR_TYPE *  argv[],
bool  substitute_env_args = true,
bool  quote_args = false 
)
explicit

Initializes the argument vector from a set of arguments. Any environment variable references are translated (if applicable) during execution of this method. In contrast with ACE_ARGV_T(CHAR_TYPE *[], bool, bool), this ctor does not require argv to be 0-terminated as the number of arguments is provided explicitely.

Parameters
argcThe number of arguments in the argv array.
argvAn array of tokens to initialize the object with. 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_argsIf 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_argsIf non-zero each argument argv[i] needs to be enclosed in double quotes ('"').
template<typename CHAR_TYPE >
ACE_ARGV_T< CHAR_TYPE >::ACE_ARGV_T ( CHAR_TYPE *  argv[],
bool  substitute_env_args = true,
bool  quote_args = false 
)
explicit

Initializes the argument vector from a set of arguments. Any environment variable references are translated (if applicable) during execution of this method.

Parameters
argvAn 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_argsIf 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_argsIf non-zero each argument argv[i] needs to be enclosed in double quotes ('"').
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_argvAn array of tokens to initialize the object with. The array must be terminated with a 0 pointer.
second_argvAn array of tokens that is concatenated with the the tokens in first_argv. The array must be terminated with a 0 pointer.
substitute_env_argsIf 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_argsIf non-zero each arguments first_argv[i] and second_argv[i] needs to be enclosed in double quotes ('"').
template<typename CHAR_TYPE >
ACE_ARGV_T< CHAR_TYPE >::ACE_ARGV_T ( bool  substitute_env_args = true)
explicit

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.

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

Destructor.

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 ( 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_argPointer to the next argument to add to the vector.
quote_argThe argument next_arg need to be quoted while adding to the vector.
Return values
0on 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.
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
argvPointers to the arguments to add to the vector. argv must be terminated by a 0 pointer.
quote_argsIf non-zero each argument argv[i] needs to be enclosed in double quotes ('"').
Return values
0on 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.
template<typename CHAR_TYPE >
int ACE_ARGV_T< CHAR_TYPE >::argc ( void  ) const
inline

Returns the current number of arguments.

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

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.

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

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.

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

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

Dump the state of this object.

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 >
const CHAR_TYPE * ACE_ARGV_T< CHAR_TYPE >::operator[] ( size_t  index)
inline

Returns the specified element of the current argument vector.

Parameters
indexIndex to the desired element.
Return values
Pointerto the indexed string.
0if index is out of bounds.
template<typename CHAR_TYPE >
int ACE_ARGV_T< CHAR_TYPE >::string_to_argv ( void  )
private

Converts buf_ into the CHAR_TYPE *argv[] format.

Member Data Documentation

template<typename CHAR_TYPE >
ACE_ARGV_T< CHAR_TYPE >::ACE_ALLOC_HOOK_DECLARE
template<typename CHAR_TYPE >
int ACE_ARGV_T< CHAR_TYPE >::argc_
private

Number of arguments in the ARGV array.

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

The array of string arguments.

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

Buffer containing the <argv> contents.

template<typename CHAR_TYPE >
bool ACE_ARGV_T< CHAR_TYPE >::iterative_
private
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

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.

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

Replace args with environment variable values?


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