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:

[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_TCHAR * | opt_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_TCHAR * | long_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_TCHAR * | optstring (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_TCHAR * | optarg
| 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_TCHAR * | nextchar_
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_Option * | long_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:

- Get_Opt.h
- Get_Opt.cpp
- Get_Opt.i