diff options
Diffstat (limited to 'ace/Get_Opt.h')
| -rw-r--r-- | ace/Get_Opt.h | 474 |
1 files changed, 0 insertions, 474 deletions
diff --git a/ace/Get_Opt.h b/ace/Get_Opt.h deleted file mode 100644 index 73a18f6a051..00000000000 --- a/ace/Get_Opt.h +++ /dev/null @@ -1,474 +0,0 @@ -// -*- C++ -*- - -//========================================================================== -/** - * @file Get_Opt.h - * - * $Id$ - * - * @author Douglas C. Schmidt <schmidt@cs.wustl.edu> - * @author Don Hinton <dhinton@gmx.net> (added long option support) - */ -//========================================================================== - -#ifndef ACE_GET_OPT_H -#define ACE_GET_OPT_H -#include /**/ "ace/pre.h" - -#include "ace/SStringfwd.h" -#include "ace/Containers.h" - -#if !defined (ACE_LACKS_PRAGMA_ONCE) -# pragma once -#endif /* ACE_LACKS_PRAGMA_ONCE */ - -#undef optind -#undef optarg -#undef opterr - -ACE_BEGIN_VERSIONED_NAMESPACE_DECL - -/* - * These definitions are for backward compatibility with previous versions. - * of ACE_Get_Opt. - */ - -/** - * @class ACE_Get_Opt - * - * @brief Iterator for parsing command-line arguments. - * - * This is a C++ wrapper for getopt(3c) and getopt_long(3c). - */ - -class ACE_Export ACE_Get_Opt -{ -public: - /// Mutually exclusive ordering values. - enum - { - /** - * REQUIRE_ORDER means that processing stops and @c EOF is - * returned as soon as a non-option argument is found. @c opt_ind() - * will return the index of the next @a argv element so the program - * can continue processing the rest of the @a argv elements. - */ - REQUIRE_ORDER = 1, - - /** - * PERMUTE_ARGS means the @a 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, @c EOF is - * returned and @c opt_ind() returns the index into the next non-option - * element. - */ - PERMUTE_ARGS = 2, - - /** - * RETURN_IN_ORDER means each @a argv element is processed in the - * order is it seen. If the element is not recognized as an option, '1' - * is returned and @c opt_arg() refers to the @a argv element found. - */ - RETURN_IN_ORDER = 3 - }; - - /// Mutually exclusive option argument mode used by long options. - enum OPTION_ARG_MODE - { - /// Doesn't take an argument. - NO_ARG = 0, - - /// Requires an argument, same as passing ":" after a short option - /// character in @a optstring. - ARG_REQUIRED = 1, - - /// Argument is optional, same as passing "::" after a short - /// option character in @a optstring. - ARG_OPTIONAL = 2 - }; - - /** - * Constructor initializes the command line to be parsed. All information - * for parsing must be supplied to this constructor. - * - * @param argc The number of @a argv elements to parse. - * @param argv Command line tokens, such as would be passed - * to @c main(). - * @param 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 - * @a argv element, or from the following @a argv - * element (only valid for required arguments; - * optional arguments must always reside in the same - * @a argv element). The argument value, if any is - * returned by the @c opt_arg() method. - * @a optstring can be extended by adding long options - * with corresponding short options via the - * @c long_option() method. If the short option - * already appears in @a optstring, the argument - * characteristics must match, otherwise it is added. - * See @c long_option() for more information. - * If 'W', followed by a semi-colon ';' appears in - * @a 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 @a optstring - * before any option characters, with the described - * effect: - * - '+' changes the @a ordering to @a REQUIRE_ORDER. - * - '-' changes the @a ordering to @a RETURN_IN_ORDER. - * - ':' changes the return value from @c operator() - * and get_opt() from '?' to ':' when an option - * requires an argument but none is specified. - * - * @param skip_args Optional (default 1). The specified number of - * initial elements in @a argv are skipped before - * parsing begins. Thus, the default prevents - * @a argv[0] (usually the command name) from being - * parsed. @a argc includes all @a argv elements, - * including any skipped elements. - * @param report_errors Optional, if non-zero then parsing errors cause - * an error message to be displayed from the - * @c 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 @c long_option() encounters - * an error. - * @param ordering Optional (default is @c PERMUTE_ARGS); determines - * how the @a argv elements are processed. This argument - * is overridden by two factors: - * -# The @c POSIXLY_CORRECT environment variable. If - * this environment variable is set, the ordering - * is changed to @c REQUIRE_ORDER. - * -# Leading characters in @a optstring (see above). - * Any leading ordering characters override both - * the @a ordering argument and any effect of the - * @c POSIXLY_CORRECT environment variable. - * @param long_only Optional. If non-zero, then long options can be - * specified using a single '-' on the command line. - * If the token is not a long option, it is processed - * as usual, that is, as a short option or set of - * short options. - * - * Multiple short options can be combined as long as only the last - * one can takes an argument. For example, if @a optstring is defined as - * @c "abc:" or @c "abc::" then the command line @e "program -abcxxx" short - * options @e a, @e b, and @e c are found with @e "xxx" as the argument for - * @e c. - * However, if the command line is specified as @e "program -acb" only - * options @e a and @e c are found with @e "b" as the argument for @e c. - * Also, for options with optional arguments, that is, those followed by - * "::", the argument must be in the same @a argv element, so "program -abc - * xxx" will only find "xxx" as the argument for @e c if @a optstring is - * specified as @c "abc:" not @c "abc::". - */ - ACE_Get_Opt (int argc, - ACE_TCHAR **argv, - const ACE_TCHAR *optstring = ACE_LIB_TEXT (""), - int skip_args = 1, - int report_errors = 0, - int ordering = PERMUTE_ARGS, - int long_only = 0); - - /// Default dtor. - ~ACE_Get_Opt (void); - - /** - * Scan elements of @a argv (whose length is @a argc) for short option - * characters given in @a optstring or long options (with no short - * option equivalents). - * - * If an element of @a 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 @c operator() is called repeatedly, it returns - * each of the option characters from each of the option elements. - * - * @return The parsed option character. The following characters have - * special significance. - * @retval 0 A long option was found - * @retval '\?' Either an unknown option character was found, or the - * option is known but requires an argument, none was - * specified, and @a optstring did not contain a leading - * colon. - * @retval ':' A known option character was found but it requires an - * argument and none was supplied, and the first character - * of @a optstring was a colon. @c opt_opt() indicates - * which option was specified. - * @retval '1' @c RETURN_IN_ORDER was specified and a non-option argument - * was found. - * @retval EOF No more option characters were found. @c opt_ind() will - * return the index in @a argv of the first @a argv element - * that is not an option. If @c PERMUTE_ARGS was - * specified, the @a 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 - * @a optstring up unto the first short option character for '+', '-', - * and ':' in order to determine ordering and missing argument behavior. - */ - int operator () (void); - - /** - * For communication from @c operator() to the caller. When - * @c operator() finds an option that takes an argument, the argument - * value is returned from this method, otherwise it returns 0. - */ - ACE_TCHAR *opt_arg (void) const; - - /** - * 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. - */ - int opt_opt (void); - - /** - * Index in @a 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 @c operator(). On entry to - * @c operator(), zero means this is the first call; initialize. - * - * When @c operator() returns @c EOF, this is the index of the first of - * the non-option elements that the caller should itself scan. - * - * Otherwise, @c opt_ind() communicates from one call to the next how - * much of @a argv has been scanned so far. - */ - int &opt_ind (void); - - /// Adds a long option with no corresponding short option. - /** - * If the @a name option is seen, @c operator() returns 0. - * - * @param name The long option to add. - * @param has_arg Defines the argument requirements for - * the new option. - * - * @retval 0 Success - * @retval -1 The long option can not be added. - */ - int long_option (const ACE_TCHAR *name, - OPTION_ARG_MODE has_arg = NO_ARG); - - /// Adds a long option with a corresponding short option. - /** - * @param name The long option to add. - * @param short_option A character, the short option that corresponds - * to @a name. - * @param has_arg Defines the argument requirements for - * the new option. If the short option has already - * been supplied in the @a optstring, @a has_arg - * must match or an error is returned; otherwise, the - * new short option is added to the @a optstring. - * - * @retval 0 Success - * @retval -1 The long option can not be added. - */ - int long_option (const ACE_TCHAR *name, - int short_option, - OPTION_ARG_MODE has_arg = NO_ARG); - - /// Returns the name of the long option found on the last call to - /// @c operator() or 0 if none was found. - const ACE_TCHAR *long_option (void) const; - - /// The number of arguments in the internal @c argv_. - int argc (void) const; - - /// Accessor for the internal @c argv_ pointer. - ACE_TCHAR **argv (void) const; - - /// Accessor for the @c last_option that was processed. This allows - /// applications to know if the found option was a short or long - /// option, and is especially useful in cases where it was invalid - /// and the caller wants to print out the invalid value. - const ACE_TCHAR *last_option (void) const; - - /// Dump the state of an object. - void dump (void) const; - - /// Return the @a optstring. This is handy to verify that calls to - /// long_option added short options as expected. - const ACE_TCHAR *optstring (void) const; - -public: - /* - * 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. - */ - - /// Holds the @a 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 - * @c argc() accessor method instead. - */ - int argc_; - - /// Holds the @a 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 - * @c argv() accessor method instead. - */ - ACE_TCHAR **argv_; - - /// Index in @c 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 - * @c opt_ind() accessor method instead. - */ - int optind; - - /// 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 - * @a report_errors argument to this class's constructor instead. - */ - int opterr; - - /// Points to the option argument when one is found on last call to - /// @c 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 - * @c opt_arg() accessor method instead. - */ - ACE_TCHAR *optarg; - -private: - /** - * @class ACE_Get_Opt_Long_Option This class is for internal use - * in the ACE_Get_Opt class, and is inaccessible to users. - */ - class ACE_Get_Opt_Long_Option - { - public: - /// ctor - ACE_Get_Opt_Long_Option (const ACE_TCHAR *name, - int has_arg, - int val = 0); - - /// Dtor. - ~ACE_Get_Opt_Long_Option (void); - - bool operator < (const ACE_Get_Opt_Long_Option &rhs); - - /// Long option name. - const ACE_TCHAR *name_; - - /// Contains value for <OPTION_ARG_MODE>. - int has_arg_; - - /// Contains a valid short option character or zero if it doesn't - /// have a corresponding short option. It can also contain a - /// non-printable value that cannot be passed to <optstring> but - /// will be returned by <operator()>. This is handy for - /// simplifying long option handling, see tests/Get_Opt_Test.cpp - /// for an example of this technique. - int val_; - }; - - /// Updates nextchar_. - int nextchar_i (void); - - /// Handles long options. - int long_option_i (void); - - /// Handles short options. - int short_option_i (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. - void permute_args (void); - - /// Handles reordering <argv>-elements. - int permute (void); - - /// Set last_option. - void last_option (const ACE_TString &s); - - // Disallow copying and assignment. - ACE_Get_Opt (const ACE_Get_Opt &); - ACE_Get_Opt &operator= (const ACE_Get_Opt &); - -private: - - /// Holds the option string. - ACE_TString *optstring_; - - /// Treat all options as long options. - int long_only_; - - /// 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 has_colon_; - - /// This is the last option, short or long, that was processed. This - /// is handy to have in cases where the option passed was invalid. - ACE_TString *last_option_; - - /** - * 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. - */ - ACE_TCHAR *nextchar_; - - /// Most recently matched short option character. - int optopt_; - - /// Keeps track of ordering mode (default <PERMUTE_ARGS>). - int ordering_; - - /// Index of the first non-option <argv>-element found (only valid - /// when permuting). - int nonopt_start_; - - /// Index of the <argv>-element following the last non-option element - /// (only valid when permuting). - int nonopt_end_; - - /// Points to the long_option found on last call to <operator()>. - ACE_Get_Opt_Long_Option *long_option_; - - /// Array of long options. - ACE_Array<ACE_Get_Opt_Long_Option*> long_opts_; - - /// Declare the dynamic allocation hooks. - ACE_ALLOC_HOOK_DECLARE; - -}; - -ACE_END_VERSIONED_NAMESPACE_DECL - -#if defined (__ACE_INLINE__) -#include "ace/Get_Opt.inl" -#endif /* __ACE_INLINE__ */ - -#include /**/ "ace/post.h" -#endif /* ACE_GET_OPT_H */ |