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

Get_Opt.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //==========================================================================
00004 /**
00005  *  @file    Get_Opt.h
00006  *
00007  *  $Id: Get_Opt.h,v 1.1.1.4 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
00010  *  @author Don Hinton <dhinton@gmx.net> (added long option support)
00011  */
00012 //==========================================================================
00013 
00014 #ifndef ACE_GET_OPT_H
00015 #define ACE_GET_OPT_H
00016 #include "ace/pre.h"
00017 
00018 #include "ace/SString.h"
00019 #include "ace/Containers.h"
00020 
00021 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00022 # pragma once
00023 #endif /* ACE_LACKS_PRAGMA_ONCE */
00024 
00025 #undef optind
00026 #undef optarg
00027 #undef opterr
00028 
00029 /*
00030  *  These definitions are for backward compatibility with previous versions.
00031  *  of ACE_Get_Opt.
00032  */
00033 
00034 /**
00035  * @class ACE_Get_Opt
00036  *
00037  * @brief Iterator for parsing command-line arguments.
00038  *
00039  * This is a C++ wrapper for getopt(3c) and getopt_long(3c).
00040  */
00041 
00042 class ACE_Export ACE_Get_Opt
00043 {
00044 public:
00045   /// Mutually exclusive ordering values.
00046   enum
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   };
00073 
00074   /// Mutually exclusive option argument mode used by long options.
00075   enum OPTION_ARG_MODE
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   };
00088 
00089   /**
00090    * Constructor initializes the command line to be parsed. All information
00091    * for parsing must be supplied to this constructor.
00092    *
00093    * @param argc          The number of @a argv elements to parse.
00094    * @param argv          Command line tokens, such as would be passed
00095    *                      to @c main().
00096    * @param optstring     Nul-terminated string containing the legitimate
00097    *                      short option characters.  A single colon ":"
00098    *                      following an option character means the option
00099    *                      requires an argument.  A double colon "::" following
00100    *                      an option character means the argument is optional.
00101    *                      The argument is taken from the rest of the current
00102    *                      @a argv element, or from the following @a argv
00103    *                      element (only valid for required arguments;
00104    *                      optional arguments must always reside in the same
00105    *                      @a argv element). The argument value, if any is
00106    *                      returned by the @c opt_arg() method.
00107    *                      @a optstring can be extended by adding long options
00108    *                      with corresponding short options via the
00109    *                      @c long_option() method.  If the short option
00110    *                      already appears in @a optstring, the argument
00111    *                      characteristics must match, otherwise it is added.
00112    *                      See @c long_option() for more information.
00113    *                      If 'W', followed by a semi-colon ';' appears in
00114    *                      @a optstring, then any time a 'W' appears on the
00115    *                      command line, the following argument is treated as
00116    *                      a long option.  For example, if the command line
00117    *                      contains "program -W foo", "foo" is treated as a
00118    *                      long option, that is, as if "program --foo" had
00119    *                      been passed.
00120    *                      The following characters can appear in @a optstring
00121    *                      before any option characters, with the described
00122    *                      effect:
00123    *                      - '+' changes the @a ordering to @a REQUIRE_ORDER.
00124    *                      - '-' changes the @a ordering to @a RETURN_IN_ORDER.
00125    *                      - ':' changes the return value from @c operator()
00126    *                            and get_opt() from '?' to ':' when an option
00127    *                            requires an argument but none is specified.
00128    *
00129    * @param skip_args     Optional (default 1). The specified number of
00130    *                      initial elements in @a argv are skipped before
00131    *                      parsing begins. Thus, the default prevents
00132    *                      @a argv[0] (usually the command name) from being
00133    *                      parsed. @a argc includes all @a argv elements,
00134    *                      including any skipped elements.
00135    * @param report_errors Optional, if non-zero then parsing errors cause
00136    *                      an error message to be displayed from the
00137    *                      @c operator() method before it returns. The
00138    *                      error message is suppressed if this argument is 0.
00139    *                      This setting also controls whether or not an error
00140    *                      message is displayed in @c long_option() encounters
00141    *                      an error.
00142    * @param ordering      Optional (default is @c PERMUTE_ARGS); determines
00143    *                      how the @a argv elements are processed. This argument
00144    *                      is overridden by two factors:
00145    *                      -# The @c POSIXLY_CORRECT environment variable. If
00146    *                         this environment variable is set, the ordering
00147    *                         is changed to @c REQUIRE_ORDER.
00148    *                      -# Leading characters in @a optstring (see above).
00149    *                         Any leading ordering characters override both
00150    *                         the @a ordering argument and any effect of the
00151    *                         @c POSIXLY_CORRECT environment variable.
00152    * @param long_only     Optional. If non-zero, then all options are treated
00153    *                      as long options.  If a long option is not
00154    *                      recognized, the class tries to find a matching
00155    *                      short option.
00156    *
00157    * Multiple short options can be combined as long as only the last
00158    * one can takes an argument. For example, if @a optstring is defined as
00159    * @c "abc:" or @c "abc::" then the command line @e "program -abcxxx" short
00160    * options @e a, @e b, and @e c are found with @e "xxx" as the argument for
00161    * @e c.
00162    * However, if the command line is specified as @e "program -acb" only
00163    * options @e a and @e c are found with @e "b" as the argument for @e c.
00164    * Also, for options with optional arguments, that is, those followed by
00165    * "::", the argument must be in the same @a argv element, so "program -abc
00166    * xxx" will only find "xxx" as the argument for @e c if @a optstring is
00167    * specified as @c "abc:" not @c "abc::".
00168    */
00169   ACE_Get_Opt (int argc,
00170                ACE_TCHAR **argv,
00171                const ACE_TCHAR *optstring,
00172                int skip_args = 1,
00173                int report_errors = 0,
00174                int ordering = PERMUTE_ARGS,
00175                int long_only = 0);
00176 
00177   /// Default dtor.
00178   ~ACE_Get_Opt (void);
00179 
00180   /**
00181    * Scan elements of @a argv (whose length is @a argc) for short option
00182    * characters given in @a optstring or long options (with no short
00183    * option equivalents).
00184    *
00185    * If an element of @a argv starts with '-', and is not exactly "-"
00186    * or "--", then it is a short option element.  The characters of this
00187    * element (aside from the initial '-') are option characters. If
00188    * it starts with "--" followed by other characters it is treated as
00189    * a long option.  If @c operator() is called repeatedly, it returns
00190    * each of the option characters from each of the option elements.
00191    *
00192    * @return The parsed option character. The following characters have
00193    * special significance.
00194    * @retval 0      A long option was found
00195    * @retval '\?'   Either an unknown option character was found, or the
00196    *                option is known but requires an argument, none was
00197    *                specified, and @a optstring did not contain a leading
00198    *                colon.
00199    * @retval ':'    A known option character was found but it requires an
00200    *                argument and none was supplied, and the first character
00201    *                of @a optstring was a colon. @c opt_opt() indicates
00202    *                which option was specified.
00203    * @retval '1'    @c RETURN_IN_ORDER was specified and a non-option argument
00204    *                was found.
00205    * @retval EOF No more option characters were found.  @c opt_ind() will
00206    *             return the index in @a argv of the first @a argv element
00207    *             that is not an option.  If @c PERMUTE_ARGS was
00208    *             specified, the @a argv elements have been permuted so that
00209    *             those that are not options now come last.
00210    *
00211    * @note The standards are unclear with respect to the conditions under
00212    * which '?' and ':' are returned, so we scan the initial characters of
00213    * @a optstring up unto the first short option character for '+', '-',
00214    * and ':' in order to determine ordering and missing argument behavior.
00215    */
00216   int operator () (void);
00217 
00218   /**
00219    * For communication from @c operator() to the caller.  When
00220    * @c operator() finds an option that takes an argument, the argument
00221    * value is returned from this method, otherwise it returns 0.
00222    */
00223   ACE_TCHAR *opt_arg (void) const;
00224 
00225   /**
00226    * Returns the most recently matched option character. Especially
00227    * useful when operator() returns ':' for an unspecified argument
00228    * that's required, since this allows the caller to learn what option
00229    * was specified without its required argument.
00230    */
00231   int opt_opt (void);
00232 
00233   /**
00234    * Index in @a argv of the next element to be scanned.  This is used
00235    * for communication to and from the caller and for communication
00236    * between successive calls to @c operator().  On entry to
00237    * @c operator(), zero means this is the first call; initialize.
00238    *
00239    * When @c operator() returns @c EOF, this is the index of the first of
00240    * the non-option elements that the caller should itself scan.
00241    *
00242    * Otherwise, @c opt_ind() communicates from one call to the next how
00243    * much of @a argv has been scanned so far.
00244    */
00245   int &opt_ind (void);
00246 
00247   /// Adds a long option with no corresponding short option.
00248   /**
00249    * If the @a name option is seen, @c operator() returns 0.
00250    *
00251    * @param name          The long option to add.
00252    * @param has_arg       Defines the argument requirements for
00253    *                      the new option.
00254    *
00255    * @retval 0  Success
00256    * @retval -1 The long option can not be added.
00257    */
00258   int long_option (const ACE_TCHAR *name,
00259                    OPTION_ARG_MODE has_arg = NO_ARG);
00260 
00261   /// Adds a long option with a corresponding short option.
00262   /**
00263    * @param name          The long option to add.
00264    * @param short_option  A character, the short option that corresponds
00265    *                      to @a name.
00266    * @param has_arg       Defines the argument requirements for
00267    *                      the new option.  If the short option has already
00268    *                      been supplied in the @a optstring, @a has_arg
00269    *                      must match or an error is returned; otherwise, the
00270    *                      new short option is added to the @a optstring.
00271    *
00272    * @retval 0  Success
00273    * @retval -1 The long option can not be added.
00274    */
00275   int long_option (const ACE_TCHAR *name,
00276                    int short_option,
00277                    OPTION_ARG_MODE has_arg = NO_ARG);
00278 
00279   /// Returns the name of the long option found on the last call to
00280   /// @c operator() or 0 if none was found.
00281   const ACE_TCHAR *long_option (void) const;
00282 
00283   /// The number of arguments in the internal @c argv_.
00284   int argc (void) const;
00285 
00286   /// Accessor for the internal @c argv_ pointer.
00287   ACE_TCHAR **argv (void) const;
00288 
00289   /// Dump the state of an object.
00290   void dump (void) const;
00291 
00292   /// Return the @a optstring.  This is handy to verify that calls to
00293   /// long_option added short options as expected.
00294   const ACE_TCHAR *optstring (void) const;
00295 
00296 public:
00297   /*
00298    * The following five data members should be private, but that
00299    * would break backwards compatibility.  However, we recommend not
00300    * writing code that uses these fields directly.
00301    */
00302 
00303   /// Holds the @a argc count.
00304   /**
00305    * @deprecated This is public for backwards compatibility only.
00306    * It will be made private in a release of ACE past 5.3.  Do not
00307    * write code that relies on this member being public; use the
00308    * @c argc() accessor method instead.
00309    */
00310   int argc_;
00311 
00312   /// Holds the @a argv pointer.
00313   /**
00314    * @deprecated This is public for backwards compatibility only.
00315    * It will be made private in a release of ACE past 5.3.  Do not
00316    * write code that relies on this member being public; use the
00317    * @c argv() accessor method instead.
00318    */
00319   ACE_TCHAR **argv_;
00320 
00321   /// Index in @c argv_ of the next element to be scanned.
00322   /**
00323    * @deprecated This is public for backwards compatibility only.
00324    * It will be made private in a release of ACE past 5.3.  Do not
00325    * write code that relies on this member being public; use the
00326    * @c opt_ind() accessor method instead.
00327    */
00328   int optind;
00329 
00330   /// Callers store zero here to inhibit the error message for
00331   /// unrecognized options.
00332   /**
00333    * @deprecated This is public for backwards compatibility only.
00334    * It will be made private in a release of ACE past 5.3.  Do not
00335    * write code that relies on this member being public; use the
00336    * @a report_errors argument to this class's constructor instead.
00337    */
00338   int opterr;
00339 
00340   /// Points to the option argument when one is found on last call to
00341   /// @c operator().
00342   /**
00343    * @deprecated This is public for backwards compatibility only.
00344    * It will be made private in a release of ACE past 5.3.  Do not
00345    * write code that relies on this member being public; use the
00346    * @c opt_arg() accessor method instead.
00347    */
00348   ACE_TCHAR *optarg;
00349 
00350 private:
00351   /**
00352    * @class ACE_Get_Opt_Long_Option  This class is for internal use
00353    * in the ACE_Get_Opt class, and is inaccessible to users.
00354    */
00355   class ACE_Get_Opt_Long_Option
00356   {
00357   public:
00358     /// ctor
00359     ACE_Get_Opt_Long_Option (const ACE_TCHAR *name,
00360                              int has_arg,
00361                              int val = 0);
00362 
00363     /// Default dtor.
00364     ~ACE_Get_Opt_Long_Option (void);
00365 
00366     int operator < (const ACE_Get_Opt_Long_Option &rhs);
00367 
00368     /// Long option name.
00369     const ACE_TCHAR *name_;
00370 
00371     /// Contains value for <OPTION_ARG_MODE>.
00372     int has_arg_;
00373 
00374     /// Contains a valid short option character or zero if it doesn't
00375     /// have a corresponding short option.  It can also contain a
00376     /// non-printable value that cannot be passed to <optstring> but
00377     /// will be returned by <operator()>.  This is handy for
00378     /// simplifying long option handling, see tests/Get_Opt_Test.cpp
00379     /// for an example of this technique.
00380     int val_;
00381   };
00382 
00383   /// Updates nextchar_.
00384   int nextchar_i (void);
00385 
00386   /// Handles long options.
00387   int long_option_i (void);
00388 
00389   /// Handles short options.
00390   int short_option_i (void);
00391 
00392   /// If permuting args, this functions manages the nonopt_start_ and
00393   /// nonopt_end_ indexes and makes calls to permute to actually
00394   /// reorder the <argv>-elements.
00395   void permute_args (void);
00396 
00397   /// Handles reordering <argv>-elements.
00398   int permute (void);
00399 
00400   /// Holds the option string.
00401   ACE_TString optstring_;
00402 
00403   /// Treat all options as long options.
00404   int long_only_;
00405 
00406   /// Keeps track of whether or not a colon was passed in <optstring>.
00407   /// This is used to determine the return value when required
00408   /// arguments are missing.
00409   int has_colon_;
00410 
00411   /**
00412    * The next char to be scanned in the option-element in which the
00413    * last option character we returned was found.  This allows us to
00414    * pick up the scan where we left off   *
00415    * If this is zero, or a null string, it means resume the scan
00416    * by advancing to the next <argv>-element.
00417    */
00418   ACE_TCHAR *nextchar_;
00419 
00420   /// Most recently matched short option character.
00421   int optopt_;
00422 
00423   /// Keeps track of ordering mode (default <PERMUTE_ARGS>).
00424   int ordering_;
00425 
00426   /// Index of the first non-option <argv>-element found (only valid
00427   /// when permuting).
00428   int nonopt_start_;
00429 
00430   /// Index of the <argv>-element following the last non-option element
00431   /// (only valid when permuting).
00432   int nonopt_end_;
00433 
00434   /// Points to the long_option found on last call to <operator()>.
00435   ACE_Get_Opt_Long_Option *long_option_;
00436 
00437   /// Array of long options.
00438   ACE_Array<ACE_Get_Opt_Long_Option*> long_opts_;
00439 
00440   /// Declare the dynamic allocation hooks.
00441   ACE_ALLOC_HOOK_DECLARE;
00442 
00443   ACE_UNIMPLEMENTED_FUNC (ACE_Get_Opt (const ACE_Get_Opt &))
00444   ACE_UNIMPLEMENTED_FUNC (ACE_Get_Opt &operator= (const ACE_Get_Opt &))
00445 };
00446 
00447 #if defined (__ACE_INLINE__)
00448 #include "ace/Get_Opt.i"
00449 #endif /* __ACE_INLINE__ */
00450 
00451 #include "ace/post.h"
00452 #endif /* ACE_GET_OPT_H */

Generated on Mon Jun 16 11:19:45 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002