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_args=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_opt (void)
int & opt_ind (void)
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)
 Adds a long option with a corresponding short option. 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...

int argc (void) const
 The number of arguments in the internal argv_. 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_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 optopt_
 Most recently matched short option character. 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_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).

Definition at line 42 of file Get_Opt.h.


Member Enumeration Documentation

anonymous enum
 

Mutually exclusive ordering values.

Enumeration values:
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.

Definition at line 46 of file Get_Opt.h.

00047   {
00048    /**
00049     * REQUIRE_ORDER means that processing stops and @c EOF is
00050     * returned as soon as a non-option argument is found. @c opt_ind()
00051     * will return the index of the next @a argv element so the program
00052     * can continue processing the rest of the @a argv elements.
00053     */
00054     REQUIRE_ORDER = 1,
00055 
00056    /**
00057     * PERMUTE_ARGS means the @a argv elements are reordered dynamically
00058     * (permuted) so that all options appear first. When the elements are
00059     * permuted, the order of the options and the following arguments are
00060     * maintained. When the last option has been processed, @c EOF is
00061     * returned and @c opt_ind() returns the index into the next non-option
00062     * element.
00063     */
00064     PERMUTE_ARGS = 2,
00065 
00066    /**
00067     * RETURN_IN_ORDER means each @a argv element is processed in the
00068     * order is it seen.  If the element is not recognized as an option, '1'
00069     * is returned and @c opt_arg() refers to the @a argv element found.
00070     */
00071     RETURN_IN_ORDER = 3
00072   };

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.

Definition at line 75 of file Get_Opt.h.

00076   {
00077     /// Doesn't take an argument.
00078     NO_ARG = 0,
00079 
00080     /// Requires an argument, same as passing ":" after a short option
00081     /// character in @a optstring.
00082     ARG_REQUIRED = 1,
00083 
00084     /// Argument is optional, same as passing "::" after a short
00085     /// option character in @a optstring.
00086     ARG_OPTIONAL = 2
00087   };


Constructor & Destructor Documentation

ACE_Get_Opt::ACE_Get_Opt int    argc,
ACE_TCHAR **    argv,
const ACE_TCHAR   optstring,
int    skip_args = 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 ":" 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.
Parameters:
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.
Parameters:
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::".

Definition at line 85 of file Get_Opt.cpp.

References ACE_LIB_TEXT, ACE_TCHAR, ACE_TRACE, ACE_OS::getenv, has_colon_, optstring, ordering_, REQUIRE_ORDER, and RETURN_IN_ORDER.

00092   : argc_ (argc),
00093     argv_ (argv),
00094     optind (skip),
00095     opterr (report_errors),
00096     optarg (0),
00097     optstring_ (optstring),
00098     long_only_ (long_only),
00099     has_colon_ (0),
00100     nextchar_ (0),
00101     optopt_ (0),
00102     ordering_ (ordering),
00103     nonopt_start_ (optind),
00104     nonopt_end_ (optind),
00105     long_option_ (0)
00106 {
00107   ACE_TRACE ("ACE_Get_Opt::ACE_Get_Opt");
00108 
00109   // First check to see if POSIXLY_CORRECT was set.
00110   if (ACE_OS::getenv (ACE_LIB_TEXT ("POSIXLY_CORRECT")) != 0)
00111     this->ordering_ = REQUIRE_ORDER;
00112 
00113   // Now, check to see if any or the following were passed at
00114   // the begining of optstring: '+' same as POSIXLY_CORRECT;
00115   // '-' turns off POSIXLY_CORRECT; or ':' which signifies we
00116   // should return ':' if a parameter is missing for an option.
00117   // We use a loop here, since a combination of "{+|-}:" in any
00118   // order should be legal.
00119   int done  = 0;
00120   int offset = 0;
00121   while (!done)
00122     {
00123       switch (optstring[offset++])
00124         {
00125         case '+':
00126           this->ordering_ = REQUIRE_ORDER;
00127           break;
00128         case '-':
00129           this->ordering_ = RETURN_IN_ORDER;
00130           break;
00131         case ':':
00132           this->has_colon_ = 1;
00133           break;
00134         default:
00135           // Quit as soon as we see something else...
00136           done = 1;
00137           break;
00138         }
00139     }
00140 }

