ACE_Get_Opt Class Reference

Iterator for parsing command-line arguments. More...

#include <Get_Opt.h>

Collaboration diagram for ACE_Get_Opt:

Collaboration graph
[legend]
List of all members.

Public Types

typedef int Option
enum  { REQUIRE_ORDER = 1, PERMUTE_ARGS = 2, RETURN_IN_ORDER = 3 }
 Mutually exclusive ordering values. More...
enum  OPTION_ARG_MODE { NO_ARG = 0, ARG_REQUIRED = 1, ARG_OPTIONAL = 2 }
 Mutually exclusive option argument mode used by long options. More...
enum  {
  eof = -1, long_option_found = 0, non_option_arg_found = 1, error = '?',
  arg_required = ':'
}

Public Member Functions

 ACE_Get_Opt (int argc, ACE_TCHAR **argv, const ACE_TCHAR *optstring=ACE_LIB_TEXT(""), int skip_args=1, bool report_errors=false, int ordering=PERMUTE_ARGS, bool long_only=false)
 ~ACE_Get_Opt (void)
 Default dtor.
Option operator() (void)
ACE_TCHARopt_arg (void) const
Option opt_opt (void)
int & opt_ind (void)
Option long_option (const ACE_TCHAR *name, OPTION_ARG_MODE has_arg=NO_ARG)
 Adds a long option with no corresponding short option.
Option long_option (const ACE_TCHAR *name, Option short_option, OPTION_ARG_MODE has_arg=NO_ARG)
 Adds a long option with a corresponding short option.
const ACE_TCHARlong_option (void) const
int argc (void) const
 The number of arguments in the internal argv_.
ACE_TCHAR ** argv (void) const
 Accessor for the internal argv_ pointer.
const ACE_TCHARlast_option (void) const
void dump (void) const
 Dump the state of an object.
const ACE_TCHARoptstring (void) const

Public Attributes

int argc_
 Holds the argc count.
ACE_TCHAR ** argv_
 Holds the argv pointer.
int optind
 Index in argv_ of the next element to be scanned.
int opterr
ACE_TCHARoptarg

Private Member Functions

Option nextchar_i (void)
 Updates nextchar_.
Option long_option_i (void)
 Handles long options.
Option short_option_i (void)
 Handles short options.
void permute_args (void)
Option permute (void)
 Handles reordering <argv>-elements.
void last_option (const ACE_TString &s)
 Set last_option.
 ACE_Get_Opt (const ACE_Get_Opt &)
ACE_Get_Optoperator= (const ACE_Get_Opt &)

Private Attributes

ACE_TStringoptstring_
 Holds the option string.
bool long_only_
 Treat all options as long options.
bool has_colon_
ACE_TStringlast_option_
ACE_TCHARnextchar_
Option optopt_
 Most recently matched short option character.
int ordering_
 Keeps track of ordering mode (default <PERMUTE_ARGS>).
int nonopt_start_
int nonopt_end_
ACE_Get_Opt_Long_Optionlong_option_
 Points to the long_option found on last call to <operator()>.
ACE_Array< ACE_Get_Opt_Long_Option * > long_opts_
 Array of long options.
 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks.

Classes

class  ACE_Get_Opt_Long_Option

Detailed Description

Iterator for parsing command-line arguments.

This is a C++ wrapper for getopt(3c) and getopt_long(3c).


Member Typedef Documentation

typedef int ACE_Get_Opt::Option
 


Member Enumeration Documentation

anonymous enum
 

Mutually exclusive ordering values.

Enumerator:
REQUIRE_ORDER  REQUIRE_ORDER means that processing stops and EOF is returned as soon as a non-option argument is found. opt_ind() will return the index of the next argv element so the program can continue processing the rest of the argv elements.
PERMUTE_ARGS  PERMUTE_ARGS means the argv elements are reordered dynamically (permuted) so that all options appear first. When the elements are permuted, the order of the options and the following arguments are maintained. When the last option has been processed, EOF is returned and opt_ind() returns the index into the next non-option element.
RETURN_IN_ORDER  RETURN_IN_ORDER means each argv element is processed in the order is it seen. If the element is not recognized as an option, '1' is returned and opt_arg() refers to the argv element found.

