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

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

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


Public Methods

 ACE_Get_Opt (int argc, ACE_TCHAR **argv, const ACE_TCHAR *optstring, int skip_argv0=1, int report_errors=0, int ordering=PERMUTE_ARGS, int long_only=0)
 ~ACE_Get_Opt (void)
 Default dtor. More...

int operator() (void)
ACE_TCHARopt_arg (void) const
int & opt_ind (void)
int long_option (const ACE_TCHAR *name, OPTION_ARG_MODE has_arg=NO_ARG)
int long_option (const ACE_TCHAR *name, int short_option, OPTION_ARG_MODE has_arg=NO_ARG)
 Adds a long option with a corresponding short option. If the short option has already been supplied in the <optstring>, has_arg match match or an error is returned, otherwise the new short option it is added to the <optstring>. Returns 0 on success and -1 if the long option can not be added. More...

const ACE_TCHARlong_option (void) const
 Returns the name of the long option found on the last call to <operator()> or 0 if none was found. More...

ACE_TCHAR ** argv (void) const
 Accessor for the <argv_> pointer. More...

void dump (void) const
 Dump the state of an object. More...

const ACE_TCHARoptstring (void) const
 Return the <optstring>. This is handy to verify that calls to long_option added short options as expected. More...


Public Attributes

int argc_
 Holds the <argc> count. More...

ACE_TCHAR ** argv_
 Holds the <argv> pointer. More...

int optind
 Index in argv_ of the next element to be scanned. More...

int opterr
 Callers store zero here to inhibit the error message for unrecognized options. More...

ACE_TCHARoptarg
 Points to the option argument when one is found on last call to <operator()>. More...


Private Methods

int nextchar_i (void)
 Updates nextchar_. More...

int long_option_i (void)
 Handles long options. More...

int short_option_i (void)
 Handles short options. More...

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

int permute (void)
 Handles reordering <argv>-elements. More...

 ACE_Get_Opt (const ACE_Get_Opt &)
ACE_Get_Opt & operator= (const ACE_Get_Opt &)

Private Attributes

ACE_TString optstring_
 Holds the option string. More...

int long_only_
 Treat all options as long options. More...

int has_colon_
 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. More...

ACE_TCHARnextchar_
int ordering_
 Keeps track of ordering mode (default <PERMUTE_ARGS>). More...

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

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

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

ACE_Array< ACE_Get_Opt_Long_Option *> long_opts_
 Array of long options. More...

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks. More...


Detailed Description

Iterator for parsing command-line arguments.

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


Member Enumeration Documentation

anonymous enum
 

Mutually exclusive ordering values.

Enumeration values:
REQUIRE_ORDER  The options must come first, return <EOF> as soon as a non-option argument is encountered.
PERMUTE_ARGS  Reorder the arguments so that all the options come first (the order of the options and the following arguments are maintained).
RETURN_IN_ORDER  Continue processing the command line for each argument. The return value '1' signifies a non-option argument.

enum ACE_Get_Opt::OPTION_ARG_MODE
 

Mutually exclusive option argument mode used by long options.

Enumeration values:
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,
int    skip = 1,
int    report_errors = 0,
int    ordering = PERMUTE_ARGS,
int    long_only = 0
 

Initialize the internal data when the first call is made. Start processing options with <argv>-element 0 + <skip_argv0>; the sequence of previously skipped non-option <argv>-elements is empty.

<optstring> is a string containing the legitimate short option characters. A single colon ":" in <optstring> means that the previous character is an option that wants, requires, an argument, whereas a double colon "::" signifies 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), and returned in by <opt_arg ()>.

Multiple short options can be combined as long as only the last one can takes an argument, e.g., 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, e.g., 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::".

If a missing required option argument is detected, return the colon character ':' if the first character of <optstring> was a colon, or a '?' otherwise. (Note that the standards are unclear in this respect, 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.)

If an short option character is seen that is not listed in <optstring>, return '?' after printing an error message. If you set <report_errors> to zero, the error message is suppressed but we still return '?'.

<optstring> can be extended by adding long options, <long_option()>, that have corresponding short options. If the short option already appears in <optstring> they 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, e.g., if the command line contains "program -W foo" "foo" is treated as a long option, i.e., as if "program --foo" had been passed.

<ordering> refers to how the <argv>-elements are processed. <REQUIRE_ORDER> means that we stop processing and return <EOF> as soon as a non-option argument is found, and <opt_ind ()> holds the index of the next <argv>-element so the program can continue processing the rest of the <argv>-elements. If <PERMUTE_ARGS> (default) is passed, the <argv>-elements are reordered dynamically, permuted, so that all options appear first. When the last option has been process, <EOF> is returned and <opt_ind()> holds the index into the next non-option element. If <RETURN_IN_ORDER> is passed, then 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()> contains the <argv>-element found.

If <long_only> is non-zero, then all options are treated as long options. If a long option is not recognized, we try to find a matching short option.

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 ACE_TCHAR ** ACE_Get_Opt::argv void    const
 

Accessor for the <argv_> pointer.

void ACE_Get_Opt::dump void    const
 

Dump the state of an object.

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.

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

Adds a long option with a corresponding short option. If the short option has already been supplied in the <optstring>, has_arg match match or an error is returned, otherwise the new short option it is added to the <optstring>. Returns 0 on success and -1 if the long option can not be added.

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

int ACE_Get_Opt::long_option_i void    [private]
 

Handles long options.

int ACE_Get_Opt::nextchar_i void    [private]
 

Updates nextchar_.

int ACE_Get_Opt::operator() void   
 

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

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 successively each of the option characters from each of the option elements.

If <operator()> finds another option character, it returns that character, updating <optind> and <nextchar> so that the next call to <operator()> can resume the scan with the following option character or <argv>-element.

If <operator()> returns 0, it found a long option, '?' indicates an unknown option character, and '1' means that <RETURN_IN_ORDER> was specified and we found an non-option argument.

If there are no more option characters, <operator()> returns <EOF>. Then <opt_ind()> is 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.)

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 here, 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 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.

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

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

The following five data members should be private, but that would break backwards compatibility. However, we recommend not writing code that uses these fields directly.

ACE_TCHAR** ACE_Get_Opt::argv_
 

Holds the <argv> pointer.

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

int 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
 

Points to the option argument when one is found on last call to <operator()>.

int ACE_Get_Opt::opterr
 

Callers store zero here to inhibit the error message for unrecognized options.

int ACE_Get_Opt::optind
 

Index in argv_ of the next element to be scanned.

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 Sun Feb 17 17:38:43 2002 for ACE by doxygen1.2.13.1 written by Dimitri van Heesch, © 1997-2001