3 //==========================================================================
7 * $Id: Get_Opt.h 81840 2008-06-05 13:46:45Z sma $
9 * @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
10 * @author Don Hinton <dhinton@gmx.net> (added long option support)
12 //==========================================================================
16 #include /**/ "ace/pre.h"
18 #include "ace/SStringfwd.h"
19 #include "ace/Containers.h"
21 #if !defined (ACE_LACKS_PRAGMA_ONCE)
23 #endif /* ACE_LACKS_PRAGMA_ONCE */
29 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
32 * These definitions are for backward compatibility with previous versions.
39 * @brief Iterator for parsing command-line arguments.
41 * This is a C++ wrapper for getopt(3c) and getopt_long(3c).
44 class ACE_Export ACE_Get_Opt
47 /// Mutually exclusive ordering values.
51 * REQUIRE_ORDER means that processing stops and @c EOF is
52 * returned as soon as a non-option argument is found. @c opt_ind()
53 * will return the index of the next @a argv element so the program
54 * can continue processing the rest of the @a argv elements.
59 * PERMUTE_ARGS means the @a argv elements are reordered dynamically
60 * (permuted) so that all options appear first. When the elements are
61 * permuted, the order of the options and the following arguments are
62 * maintained. When the last option has been processed, @c EOF is
63 * returned and @c opt_ind() returns the index into the next non-option
69 * RETURN_IN_ORDER means each @a argv element is processed in the
70 * order is it seen. If the element is not recognized as an option, '1'
71 * is returned and @c opt_arg() refers to the @a argv element found.
76 /// Mutually exclusive option argument mode used by long options.
79 /// Doesn't take an argument.
82 /// Requires an argument, same as passing ":" after a short option
83 /// character in @a optstring.
86 /// Argument is optional, same as passing "::" after a short
87 /// option character in @a optstring.
92 * Constructor initializes the command line to be parsed. All information
93 * for parsing must be supplied to this constructor.
95 * @param argc The number of @a argv elements to parse.
96 * @param argv Command line tokens, such as would be passed
98 * @param optstring Nul-terminated string containing the legitimate
99 * short option characters. A single colon ":"
100 * following an option character means the option
101 * requires an argument. A double colon "::" following
102 * an option character means the argument is optional.
103 * The argument is taken from the rest of the current
104 * @a argv element, or from the following @a argv
105 * element (only valid for required arguments;
106 * optional arguments must always reside in the same
107 * @a argv element). The argument value, if any is
108 * returned by the @c opt_arg() method.
109 * @a optstring can be extended by adding long options
110 * with corresponding short options via the
111 * @c long_option() method. If the short option
112 * already appears in @a optstring, the argument
113 * characteristics must match, otherwise it is added.
114 * See @c long_option() for more information.
115 * If 'W', followed by a semi-colon ';' appears in
116 * @a optstring, then any time a 'W' appears on the
117 * command line, the following argument is treated as
118 * a long option. For example, if the command line
119 * contains "program -W foo", "foo" is treated as a
120 * long option, that is, as if "program --foo" had
122 * The following characters can appear in @a optstring
123 * before any option characters, with the described
125 * - '+' changes the @a ordering to @a REQUIRE_ORDER.
126 * - '-' changes the @a ordering to @a RETURN_IN_ORDER.
127 * - ':' changes the return value from @c operator()
128 * and get_opt() from '?' to ':' when an option
129 * requires an argument but none is specified.
131 * @param skip_args Optional (default 1). The specified number of
132 * initial elements in @a argv are skipped before
133 * parsing begins. Thus, the default prevents
134 * @a argv[0] (usually the command name) from being
135 * parsed. @a argc includes all @a argv elements,
136 * including any skipped elements.
137 * @param report_errors Optional, if non-zero then parsing errors cause
138 * an error message to be displayed from the
139 * @c operator() method before it returns. The
140 * error message is suppressed if this argument is 0.
141 * This setting also controls whether or not an error
142 * message is displayed in @c long_option() encounters
144 * @param ordering Optional (default is @c PERMUTE_ARGS); determines
145 * how the @a argv elements are processed. This argument
146 * is overridden by two factors:
147 * -# The @c POSIXLY_CORRECT environment variable. If
148 * this environment variable is set, the ordering
149 * is changed to @c REQUIRE_ORDER.
150 * -# Leading characters in @a optstring (see above).
151 * Any leading ordering characters override both
152 * the @a ordering argument and any effect of the
153 * @c POSIXLY_CORRECT environment variable.
154 * @param long_only Optional. If non-zero, then long options can be
155 * specified using a single '-' on the command line.
156 * If the token is not a long option, it is processed
157 * as usual, that is, as a short option or set of
160 * Multiple short options can be combined as long as only the last
161 * one can takes an argument. For example, if @a optstring is defined as
162 * @c "abc:" or @c "abc::" then the command line @e "program -abcxxx" short
163 * options @e a, @e b, and @e c are found with @e "xxx" as the argument for
165 * However, if the command line is specified as @e "program -acb" only
166 * options @e a and @e c are found with @e "b" as the argument for @e c.
167 * Also, for options with optional arguments, that is, those followed by
168 * "::", the argument must be in the same @a argv element, so "program -abc
169 * xxx" will only find "xxx" as the argument for @e c if @a optstring is
170 * specified as @c "abc:" not @c "abc::".
172 #ifndef ACE_USES_WCHAR
173 ACE_Get_Opt (int argc
,
175 const ACE_TCHAR
*optstring
= ACE_TEXT (""),
177 int report_errors
= 0,
178 int ordering
= PERMUTE_ARGS
,
183 void ACE_Get_Opt_Init (const ACE_TCHAR
*optstring
);
185 ACE_INLINE
ACE_Get_Opt (int argc
,
187 const ACE_TCHAR
*optstring
= ACE_TEXT (""),
189 int report_errors
= 0,
190 int ordering
= PERMUTE_ARGS
,
192 ACE_INLINE
ACE_Get_Opt (int argc
,
194 const char *optstring
,
196 int report_errors
= 0,
197 int ordering
= PERMUTE_ARGS
,
204 * Scan elements of @a argv (whose length is @a argc) for short option
205 * characters given in @a optstring or long options (with no short
206 * option equivalents).
208 * If an element of @a argv starts with '-', and is not exactly "-"
209 * or "--", then it is a short option element. The characters of this
210 * element (aside from the initial '-') are option characters. If
211 * it starts with "--" followed by other characters it is treated as
212 * a long option. If @c operator() is called repeatedly, it returns
213 * each of the option characters from each of the option elements.
215 * @return The parsed option character. The following characters have
216 * special significance.
217 * @retval 0 A long option was found
218 * @retval '\?' Either an unknown option character was found, or the
219 * option is known but requires an argument, none was
220 * specified, and @a optstring did not contain a leading
222 * @retval ':' A known option character was found but it requires an
223 * argument and none was supplied, and the first character
224 * of @a optstring was a colon. @c opt_opt() indicates
225 * which option was specified.
226 * @retval '1' @c RETURN_IN_ORDER was specified and a non-option argument
228 * @retval EOF No more option characters were found. @c opt_ind() will
229 * return the index in @a argv of the first @a argv element
230 * that is not an option. If @c PERMUTE_ARGS was
231 * specified, the @a argv elements have been permuted so that
232 * those that are not options now come last.
234 * @note The standards are unclear with respect to the conditions under
235 * which '?' and ':' are returned, so we scan the initial characters of
236 * @a optstring up unto the first short option character for '+', '-',
237 * and ':' in order to determine ordering and missing argument behavior.
239 int operator () (void);
242 * For communication from @c operator() to the caller. When
243 * @c operator() finds an option that takes an argument, the argument
244 * value is returned from this method, otherwise it returns 0.
246 ACE_TCHAR
*opt_arg (void) const;
249 * Returns the most recently matched option character. Especially
250 * useful when operator() returns ':' for an unspecified argument
251 * that's required, since this allows the caller to learn what option
252 * was specified without its required argument.
257 * Index in @a argv of the next element to be scanned. This is used
258 * for communication to and from the caller and for communication
259 * between successive calls to @c operator(). On entry to
260 * @c operator(), zero means this is the first call; initialize.
262 * When @c operator() returns @c EOF, this is the index of the first of
263 * the non-option elements that the caller should itself scan.
265 * Otherwise, @c opt_ind() communicates from one call to the next how
266 * much of @a argv has been scanned so far.
270 /// Adds a long option with no corresponding short option.
272 * If the @a name option is seen, @c operator() returns 0.
274 * @param name The long option to add.
275 * @param has_arg Defines the argument requirements for
279 * @retval -1 The long option can not be added.
281 int long_option (const ACE_TCHAR
*name
,
282 OPTION_ARG_MODE has_arg
= NO_ARG
);
284 /// Adds a long option with a corresponding short option.
286 * @param name The long option to add.
287 * @param short_option A character, the short option that corresponds
289 * @param has_arg Defines the argument requirements for
290 * the new option. If the short option has already
291 * been supplied in the @a optstring, @a has_arg
292 * must match or an error is returned; otherwise, the
293 * new short option is added to the @a optstring.
296 * @retval -1 The long option can not be added.
298 int long_option (const ACE_TCHAR
*name
,
300 OPTION_ARG_MODE has_arg
= NO_ARG
);
302 /// Returns the name of the long option found on the last call to
303 /// @c operator() or 0 if none was found.
304 const ACE_TCHAR
*long_option (void) const;
306 /// The number of arguments in the internal @c argv_.
307 int argc (void) const;
309 /// Accessor for the internal @c argv_ pointer.
310 ACE_TCHAR
**argv (void) const;
312 /// Accessor for the @c last_option that was processed. This allows
313 /// applications to know if the found option was a short or long
314 /// option, and is especially useful in cases where it was invalid
315 /// and the caller wants to print out the invalid value.
316 const ACE_TCHAR
*last_option (void) const;
318 /// Dump the state of an object.
319 void dump (void) const;
321 /// Return the @a optstring. This is handy to verify that calls to
322 /// long_option added short options as expected.
323 const ACE_TCHAR
*optstring (void) const;
327 * The following five data members should be private, but that
328 * would break backwards compatibility. However, we recommend not
329 * writing code that uses these fields directly.
332 /// Holds the @a argc count.
334 * @deprecated This is public for backwards compatibility only.
335 * It will be made private in a release of ACE past 5.3. Do not
336 * write code that relies on this member being public; use the
337 * @c argc() accessor method instead.
341 /// Holds the @a argv pointer.
343 * @deprecated This is public for backwards compatibility only.
344 * It will be made private in a release of ACE past 5.3. Do not
345 * write code that relies on this member being public; use the
346 * @c argv() accessor method instead.
350 /// Index in @c argv_ of the next element to be scanned.
352 * @deprecated This is public for backwards compatibility only.
353 * It will be made private in a release of ACE past 5.3. Do not
354 * write code that relies on this member being public; use the
355 * @c opt_ind() accessor method instead.
359 /// Callers store zero here to inhibit the error message for
360 /// unrecognized options.
362 * @deprecated This is public for backwards compatibility only.
363 * It will be made private in a release of ACE past 5.3. Do not
364 * write code that relies on this member being public; use the
365 * @a report_errors argument to this class's constructor instead.
369 /// Points to the option argument when one is found on last call to
372 * @deprecated This is public for backwards compatibility only.
373 * It will be made private in a release of ACE past 5.3. Do not
374 * write code that relies on this member being public; use the
375 * @c opt_arg() accessor method instead.
381 * @class ACE_Get_Opt_Long_Option This class is for internal use
382 * in the ACE_Get_Opt class, and is inaccessible to users.
384 class ACE_Get_Opt_Long_Option
388 ACE_Get_Opt_Long_Option (const ACE_TCHAR
*name
,
393 ~ACE_Get_Opt_Long_Option (void);
395 bool operator < (const ACE_Get_Opt_Long_Option
&rhs
);
397 /// Long option name.
398 const ACE_TCHAR
*name_
;
400 /// Contains value for <OPTION_ARG_MODE>.
403 /// Contains a valid short option character or zero if it doesn't
404 /// have a corresponding short option. It can also contain a
405 /// non-printable value that cannot be passed to <optstring> but
406 /// will be returned by <operator()>. This is handy for
407 /// simplifying long option handling, see tests/Get_Opt_Test.cpp
408 /// for an example of this technique.
412 /// Updates nextchar_.
413 int nextchar_i (void);
415 /// Handles long options.
416 int long_option_i (void);
418 /// Handles short options.
419 int short_option_i (void);
421 /// If permuting args, this functions manages the nonopt_start_ and
422 /// nonopt_end_ indexes and makes calls to permute to actually
423 /// reorder the <argv>-elements.
424 void permute_args (void);
426 /// Handles reordering <argv>-elements.
430 void last_option (const ACE_TString
&s
);
432 // Disallow copying and assignment.
433 ACE_Get_Opt (const ACE_Get_Opt
&);
434 ACE_Get_Opt
&operator= (const ACE_Get_Opt
&);
438 /// Holds the option string.
439 ACE_TString
*optstring_
;
441 /// Treat all options as long options.
444 /// Keeps track of whether or not a colon was passed in <optstring>.
445 /// This is used to determine the return value when required
446 /// arguments are missing.
449 /// This is the last option, short or long, that was processed. This
450 /// is handy to have in cases where the option passed was invalid.
451 ACE_TString
*last_option_
;
454 * The next char to be scanned in the option-element in which the
455 * last option character we returned was found. This allows us to
456 * pick up the scan where we left off *
457 * If this is zero, or a null string, it means resume the scan
458 * by advancing to the next <argv>-element.
460 ACE_TCHAR
*nextchar_
;
462 /// Most recently matched short option character.
465 /// Keeps track of ordering mode (default <PERMUTE_ARGS>).
468 /// Index of the first non-option <argv>-element found (only valid
472 /// Index of the <argv>-element following the last non-option element
473 /// (only valid when permuting).
476 /// Points to the long_option found on last call to <operator()>.
477 ACE_Get_Opt_Long_Option
*long_option_
;
479 /// Array of long options.
480 ACE_Array
<ACE_Get_Opt_Long_Option
*> long_opts_
;
482 /// Declare the dynamic allocation hooks.
483 ACE_ALLOC_HOOK_DECLARE
;
487 ACE_END_VERSIONED_NAMESPACE_DECL
489 #if defined (__ACE_INLINE__)
490 #include "ace/Get_Opt.inl"
491 #endif /* __ACE_INLINE__ */
493 #include /**/ "ace/post.h"
494 #endif /* ACE_GET_OPT_H */