anonymous enum
 

Scan elements of argv (whose length is argc) for short option characters given in optstring or long options (with no short option equivalents).

If an element of argv starts with '-', and is not exactly "-" or "--", then it is a short option element. The characters of this element (aside from the initial '-') are option characters. If it starts with "--" followed by other characters it is treated as a long option. If operator() is called repeatedly, it returns each of the option characters from each of the option elements.

Returns:
The parsed option character. The following characters have special significance.
Return values:
0 A long option was found
'\?' Either an unknown option character was found, or the option is known but requires an argument, none was specified, and optstring did not contain a leading colon.
':' A known option character was found but it requires an argument and none was supplied, and the first character of optstring was a colon. opt_opt() indicates which option was specified.
'1' RETURN_IN_ORDER was specified and a non-option argument was found.
-1 No more option characters were found. opt_ind() will return the index in argv of the first argv element that is not an option. If PERMUTE_ARGS was specified, the argv elements have been permuted so that those that are not options now come last.
Note:
The standards are unclear with respect to the conditions under which '?' and ':' are returned, so we scan the initial characters of optstring up unto the first short option character for '+', '-', and ':' in order to determine ordering and missing argument behavior.
Enumerator:
eof 
long_option_found 
non_option_arg_found 
error 
arg_required 

enum ACE_Get_Opt::OPTION_ARG_MODE
 

Mutually exclusive option argument mode used by long options.

Enumerator:
NO_ARG  Doesn't take an argument.
ARG_REQUIRED  Requires an argument, same as passing ":" after a short option character in optstring.
ARG_OPTIONAL  Argument is optional, same as passing "::" after a short option character in optstring.


Constructor & Destructor Documentation

ACE_Get_Opt::ACE_Get_Opt int  argc,
ACE_TCHAR **  argv,
const ACE_TCHAR optstring = ACE_LIB_TEXT(""),
int  skip_args = 1,
bool  report_errors = false,
int  ordering = PERMUTE_ARGS,
bool  long_only = false
 

Constructor initializes the command line to be parsed. All information for parsing must be supplied to this constructor.

Parameters:
argc The number of argv elements to parse.
argv Command line tokens, such as would be passed to main().
optstring Nul-terminated string containing the legitimate short option characters. A single colon ":" following an option character means the option requires an argument. A double colon "::" following an option character means the argument is optional. The argument is taken from the rest of the current argv element, or from the following argv element (only valid for required arguments; optional arguments must always reside in the same argv element). The argument value, if any is returned by the opt_arg() method. optstring can be extended by adding long options with corresponding short options via the long_option() method. If the short option already appears in optstring, the argument characteristics must match, otherwise it is added. See long_option() for more information. If 'W', followed by a semi-colon ';' appears in optstring, then any time a 'W' appears on the command line, the following argument is treated as a long option. For example, if the command line contains "program -W foo", "foo" is treated as a long option, that is, as if "program --foo" had been passed. The following characters can appear in optstring before any option characters, with the described effect:
  • '+' changes the ordering to REQUIRE_ORDER.
  • '-' changes the ordering to RETURN_IN_ORDER.
  • ':' changes the return value from operator() and get_opt() from '?' to ':' when an option requires an argument but none is specified.
skip_args Optional (default 1). The specified number of initial elements in argv are skipped before parsing begins. Thus, the default prevents argv[0] (usually the command name) from being parsed. argc includes all argv elements, including any skipped elements.
report_errors Optional, if non-zero then parsing errors cause an error message to be displayed from the operator() method before it returns. The error message is suppressed if this argument is 0. This setting also controls whether or not an error message is displayed in long_option() encounters an error.
ordering Optional (default is PERMUTE_ARGS); determines how the argv elements are processed. This argument is overridden by two factors:
  1. The POSIXLY_CORRECT environment variable. If this environment variable is set, the ordering is changed to REQUIRE_ORDER.
  2. Leading characters in optstring (see above). Any leading ordering characters override both the ordering argument and any effect of the POSIXLY_CORRECT environment variable.