ACE_Get_Opt::~ACE_Get_Opt void   
 

Default dtor.

Definition at line 142 of file Get_Opt.cpp.

References ACE_TRACE, ACE_Array_Base< ACE_Get_Opt_Long_Option * >::get, long_opts_, and ACE_Array_Base< ACE_Get_Opt_Long_Option * >::size.

00143 {
00144   ACE_TRACE ("ACE_Get_Opt::~ACE_Get_Opt");
00145 
00146   size_t i = 0;
00147   size_t size = this->long_opts_.size ();
00148   ACE_Get_Opt_Long_Option *option = 0;
00149   for (i = 0; i < size; ++i)
00150     {
00151      int retval = this->long_opts_.get (option, i);
00152       if (retval != 0)
00153         {
00154           // Should never happen.
00155           retval = 0;
00156           continue;
00157         }
00158       if (option)
00159         {
00160           delete option;
00161           option = 0;
00162         }
00163     }
00164 }

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

Definition at line 13 of file Get_Opt.i.

References argc_.

00014 { 
00015   return this->argc_; 
00016 }

ACE_INLINE ACE_TCHAR ** ACE_Get_Opt::argv void    const
 

Accessor for the internal argv_ pointer.

Definition at line 19 of file Get_Opt.i.

References argv_.

00020 { 
00021   return this->argv_; 
00022 }

void ACE_Get_Opt::dump void    const
 

Dump the state of an object.

Definition at line 559 of file Get_Opt.cpp.

References ACE_BEGIN_DUMP, ACE_DEBUG, ACE_END_DUMP, ACE_LIB_TEXT, ACE_TRACE, and LM_DEBUG.

00560 {
00561   ACE_TRACE ("ACE_Get_Opt::dump");
00562 
00563   ACE_DEBUG ((LM_DEBUG, ACE_BEGIN_DUMP, this));
00564   ACE_DEBUG ((LM_DEBUG,  ACE_LIB_TEXT ("\n")));
00565   ACE_DEBUG ((LM_DEBUG, ACE_END_DUMP));
00566 }

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.

Definition at line 550 of file Get_Opt.cpp.

References ACE_TRACE, long_option_, and ACE_Get_Opt::ACE_Get_Opt_Long_Option::name_.

Referenced by long_option.

00551 {
00552   ACE_TRACE ("ACE_Get_Opt::long_option (void)");
00553   if (this->long_option_)
00554     return this->long_option_->name_;
00555   return 0;
00556 }

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.

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.

Definition at line 450 of file Get_Opt.cpp.

References ACE_ERROR, ACE_ERROR_RETURN, ACE_LIB_TEXT, ACE_TCHAR, ACE_TRACE, ARG_OPTIONAL, ARG_REQUIRED, LM_ERROR, long_opts_, NO_ARG, opterr, optstring_, ACE_Array_Base< ACE_Get_Opt_Long_Option * >::set, ACE_Array_Base< ACE_Get_Opt_Long_Option * >::size, and ACE_OS_String::strchr.

