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)
| Constructor initializes the command line to be parsed. More...
| ~ACE_Get_Opt (void)
| Default dtor. More...
int | operator() (void)
| Scan elements of argv (whose length is argc) for short option characters given in optstring or long options (with no short option equivalents). More...
ACE_TCHAR * | opt_arg (void) const
| For communication from `operator()` to the caller. More...
int & | opt_ind (void)
| Index in argv of the next element to be scanned. More...
int | long_option (const ACE_TCHAR *name, OPTION_ARG_MODE has_arg=NO_ARG)
| Adds a long option with no corresponding short option. More...
int | long_option (const ACE_TCHAR *name, int short_option, OPTION_ARG_MODE has_arg=NO_ARG)
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 internal `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_
ACE_TCHAR ** | argv_
int | optind
int | opterr
ACE_TCHAR * | optarg
## 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_
| The next char to be scanned in the option-element in which the last option character we returned was found. More...
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
| ) |

  | 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 ":" in optstring means that the previous character is an option that requires an argument. 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). 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.
  skip_argv0 | 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. This value of argc includes all skipped elements of argv specified by this parameter.
  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.
  ordering | Optional (default is `PERMUTE_ARGS)`; refers to how the argv elements are processed. 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 (default) means the argv elements are reordered dynamically (permuted) so that all options appear first. 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 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.
  long_only | Optional. If non-zero, then all options are treated as long options. If a long option is not recognized, the class tries to find a matching short option.
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 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.

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

  | 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 it is added to the optstring.
  Return values:
  0 | Success
  -1 | The long option can not be added.

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

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 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. Return values:
  0 | A long option was found
  An | unknown option character was found and the first character of optstring was not a colon.
  : | ' An unknown option character was found and the first character of optstring was a colon.
  1 | ' `RETURN_IN_ORDER` was specified and a non-option argument was found.
  EOF | 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.

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

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

ACE_TCHAR** ACE_Get_Opt::argv_

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

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

| 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

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

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