long_only Optional. If non-zero, then long options can be specified using a single '-' on the command line. If the token is not a long option, it is processed as usual, that is, as a short option or set of short options.
Multiple short options can be combined as long as only the last one can takes an argument. For example, if optstring is defined as "abc:" or "abc::" then the command line "program -abcxxx" short options a, b, and c are found with "xxx" as the argument for c. However, if the command line is specified as "program -acb" only options a and c are found with "b" as the argument for c. Also, for options with optional arguments, that is, those followed by "::", the argument must be in the same argv element, so "program -abc xxx" will only find "xxx" as the argument for c if optstring is specified as "abc:" not "abc::".

ACE_Get_Opt::~ACE_Get_Opt void   ) 
 

Default dtor.

ACE_Get_Opt::ACE_Get_Opt const ACE_Get_Opt  )  [private]
 


Member Function Documentation

ACE_INLINE int ACE_Get_Opt::argc void   )  const
 

The number of arguments in the internal argv_.

ACE_INLINE ACE_TCHAR ** ACE_Get_Opt::argv void   )  const
 

Accessor for the internal argv_ pointer.

void ACE_Get_Opt::dump void   )  const
 

Dump the state of an object.

void ACE_Get_Opt::last_option const ACE_TString s  )  [private]
 

Set last_option.

const ACE_TCHAR * ACE_Get_Opt::last_option void   )  const
 

Accessor for the last_option that was processed. This allows applications to know if the found option was a short or long option, and is especially useful in cases where it was invalid and the caller wants to print out the invalid value.

const ACE_TCHAR * ACE_Get_Opt::long_option void   )  const
 

Returns the name of the long option found on the last call to operator() or 0 if none was found.

ACE_Get_Opt::Option ACE_Get_Opt::long_option const ACE_TCHAR name,
Option  short_option,
OPTION_ARG_MODE  has_arg = NO_ARG
 

Adds a long option with a corresponding short option.

Parameters:
name The long option to add.
short_option A character, the short option that corresponds to name.
has_arg Defines the argument requirements for the new option. If the short option has already been supplied in the optstring, has_arg must match or an error is returned; otherwise, the new short option is added to the optstring.
Return values:
0 Success
-1 The long option can not be added.

ACE_Get_Opt::Option ACE_Get_Opt::long_option const ACE_TCHAR name,
OPTION_ARG_MODE  has_arg = NO_ARG
 

Adds a long option with no corresponding short option.

If the name option is seen, operator() returns 0.

Parameters:
name The long option to add.
has_arg Defines the argument requirements for the new option.
Return values:
0 Success
-1 The long option can not be added.

ACE_Get_Opt::Option ACE_Get_Opt::long_option_i void   )  [private]
 

Handles long options.

ACE_Get_Opt::Option ACE_Get_Opt::nextchar_i void   )  [private]
 

Updates nextchar_.

ACE_Get_Opt::Option ACE_Get_Opt::operator() void   ) 
 

ACE_Get_Opt& ACE_Get_Opt::operator= const ACE_Get_Opt  )  [private]
 

ACE_INLINE ACE_TCHAR * ACE_Get_Opt::opt_arg void   )  const
 

For communication from operator() to the caller. When operator() finds an option that takes an argument, the argument value is returned from this method, otherwise it returns 0.

ACE_INLINE int & ACE_Get_Opt::opt_ind void   ) 
 

Index in argv of the next element to be scanned. This is used for communication to and from the caller and for communication between successive calls to operator(). On entry to operator(), zero means this is the first call; initialize.

When operator() returns EOF, this is the index of the first of the non-option elements that the caller should itself scan.