00453 {
00454   ACE_TRACE ("ACE_Get_Opt::long_option (const ACE_TCHAR *name, int short_option, OPTION_ARG_MODE has_arg)");
00455 
00456   // We only allow valid alpha-numeric characters as short options.
00457   // If short_options is not a valid alpha-numeric, we can still return it
00458   // when the long option is found, but won't allow the caller to pass it on
00459   // the command line (how could they?).  The special case is 0, but since
00460   // we always return it, we let the caller worry about that.
00461 #if defined (_MSC_VER) && (_MSC_VER >= 1300)
00462   // For MSVC 7.x, we need to prevent "illegal" character getting into
00463   // isalnum, otherwise, it will crash the program.
00464   if (short_option > 0 &&
00465       short_option < 256 &&
00466       isalnum (short_option) != 0)
00467 #else
00468   if (isalnum (short_option) != 0)
00469 #endif /* _MSC_VER && _MSC_VER >= 1300 */
00470     {
00471       // If the short_option already exists, make sure it matches, otherwise
00472       // add it.
00473       ACE_TCHAR *s = 0;
00474       if ((s = ACE_const_cast (ACE_TCHAR*,
00475                                ACE_OS::strchr (this->optstring_.c_str (), short_option))) != 0)
00476         {
00477           // Short option exists, so verify the argument options
00478           if (s[1] == ':')
00479             {
00480               if (s[2] == ':')
00481                 {
00482                   if (has_arg != ARG_OPTIONAL)
00483                     {
00484                       if (this->opterr)
00485                         ACE_ERROR
00486                           ((LM_ERROR,
00487                             ACE_LIB_TEXT ("Existing short option '%c' takes ")
00488                             ACE_LIB_TEXT ("optional argument; adding %s ")
00489                             ACE_LIB_TEXT ("requires ARG_OPTIONAL\n"),
00490                             short_option, name));
00491                       return -1;
00492                     }
00493                 }
00494               else
00495                 if (has_arg != ARG_REQUIRED)
00496                   {
00497                     if (this->opterr)
00498                       ACE_ERROR
00499                         ((LM_ERROR,
00500                           ACE_LIB_TEXT ("Existing short option '%c' requires ")
00501                           ACE_LIB_TEXT ("an argument; adding %s ")
00502                           ACE_LIB_TEXT ("requires ARG_REQUIRED\n"),
00503                           short_option, name));
00504                     return -1;
00505                   }
00506             }
00507           else if (has_arg != NO_ARG)
00508             {
00509               if (this->opterr)
00510                 ACE_ERROR
00511                   ((LM_ERROR,
00512                     ACE_LIB_TEXT ("Existing short option '%c' does not ")
00513                     ACE_LIB_TEXT ("accept an argument; adding %s ")
00514                     ACE_LIB_TEXT ("requires NO_ARG\n"),
00515                     short_option, name));
00516               return -1;
00517             }
00518         }
00519       else
00520         {
00521           // Didn't find short option, so add it...
00522           this->optstring_ += (ACE_TCHAR) short_option;
00523           if (has_arg == ARG_REQUIRED)
00524             this->optstring_ += ACE_LIB_TEXT (":");
00525           else if (has_arg == ARG_OPTIONAL)
00526             this->optstring_ += ACE_LIB_TEXT ("::");
00527         }
00528     }
00529 
00530   ACE_Get_Opt_Long_Option *option =
00531     new ACE_Get_Opt_Long_Option (name, has_arg, short_option);
00532 
00533   if (!option)
00534     return -1;
00535 
00536   // Add to array
00537   size_t size = this->long_opts_.size ();
00538   if (this->long_opts_.size (size + 1) != 0
00539       || this->long_opts_.set (option, size) != 0)
00540     {
00541       delete option;
00542       ACE_ERROR_RETURN
00543         ((LM_ERROR, ACE_LIB_TEXT ("Could not add long option to array.\n")),
00544          -1);
00545     }
00546   return 0;
00547 }

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.

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.

Definition at line 442 of file Get_Opt.cpp.

References ACE_TCHAR, ACE_TRACE, and long_option.

00444 {
00445   ACE_TRACE ("ACE_Get_Opt::long_option (const ACE_TCHAR *name, OPTION_ARG_MODE has_arg)");
00446   return this->long_option (name, 0, has_arg);
00447 }

int ACE_Get_Opt::long_option_i void    [private]
 

Handles long options.

Definition at line 215 of file Get_Opt.cpp.

References ACE_ASSERT, ACE_ERROR, ACE_LIB_TEXT, ACE_TCHAR, ACE_TRACE, ARG_REQUIRED, argc_, argv_, ACE_String_Base< char >::find, has_colon_, LM_ERROR, long_only_, long_option_, long_opts_, nextchar_, NO_ARG, optarg, opterr, optind, optopt_, optstring_, short_option_i, ACE_Array_Base< ACE_Get_Opt_Long_Option * >::size, ACE_OS_String::strlen, and ACE_OS_String::strncmp.

Referenced by operator(), and short_option_i.

00216 {
00217   ACE_TRACE ("ACE_Get_Opt::long_option_i");
00218 
00219   ACE_Get_Opt_Long_Option *p;
00220   ACE_TCHAR *s = this->nextchar_;
00221   int hits = 0;
00222   int exact = 0;
00223   ACE_Get_Opt_Long_Option *pfound = 0;
00224   int indfound = 0;
00225 
00226   // Advance to the end of the long option name so we can use
00227   // it to get the length for a string compare.
00228   while (*s && *s != '=')
00229     s++;
00230 
00231   size_t len = s - this->nextchar_;
00232   size_t size = this->long_opts_.size ();
00233   u_int option_index = 0;
00234   for (option_index = 0; option_index < size ; option_index++)
00235     {
00236       p = this->long_opts_[option_index];
00237       ACE_ASSERT (p);
00238 
00239       if (!ACE_OS::strncmp (p->name_, this->nextchar_, len))
00240         {
00241           // Got at least a partial match.
00242           pfound = p;
00243           indfound = option_index;
00244           hits += 1;
00245           if (len == ACE_OS::strlen(p->name_))
00246             {
00247               // And in fact, it an exact match, so let's use it.
00248               exact = 1;
00249               break;
00250             }
00251         }
00252     }
00253 
00254   if ((hits > 1) && !exact)
00255     {
00256       // Great, we found a match, but unfortunately we found more than
00257       // one and it wasn't exact.
00258       if (this->opterr)
00259         ACE_ERROR ((LM_ERROR,
00260                     ACE_LIB_TEXT ("%s: option `%s' is ambiguous\n"),
00261                     this->argv_[0], this->argv_[this->optind]));
00262       this->nextchar_ = 0;
00263       this->optind++;
00264       return '?';
00265     }
00266 
00267   if (pfound != 0)
00268     {
00269       // Okay, we found a good one (either a single hit or an exact match).
00270       option_index = indfound;
00271       this->optind++;
00272       if (*s)
00273         {
00274           // s must point to '=' which means there's an argument (well
00275           // close enough).
00276           if (pfound->has_arg_ != NO_ARG)
00277             // Good, we want an argument and here it is.
00278             this->optarg = ++s;
00279           else
00280             {
00281               // Whoops, we've got what looks like an argument, but we
00282               // don't want one.
00283               if (this->opterr)
00284                   ACE_ERROR
00285                     ((LM_ERROR,
00286                       ACE_LIB_TEXT ("%s: long option `--%s' doesn't allow an argument\n"),
00287                       this->argv_[0], pfound->name_));
00288               // The spec doesn't cover this, so we keep going and the program
00289               // doesn't know we ignored an argument if opt_err is off!!!
00290             }
00291         }
00292       else if (pfound->has_arg_ == ARG_REQUIRED)
00293         {
00294           // s didn't help us, but we need an argument. Note that
00295           // optional arguments for long options must use the "=" syntax,
00296           // so we won't get here in that case.
00297           if (this->optind < this->argc_)
00298             // We still have some elements left, so use the next one.
00299             this->optarg = this->argv_[this->optind++];
00300           else
00301             {
00302               // All out of elements, so we have to punt...
00303               if (this->opterr)
00304                 ACE_ERROR ((LM_ERROR,
00305                             ACE_LIB_TEXT ("%s: long option '--%s' requires an argument\n"),
00306                             this->argv_[0], pfound->name_));
00307               this->nextchar_ = 0;
00308               this->optopt_ = pfound->val_;   // Remember matching short equiv
00309               return this->has_colon_ ? ':' : '?';
00310             }
00311         }
00312       this->nextchar_ = 0;
00313       this->long_option_ = pfound;
00314       // Since val_ has to be either a valid short option or 0, this works
00315       // great.  If the user really wants to know if a long option was passed.
00316       this->optopt_ = pfound->val_;
00317       return pfound->val_;
00318     }
00319   if (!this->long_only_ || this->argv_[this->optind][1] == '-'
00320       || this->optstring_.find (*this->nextchar_) == ACE_TString::npos)
00321     {
00322       // Okay, we couldn't find a long option.  If it isn't long_only (which
00323       // means try the long first, and if not found try the short) or a long
00324       // signature was passed, e.g. "--", or it's not a short (not sure when
00325       // this could happen) it's an error.
00326       if (this->opterr)
00327         ACE_ERROR ((LM_ERROR,
00328                     ACE_LIB_TEXT ("%s: illegal long option '--%s'\n"),
00329                     this->argv_[0], this->nextchar_));
00330       this->nextchar_ = 0;
00331       this->optind++;
00332       return '?';
00333     }
00334   return this->short_option_i ();
00335 }

int ACE_Get_Opt::nextchar_i void    [private]
 

Updates nextchar_.