Otherwise, opt_ind() communicates from one call to the next how much of argv has been scanned so far.

ACE_INLINE ACE_Get_Opt::Option ACE_Get_Opt::opt_opt void   ) 
 

Returns the most recently matched option character. Especially useful when operator() returns ':' for an unspecified argument that's required, since this allows the caller to learn what option was specified without its required argument.

const ACE_TCHAR * ACE_Get_Opt::optstring void   )  const
 

Return the optstring. This is handy to verify that calls to long_option added short options as expected.

ACE_Get_Opt::Option ACE_Get_Opt::permute void   )  [private]
 

Handles reordering <argv>-elements.

void ACE_Get_Opt::permute_args void   )  [private]
 

If permuting args, this functions manages the nonopt_start_ and nonopt_end_ indexes and makes calls to permute to actually reorder the <argv>-elements.

ACE_Get_Opt::Option ACE_Get_Opt::short_option_i void   )  [private]
 

Handles short options.


Member Data Documentation

ACE_Get_Opt::ACE_ALLOC_HOOK_DECLARE [private]
 

Declare the dynamic allocation hooks.

int ACE_Get_Opt::argc_
 

Holds the argc count.

Deprecated:
This is public for backwards compatibility only. It will be made private in a release of ACE past 5.3. Do not write code that relies on this member being public; use the argc() accessor method instead.

ACE_TCHAR** ACE_Get_Opt::argv_
 

Holds the argv pointer.

Deprecated:
This is public for backwards compatibility only. It will be made private in a release of ACE past 5.3. Do not write code that relies on this member being public; use the argv() accessor method instead.

bool ACE_Get_Opt::has_colon_ [private]
 

Keeps track of whether or not a colon was passed in <optstring>. This is used to determine the return value when required arguments are missing.

ACE_TString* ACE_Get_Opt::last_option_ [private]
 

This is the last option, short or long, that was processed. This is handy to have in cases where the option passed was invalid.

bool ACE_Get_Opt::long_only_ [private]
 

Treat all options as long options.

ACE_Get_Opt_Long_Option* ACE_Get_Opt::long_option_ [private]
 

Points to the long_option found on last call to <operator()>.

ACE_Array<ACE_Get_Opt_Long_Option*> ACE_Get_Opt::long_opts_ [private]
 

Array of long options.

ACE_TCHAR* ACE_Get_Opt::nextchar_ [private]
 

The next char to be scanned in the option-element in which the last option character we returned was found. This allows us to pick up the scan where we left off * If this is zero, or a null string, it means resume the scan by advancing to the next <argv>-element.

int ACE_Get_Opt::nonopt_end_ [private]
 

Index of the <argv>-element following the last non-option element (only valid when permuting).

int ACE_Get_Opt::nonopt_start_ [private]
 

Index of the first non-option <argv>-element found (only valid when permuting).

ACE_TCHAR* ACE_Get_Opt::optarg
 

Deprecated:
This is public for backwards compatibility only. It will be made private in a release of ACE past 5.3. Do not write code that relies on this member being public; use the opt_arg() accessor method instead.

int ACE_Get_Opt::opterr
 

Deprecated:
This is public for backwards compatibility only. It will be made private in a release of ACE past 5.3. Do not write code that relies on this member being public; use the report_errors argument to this class's constructor instead.

int ACE_Get_Opt::optind
 

Index in argv_ of the next element to be scanned.

Deprecated:
This is public for backwards compatibility only. It will be made private in a release of ACE past 5.3. Do not write code that relies on this member being public; use the opt_ind() accessor method instead.

Option ACE_Get_Opt::optopt_ [private]
 

Most recently matched short option character.

ACE_TString* ACE_Get_Opt::optstring_ [private]
 

Holds the option string.

int ACE_Get_Opt::ordering_ [private]
 

Keeps track of ordering mode (default <PERMUTE_ARGS>).


The documentation for this class was generated from the following files:
Generated on Wed Nov 23 15:48:46 2005 for ACE by  doxygen 1.4.5