Definition at line 167 of file Get_Opt.cpp.

References ACE_TRACE, argc_, argv_, long_opts_, nextchar_, optarg, optind, ordering_, permute, PERMUTE_ARGS, REQUIRE_ORDER, and ACE_Array_Base< ACE_Get_Opt_Long_Option * >::size.

Referenced by operator().

00168 {
00169   ACE_TRACE ("ACE_Get_Opt::nextchar_i");
00170 
00171   if (this->ordering_ == PERMUTE_ARGS)
00172     if (this->permute () == EOF)
00173       return EOF;
00174 
00175   // Update scanning pointer.
00176   if (this->optind >= this->argc_)
00177     {
00178       // We're done...
00179       this->nextchar_ = 0;
00180       return EOF;
00181     }
00182   else if (*(this->nextchar_ = this->argv_[this->optind]) != '-'
00183             || this->nextchar_[1] == '\0')
00184     {
00185       // We didn't get an option.
00186 
00187       if (this->ordering_ == REQUIRE_ORDER
00188           || this->ordering_ == PERMUTE_ARGS)
00189         // If we permuted or require the options to be in order, we're done.
00190         return EOF;
00191 
00192       // It must be RETURN_IN_ORDER...
00193       this->optarg = this->argv_[this->optind++];
00194       this->nextchar_ = 0;
00195       return 1;
00196     }
00197   else if (this->nextchar_[1] != 0
00198            && *++this->nextchar_ == '-'
00199            && this->nextchar_[1] == 0)
00200     {
00201       // Found "--" so we're done...
00202       ++this->optind;
00203       this->nextchar_ = 0;
00204       return EOF;
00205     }
00206 
00207   // If it's a long option, and we allow long options advance nextchar_.
00208   if (*this->nextchar_ == '-' && this->long_opts_.size () != 0)
00209     this->nextchar_++;
00210 
00211   return 0;
00212 }

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

Definition at line 410 of file Get_Opt.cpp.

References ACE_TRACE, argv_, long_only_, long_option_, long_option_i, nextchar_, nextchar_i, optarg, optind, and short_option_i.

00411 {
00412   ACE_TRACE ("ACE_Get_Opt_Long::operator");
00413 
00414   // First of all, make sure we reinitialize any pointers..
00415   this->optarg = 0;
00416   this->long_option_ = 0;
00417 
00418   if (this->argv_ == 0)
00419     {
00420       // It can happen, e.g., on VxWorks.
00421       this->optind = 0;
00422       return -1;
00423     }
00424 
00425   // We check this because we can string short options together if the
00426   // preceding one doesn't take an argument.
00427   if (this->nextchar_ == 0 || *this->nextchar_ == '\0')
00428     {
00429       int retval = this->nextchar_i ();
00430       if (retval != 0)
00431         return retval;
00432     }
00433 
00434   if (((this->argv_[this->optind][0] == '-')
00435        && (this->argv_[this->optind][1] == '-')) || this->long_only_)
00436     return this->long_option_i ();
00437 
00438   return this->short_option_i ();
00439 }

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.

Definition at line 25 of file Get_Opt.i.

References optarg.

Referenced by ACE_Service_Manager::init, ACE_Service_Config::parse_args, ACE_Name_Options::parse_args, and ACE_Logging_Strategy::parse_args.

00026 { 
00027   return this->optarg; 
00028 }

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.

Definition at line 37 of file Get_Opt.i.

References optind.

00038 { 
00039   return this->optind; 
00040 }

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

Definition at line 31 of file Get_Opt.i.

References optopt_.

00032 {
00033   return this->optopt_;
00034 }

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.

Definition at line 43 of file Get_Opt.i.

References ACE_String_Base< char >::c_str, and optstring_.

Referenced by ACE_Get_Opt.

00044 { 
00045   return this->optstring_.c_str ();
00046 }

int ACE_Get_Opt::permute void    [private]
 

Handles reordering <argv>-elements.

Definition at line 604 of file Get_Opt.cpp.

References ACE_LIB_TEXT, ACE_TRACE, argc_, argv_, nonopt_end_, nonopt_start_, optind, permute_args, and ACE_OS_String::strcmp.

Referenced by nextchar_i.

00605 {
00606   ACE_TRACE ("ACE_Get_Opt::permute");
00607 
00608   if (this->nonopt_start_ != this->nonopt_end_
00609       && this->nonopt_start_ != this->optind)
00610     this->permute_args ();
00611 
00612   this->nonopt_start_ = this->optind;
00613 
00614   // Skip over args untill we find the next option.
00615   while (this->optind < this->argc_
00616          && (this->argv_[this->optind][0] != '-'
00617              || this->argv_[this->optind][1] == '\0'))
00618     this->optind++;
00619 
00620   // Got an option, so mark this as the end of the non options.
00621   this->nonopt_end_ = this->optind;
00622 
00623   if (this->optind != this->argc_
00624       && ACE_OS::strcmp (this->argv_[this->optind],
00625                          ACE_LIB_TEXT ("--")) == 0)
00626     {
00627       // We found the marker for the end of the options.
00628       this->optind++;
00629 
00630       if (this->nonopt_start_ != this->nonopt_end_
00631           && this->nonopt_end_ != this->optind)
00632         this->permute_args ();
00633     }
00634 
00635   if (this->optind == this->argc_)
00636     {
00637       if (this->nonopt_start_ != this->nonopt_end_)
00638         this->optind = this->nonopt_start_;
00639       return EOF;
00640     }
00641   return 0;
00642 }

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.

Definition at line 569 of file Get_Opt.cpp.

References ACE_TCHAR, ACE_TRACE, argv_, ACE::gcd, nonopt_end_, nonopt_start_, and optind.

Referenced by permute.

00570 {
00571   ACE_TRACE ("ACE_Get_Opt::permute_args");
00572 
00573   int cstart, cyclelen, i, j, ncycle, nnonopts, nopts, pos;
00574   ACE_TCHAR *swap;
00575   int opt_end = this->optind;
00576 
00577   nnonopts = this->nonopt_end_ - this->nonopt_start_;
00578   nopts = opt_end - this->nonopt_end_;
00579   ncycle = ACE::gcd (nnonopts, nopts);
00580   cyclelen = (opt_end - this->nonopt_start_) / ncycle;
00581 
00582   this->optind = this->optind - nnonopts;
00583 
00584   for (i = 0; i < ncycle; i++)
00585     {
00586       cstart = this->nonopt_end_ + i;
00587       pos = cstart;
00588       for (j = 0; j < cyclelen; j++)
00589         {
00590           if (pos >= this->nonopt_end_)
00591             pos -= nnonopts;
00592           else
00593             pos += nopts;
00594           swap = this->argv_[pos];
00595 
00596           ((ACE_TCHAR **)this->argv_)[pos] = argv_[cstart];
00597 
00598           ((ACE_TCHAR **)this->argv_)[cstart] = swap;
00599         }
00600     }
00601 }

int ACE_Get_Opt::short_option_i void    [private]
 

Handles short options.

Definition at line 338 of file Get_Opt.cpp.

References ACE_ERROR, ACE_LIB_TEXT, ACE_TCHAR, ACE_TRACE, argc_, argv_, has_colon_, LM_ERROR, long_option_i, nextchar_, optarg, opterr, optind, optopt_, and ACE_OS_String::strchr.

Referenced by long_option_i, and operator().

00339 {
00340   ACE_TRACE ("ACE_Get_Opt::short_option_i");
00341 
00342   /* Look at and handle the next option-character.  */
00343   ACE_TCHAR opt = *this->nextchar_++;
00344   ACE_TCHAR *oli = 0;
00345   oli = ACE_const_cast (ACE_TCHAR*, ACE_OS::strchr (this->optstring_.c_str (), opt));
00346 
00347   /* Increment `optind' when we start to process its last character.  */
00348   if (*this->nextchar_ == '\0')
00349     ++this->optind;
00350 
00351   if (oli == 0 || opt == ':')
00352     {
00353       if (this->opterr)
00354         ACE_ERROR ((LM_ERROR,
00355                     ACE_LIB_TEXT ("%s: illegal short option -- %c\n"),
00356                     this->argv_[0], opt));
00357       return '?';
00358     }
00359   if (opt == 'W' && oli[1] == ';')
00360     {
00361       if (this->nextchar_[0] == 0)
00362         this->nextchar_ = this->argv_[this->optind];
00363       return long_option_i ();
00364     }
00365   this->optopt_ = oli[0];      // Remember the option that matched
00366   if (oli[1] == ':')
00367     {
00368       if (oli[2] == ':')
00369         {
00370           // Takes an optional argument, and since short option args must
00371           // must follow directly in the same argument, a NULL nextchar_
00372           // means we didn't get one.
00373           if (*this->nextchar_ != '\0')
00374             {
00375               this->optarg = this->nextchar_;
00376               this->optind++;
00377             }
00378           else
00379             this->optarg = 0;
00380           this->nextchar_ = 0;
00381         }
00382       else
00383         {
00384           // Takes a required argument.
00385           if (*this->nextchar_ != '\0')
00386             {
00387               // Found argument in same argv-element.
00388               this->optarg = this->nextchar_;
00389               this->optind++;
00390             }
00391           else if (this->optind == this->argc_)
00392             {
00393               // Ran out of arguments before finding required argument.
00394               if (this->opterr)
00395                 ACE_ERROR ((LM_ERROR,
00396                             ACE_LIB_TEXT ("%s: short option requires an argument -- %c\n"),
00397                             this->argv_[0], opt));
00398               opt = this->has_colon_ ? ':' : '?';
00399             }
00400           else
00401             // Use the next argv-element as the argument.
00402             this->optarg = this->argv_[this->optind++];
00403           this->nextchar_ = 0;
00404         }
00405     }
00406   return opt;
00407 }


Member Data Documentation

ACE_Get_Opt::ACE_ALLOC_HOOK_DECLARE [private]
 

Declare the dynamic allocation hooks.

Definition at line 441 of file Get_Opt.h.

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.

Definition at line 310 of file Get_Opt.h.

Referenced by argc, long_option_i, nextchar_i, permute, and short_option_i.

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.

Definition at line 319 of file Get_Opt.h.

Referenced by argv, long_option_i, nextchar_i, operator(), permute, permute_args, and short_option_i.

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.

Definition at line 409 of file Get_Opt.h.

Referenced by ACE_Get_Opt, long_option_i, and short_option_i.

int ACE_Get_Opt::long_only_ [private]
 

Treat all options as long options.

Definition at line 404 of file Get_Opt.h.

Referenced by long_option_i, and operator().

ACE_Get_Opt_Long_Option* ACE_Get_Opt::long_option_ [private]
 

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

Definition at line 435 of file Get_Opt.h.

Referenced by long_option, long_option_i, and operator().

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

Array of long options.

Definition at line 438 of file Get_Opt.h.

Referenced by long_option, long_option_i, nextchar_i, and ~ACE_Get_Opt.

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.

Definition at line 418 of file Get_Opt.h.

Referenced by long_option_i, nextchar_i, operator(), and short_option_i.

int ACE_Get_Opt::nonopt_end_ [private]
 

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

Definition at line 432 of file Get_Opt.h.

Referenced by permute, and permute_args.

int ACE_Get_Opt::nonopt_start_ [private]
 

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

Definition at line 428 of file Get_Opt.h.

Referenced by permute, and permute_args.

ACE_TCHAR* ACE_Get_Opt::optarg
 

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

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.

Definition at line 348 of file Get_Opt.h.

Referenced by long_option_i, nextchar_i, operator(), opt_arg, and short_option_i.

int ACE_Get_Opt::opterr
 

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

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.

Definition at line 338 of file Get_Opt.h.

Referenced by long_option, long_option_i, and short_option_i.

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.

Definition at line 328 of file Get_Opt.h.

Referenced by long_option_i, nextchar_i, operator(), opt_ind, permute, permute_args, and short_option_i.

int ACE_Get_Opt::optopt_ [private]
 

Most recently matched short option character.

Definition at line 421 of file Get_Opt.h.

Referenced by long_option_i, opt_opt, and short_option_i.

ACE_TString ACE_Get_Opt::optstring_ [private]
 

Holds the option string.

Definition at line 401 of file Get_Opt.h.

Referenced by long_option, long_option_i, and optstring.

int ACE_Get_Opt::ordering_ [private]
 

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

Definition at line 424 of file Get_Opt.h.

Referenced by ACE_Get_Opt, and nextchar_i.


The documentation for this class was generated from the following files:
Generated on Mon Jun 16 12:48:16 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002