KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > gnu > getopt > Getopt


1 /**************************************************************************
2 /* Getopt.java -- Java port of GNU getopt from glibc 2.0.6
3 /*
4 /* Copyright (c) 1987-1997 Free Software Foundation, Inc.
5 /* Java Port Copyright (c) 1998 by Aaron M. Renn (arenn@urbanophile.com)
6 /*
7 /* This program is free software; you can redistribute it and/or modify
8 /* it under the terms of the GNU Library General Public License as published
9 /* by the Free Software Foundation; either version 2 of the License or
10 /* (at your option) any later version.
11 /*
12 /* This program is distributed in the hope that it will be useful, but
13 /* WITHOUT ANY WARRANTY; without even the implied warranty of
14 /* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 /* GNU Library General Public License for more details.
16 /*
17 /* You should have received a copy of the GNU Library General Public License
18 /* along with this program; see the file COPYING.LIB. If not, write to
19 /* the Free Software Foundation Inc., 59 Temple Place - Suite 330,
20 /* Boston, MA 02111-1307 USA
21 /**************************************************************************/

22
23 package gnu.getopt;
24
25 import java.util.Locale JavaDoc;
26 import java.util.ResourceBundle JavaDoc;
27 import java.util.PropertyResourceBundle JavaDoc;
28 import java.text.MessageFormat JavaDoc;
29
30 /**************************************************************************/
31
32 /**
33   * This is a Java port of GNU getopt, a class for parsing command line
34   * arguments passed to programs. It it based on the C getopt() functions
35   * in glibc 2.0.6 and should parse options in a 100% compatible manner.
36   * If it does not, that is a bug. The programmer's interface is also
37   * very compatible.
38   * <p>
39   * To use Getopt, create a Getopt object with a argv array passed to the
40   * main method, then call the getopt() method in a loop. It will return an
41   * int that contains the value of the option character parsed from the
42   * command line. When there are no more options to be parsed, it
43   * returns -1.
44   * <p>
45   * A command line option can be defined to take an argument. If an
46   * option has an argument, the value of that argument is stored in an
47   * instance variable called optarg, which can be accessed using the
48   * getOptarg() method. If an option that requires an argument is
49   * found, but there is no argument present, then an error message is
50   * printed. Normally getopt() returns a '?' in this situation, but
51   * that can be changed as described below.
52   * <p>
53   * If an invalid option is encountered, an error message is printed
54   * to the standard error and getopt() returns a '?'. The value of the
55   * invalid option encountered is stored in the instance variable optopt
56   * which can be retrieved using the getOptopt() method. To suppress
57   * the printing of error messages for this or any other error, set
58   * the value of the opterr instance variable to false using the
59   * setOpterr() method.
60   * <p>
61   * Between calls to getopt(), the instance variable optind is used to
62   * keep track of where the object is in the parsing process. After all
63   * options have been returned, optind is the index in argv of the first
64   * non-option argument. This variable can be accessed with the getOptind()
65   * method.
66   * <p>
67   * Note that this object expects command line options to be passed in the
68   * traditional Unix manner. That is, proceeded by a '-' character.
69   * Multiple options can follow the '-'. For example "-abc" is equivalent
70   * to "-a -b -c". If an option takes a required argument, the value
71   * of the argument can immediately follow the option character or be
72   * present in the next argv element. For example, "-cfoo" and "-c foo"
73   * both represent an option character of 'c' with an argument of "foo"
74   * assuming c takes a required argument. If an option takes an argument
75   * that is not required, then any argument must immediately follow the
76   * option character in the same argv element. For example, if c takes
77   * a non-required argument, then "-cfoo" represents option character 'c'
78   * with an argument of "foo" while "-c foo" represents the option
79   * character 'c' with no argument, and a first non-option argv element
80   * of "foo".
81   * <p>
82   * The user can stop getopt() from scanning any further into a command line
83   * by using the special argument "--" by itself. For example:
84   * "-a -- -d" would return an option character of 'a', then return -1
85   * The "--" is discarded and "-d" is pointed to by optind as the first
86   * non-option argv element.
87   * <p>
88   * Here is a basic example of using Getopt:
89   * <p>
90   * <pre>
91   * Getopt g = new Getopt("testprog", argv, "ab:c::d");
92   * //
93   * int c;
94   * String arg;
95   * while ((c = g.getopt()) != -1)
96   * {
97   * switch(c)
98   * {
99   * case 'a':
100   * case 'd':
101   * System.out.print("You picked " + (char)c + "\n");
102   * break;
103   * //
104   * case 'b':
105   * case 'c':
106   * arg = g.getOptarg();
107   * System.out.print("You picked " + (char)c +
108   * " with an argument of " +
109   * ((arg != null) ? arg : "null") + "\n");
110   * break;
111   * //
112   * case '?':
113   * break; // getopt() already printed an error
114   * //
115   * default:
116   * System.out.print("getopt() returned " + c + "\n");
117   * }
118   * }
119   * </pre>
120   * <p>
121   * In this example, a new Getopt object is created with three params.
122   * The first param is the program name. This is for printing error
123   * messages in the form "program: error message". In the C version, this
124   * value is taken from argv[0], but in Java the program name is not passed
125   * in that element, thus the need for this parameter. The second param is
126   * the argument list that was passed to the main() method. The third
127   * param is the list of valid options. Each character represents a valid
128   * option. If the character is followed by a single colon, then that
129   * option has a required argument. If the character is followed by two
130   * colons, then that option has an argument that is not required.
131   * <p>
132   * Note in this example that the value returned from getopt() is cast to
133   * a char prior to printing. This is required in order to make the value
134   * display correctly as a character instead of an integer.
135   * <p>
136   * If the first character in the option string is a colon, for example
137   * ":abc::d", then getopt() will return a ':' instead of a '?' when it
138   * encounters an option with a missing required argument. This allows the
139   * caller to distinguish between invalid options and valid options that
140   * are simply incomplete.
141   * <p>
142   * In the traditional Unix getopt(), -1 is returned when the first non-option
143   * charcter is encountered. In GNU getopt(), the default behavior is to
144   * allow options to appear anywhere on the command line. The getopt()
145   * method permutes the argument to make it appear to the caller that all
146   * options were at the beginning of the command line, and all non-options
147   * were at the end. For example, calling getopt() with command line args
148   * of "-a foo bar -d" returns options 'a' and 'd', then sets optind to
149   * point to "foo". The program would read the last two argv elements as
150   * "foo" and "bar", just as if the user had typed "-a -d foo bar".
151   * <p>
152   * The user can force getopt() to stop scanning the command line with
153   * the special argument "--" by itself. Any elements occuring before the
154   * "--" are scanned and permuted as normal. Any elements after the "--"
155   * are returned as is as non-option argv elements. For example,
156   * "foo -a -- bar -d" would return option 'a' then -1. optind would point
157   * to "foo", "bar" and "-d" as the non-option argv elements. The "--"
158   * is discarded by getopt().
159   * <p>
160   * There are two ways this default behavior can be modified. The first is
161   * to specify traditional Unix getopt() behavior (which is also POSIX
162   * behavior) in which scanning stops when the first non-option argument
163   * encountered. (Thus "-a foo bar -d" would return 'a' as an option and
164   * have "foo", "bar", and "-d" as non-option elements). The second is to
165   * allow options anywhere, but to return all elements in the order they
166   * occur on the command line. When a non-option element is ecountered,
167   * an integer 1 is returned and the value of the non-option element is
168   * stored in optarg is if it were the argument to that option. For
169   * example, "-a foo -d", returns first 'a', then 1 (with optarg set to
170   * "foo") then 'd' then -1. When this "return in order" functionality
171   * is enabled, the only way to stop getopt() from scanning all command
172   * line elements is to use the special "--" string by itself as described
173   * above. An example is "-a foo -b -- bar", which would return 'a', then
174   * integer 1 with optarg set to "foo", then 'b', then -1. optind would
175   * then point to "bar" as the first non-option argv element. The "--"
176   * is discarded.
177   * <p>
178   * The POSIX/traditional behavior is enabled by either setting the
179   * property "gnu.posixly_correct" or by putting a '+' sign as the first
180   * character of the option string. The difference between the two
181   * methods is that setting the gnu.posixly_correct property also forces
182   * certain error messages to be displayed in POSIX format. To enable
183   * the "return in order" functionality, put a '-' as the first character
184   * of the option string. Note that after determining the proper
185   * behavior, Getopt strips this leading '+' or '-', meaning that a ':'
186   * placed as the second character after one of those two will still cause
187   * getopt() to return a ':' instead of a '?' if a required option
188   * argument is missing.
189   * <p>
190   * In addition to traditional single character options, GNU Getopt also
191   * supports long options. These are preceeded by a "--" sequence and
192   * can be as long as desired. Long options provide a more user-friendly
193   * way of entering command line options. For example, in addition to a
194   * "-h" for help, a program could support also "--help".
195   * <p>
196   * Like short options, long options can also take a required or non-required
197   * argument. Required arguments can either be specified by placing an
198   * equals sign after the option name, then the argument, or by putting the
199   * argument in the next argv element. For example: "--outputdir=foo" and
200   * "--outputdir foo" both represent an option of "outputdir" with an
201   * argument of "foo", assuming that outputdir takes a required argument.
202   * If a long option takes a non-required argument, then the equals sign
203   * form must be used to specify the argument. In this case,
204   * "--outputdir=foo" would represent option outputdir with an argument of
205   * "foo" while "--outputdir foo" would represent the option outputdir
206   * with no argument and a first non-option argv element of "foo".
207   * <p>
208   * Long options can also be specified using a special POSIX argument
209   * format (one that I highly discourage). This form of entry is
210   * enabled by placing a "W;" (yes, 'W' then a semi-colon) in the valid
211   * option string. This causes getopt to treat the name following the
212   * "-W" as the name of the long option. For example, "-W outputdir=foo"
213   * would be equivalent to "--outputdir=foo". The name can immediately
214   * follow the "-W" like so: "-Woutputdir=foo". Option arguments are
215   * handled identically to normal long options. If a string follows the
216   * "-W" that does not represent a valid long option, then getopt() returns
217   * 'W' and the caller must decide what to do. Otherwise getopt() returns
218   * a long option value as described below.
219   * <p>
220   * While long options offer convenience, they can also be tedious to type
221   * in full. So it is permissible to abbreviate the option name to as
222   * few characters as required to uniquely identify it. If the name can
223   * represent multiple long options, then an error message is printed and
224   * getopt() returns a '?'.
225   * <p>
226   * If an invalid option is specified or a required option argument is
227   * missing, getopt() prints an error and returns a '?' or ':' exactly
228   * as for short options. Note that when an invalid long option is
229   * encountered, the optopt variable is set to integer 0 and so cannot
230   * be used to identify the incorrect option the user entered.
231   * <p>
232   * Long options are defined by LongOpt objects. These objects are created
233   * with a contructor that takes four params: a String representing the
234   * object name, a integer specifying what arguments the option takes
235   * (the value is one of LongOpt.NO_ARGUMENT, LongOpt.REQUIRED_ARGUMENT,
236   * or LongOpt.OPTIONAL_ARGUMENT), a StringBuffer flag object (described
237   * below), and an integer value (described below).
238   * <p>
239   * To enable long option parsing, create an array of LongOpt's representing
240   * the legal options and pass it to the Getopt() constructor. WARNING: If
241   * all elements of the array are not populated with LongOpt objects, the
242   * getopt() method will throw a NullPointerException.
243   * <p>
244   * When getopt() is called and a long option is encountered, one of two
245   * things can be returned. If the flag field in the LongOpt object
246   * representing the long option is non-null, then the integer value field
247   * is stored there and an integer 0 is returned to the caller. The val
248   * field can then be retrieved from the flag field. Note that since the
249   * flag field is a StringBuffer, the appropriate String to integer converions
250   * must be performed in order to get the actual int value stored there.
251   * If the flag field in the LongOpt object is null, then the value field
252   * of the LongOpt is returned. This can be the character of a short option.
253   * This allows an app to have both a long and short option sequence
254   * (say, "-h" and "--help") that do the exact same thing.
255   * <p>
256   * With long options, there is an alternative method of determining
257   * which option was selected. The method getLongind() will return the
258   * the index in the long option array (NOT argv) of the long option found.
259   * So if multiple long options are configured to return the same value,
260   * the application can use getLongind() to distinguish between them.
261   * <p>
262   * Here is an expanded Getopt example using long options and various
263   * techniques described above:
264   * <p>
265   * <pre>
266   * int c;
267   * String arg;
268   * LongOpt[] longopts = new LongOpt[3];
269   * //
270   * StringBuffer sb = new StringBuffer();
271   * longopts[0] = new LongOpt("help", LongOpt.NO_ARGUMENT, null, 'h');
272   * longopts[1] = new LongOpt("outputdir", LongOpt.REQUIRED_ARGUMENT, sb, 'o');
273   * longopts[2] = new LongOpt("maximum", LongOpt.OPTIONAL_ARGUMENT, null, 2);
274   * //
275   * Getopt g = new Getopt("testprog", argv, "-:bc::d:hW;", longopts);
276   * g.setOpterr(false); // We'll do our own error handling
277   * //
278   * while ((c = g.getopt()) != -1)
279   * switch (c)
280   * {
281   * case 0:
282   * arg = g.getOptarg();
283   * System.out.println("Got long option with value '" +
284   * (char)(new Integer(sb.toString())).intValue()
285   * + "' with argument " +
286   * ((arg != null) ? arg : "null"));
287   * break;
288   * //
289   * case 1:
290   * System.out.println("I see you have return in order set and that " +
291   * "a non-option argv element was just found " +
292   * "with the value '" + g.getOptarg() + "'");
293   * break;
294   * //
295   * case 2:
296   * arg = g.getOptarg();
297   * System.out.println("I know this, but pretend I didn't");
298   * System.out.println("We picked option " +
299   * longopts[g.getLongind()].getName() +
300   * " with value " +
301   * ((arg != null) ? arg : "null"));
302   * break;
303   * //
304   * case 'b':
305   * System.out.println("You picked plain old option " + (char)c);
306   * break;
307   * //
308   * case 'c':
309   * case 'd':
310   * arg = g.getOptarg();
311   * System.out.println("You picked option '" + (char)c +
312   * "' with argument " +
313   * ((arg != null) ? arg : "null"));
314   * break;
315   * //
316   * case 'h':
317   * System.out.println("I see you asked for help");
318   * break;
319   * //
320   * case 'W':
321   * System.out.println("Hmmm. You tried a -W with an incorrect long " +
322   * "option name");
323   * break;
324   * //
325   * case ':':
326   * System.out.println("Doh! You need an argument for option " +
327   * (char)g.getOptopt());
328   * break;
329   * //
330   * case '?':
331   * System.out.println("The option '" + (char)g.getOptopt() +
332   * "' is not valid");
333   * break;
334   * //
335   * default:
336   * System.out.println("getopt() returned " + c);
337   * break;
338   * }
339   * //
340   * for (int i = g.getOptind(); i < argv.length ; i++)
341   * System.out.println("Non option argv element: " + argv[i] + "\n");
342   * </pre>
343   * <p>
344   * There is an alternative form of the constructor used for long options
345   * above. This takes a trailing boolean flag. If set to false, Getopt
346   * performs identically to the example, but if the boolean flag is true
347   * then long options are allowed to start with a single '-' instead of
348   * "--". If the first character of the option is a valid short option
349   * character, then the option is treated as if it were the short option.
350   * Otherwise it behaves as if the option is a long option. Note that
351   * the name given to this option - long_only - is very counter-intuitive.
352   * It does not cause only long options to be parsed but instead enables
353   * the behavior described above.
354   * <p>
355   * Note that the functionality and variable names used are driven from
356   * the C lib version as this object is a port of the C code, not a
357   * new implementation. This should aid in porting existing C/C++ code,
358   * as well as helping programmers familiar with the glibc version to
359   * adapt to the Java version even if it seems very non-Java at times.
360   * <p>
361   * In this release I made all instance variables protected due to
362   * overwhelming public demand. Any code which relied on optarg,
363   * opterr, optind, or optopt being public will need to be modified to
364   * use the appropriate access methods.
365   * <p>
366   * Please send all bug reports, requests, and comments to
367   * <a HREF="mailto:arenn@urbanophile.com">arenn@urbanophile.com</a>.
368   *
369   * @version 1.0.5
370   *
371   * @author Roland McGrath (roland@gnu.ai.mit.edu)
372   * @author Ulrich Drepper (drepper@cygnus.com)
373   * @author Aaron M. Renn (arenn@urbanophile.com)
374   *
375   * @see LongOpt
376   */

377 public class Getopt extends Object JavaDoc
378 {
379
380 /**************************************************************************/
381
382 /*
383  * Class Variables
384  */

385
386 /**
387   * Describe how to deal with options that follow non-option ARGV-elements.
388   *
389   * If the caller did not specify anything,
390   * the default is REQUIRE_ORDER if the property
391   * gnu.posixly_correct is defined, PERMUTE otherwise.
392   *
393   * The special argument `--' forces an end of option-scanning regardless
394   * of the value of `ordering'. In the case of RETURN_IN_ORDER, only
395   * `--' can cause `getopt' to return -1 with `optind' != ARGC.
396   *
397   * REQUIRE_ORDER means don't recognize them as options;
398   * stop option processing when the first non-option is seen.
399   * This is what Unix does.
400   * This mode of operation is selected by either setting the property
401   * gnu.posixly_correct, or using `+' as the first character
402   * of the list of option characters.
403   */

404 protected static final int REQUIRE_ORDER = 1;
405
406 /**
407   * PERMUTE is the default. We permute the contents of ARGV as we scan,
408   * so that eventually all the non-options are at the end. This allows options
409   * to be given in any order, even with programs that were not written to
410   * expect this.
411   */

412 protected static final int PERMUTE = 2;
413
414 /**
415   * RETURN_IN_ORDER is an option available to programs that were written
416   * to expect options and other ARGV-elements in any order and that care about
417   * the ordering of the two. We describe each non-option ARGV-element
418   * as if it were the argument of an option with character code 1.
419   * Using `-' as the first character of the list of option characters
420   * selects this mode of operation.
421   */

422 protected static final int RETURN_IN_ORDER = 3;
423
424 /**************************************************************************/
425
426 /*
427  * Instance Variables
428  */

429  
430 /**
431   * For communication from `getopt' to the caller.
432   * When `getopt' finds an option that takes an argument,
433   * the argument value is returned here.
434   * Also, when `ordering' is RETURN_IN_ORDER,
435   * each non-option ARGV-element is returned here.
436   */

437 protected String JavaDoc optarg;
438
439 /**
440   * Index in ARGV of the next element to be scanned.
441   * This is used for communication to and from the caller
442   * and for communication between successive calls to `getopt'.
443   *
444   * On entry to `getopt', zero means this is the first call; initialize.
445   *
446   * When `getopt' returns -1, this is the index of the first of the
447   * non-option elements that the caller should itself scan.
448   *
449   * Otherwise, `optind' communicates from one call to the next
450   * how much of ARGV has been scanned so far.
451   */

452 protected int optind = 0;
453
454 /**
455   * Callers store false here to inhibit the error message
456   * for unrecognized options.
457   */

458 protected boolean opterr = true;
459
460 /**
461   * When an unrecognized option is encountered, getopt will return a '?'
462   * and store the value of the invalid option here.
463   */

464 protected int optopt = '?';
465
466 /**
467   * The next char to be scanned in the option-element
468   * in which the last option character we returned was found.
469   * This allows us to pick up the scan where we left off.
470   *
471   * If this is zero, or a null string, it means resume the scan
472   * by advancing to the next ARGV-element.
473   */

474 protected String JavaDoc nextchar;
475
476 /**
477   * This is the string describing the valid short options.
478   */

479 protected String JavaDoc optstring;
480
481 /**
482   * This is an array of LongOpt objects which describ the valid long
483   * options.
484   */

485 protected LongOpt[] long_options;
486
487 /**
488   * This flag determines whether or not we are parsing only long args
489   */

490 protected boolean long_only;
491
492 /**
493   * Stores the index into the long_options array of the long option found
494   */

495 protected int longind;
496
497 /**
498   * The flag determines whether or not we operate in strict POSIX compliance
499   */

500 protected boolean posixly_correct;
501
502 /**
503   * A flag which communicates whether or not checkLongOption() did all
504   * necessary processing for the current option
505   */

506 protected boolean longopt_handled;
507
508 /**
509   * The index of the first non-option in argv[]
510   */

511 protected int first_nonopt = 1;
512
513 /**
514   * The index of the last non-option in argv[]
515   */

516 protected int last_nonopt = 1;
517
518 /**
519   * Saved argument list passed to the program
520   */

521 protected String JavaDoc[] argv;
522
523 /**
524   * Determines whether we permute arguments or not
525   */

526 protected int ordering;
527
528 /**
529   * Name to print as the program name in error messages. This is necessary
530   * since Java does not place the program name in argv[0]
531   */

532 protected String JavaDoc progname;
533
534 /**
535   * The localized strings are kept in a separate file
536   */

537 private ResourceBundle JavaDoc _messages = PropertyResourceBundle.getBundle(
538                            "gnu/getopt/MessagesBundle", Locale.getDefault());
539
540 /**************************************************************************/
541
542 /*
543  * Constructors
544  */

545
546 /**
547   * Construct a basic Getopt instance with the given input data. Note that
548   * this handles "short" options only.
549   *
550   * @param progname The name to display as the program name when printing errors
551   * @param argv The String array passed as the command line to the program.
552   * @param optstring A String containing a description of the valid args for this program
553   */

554 public
555 Getopt(String JavaDoc progname, String JavaDoc[] argv, String JavaDoc optstring)
556 {
557   this(progname, argv, optstring, null, false);
558 }
559
560 /**************************************************************************/
561
562 /**
563   * Construct a Getopt instance with given input data that is capable of
564   * parsing long options as well as short.
565   *
566   * @param progname The name to display as the program name when printing errors
567   * @param argv The String array passed as the command ilne to the program
568   * @param optstring A String containing a description of the valid short args for this program
569   * @param long_options An array of LongOpt objects that describes the valid long args for this program
570   */

571 public
572 Getopt(String JavaDoc progname, String JavaDoc[] argv, String JavaDoc optstring,
573        LongOpt[] long_options)
574 {
575   this(progname, argv, optstring, long_options, false);
576 }
577
578 /**************************************************************************/
579
580 /**
581   * Construct a Getopt instance with given input data that is capable of
582   * parsing long options and short options. Contrary to what you might
583   * think, the flag 'long_only' does not determine whether or not we
584   * scan for only long arguments. Instead, a value of true here allows
585   * long arguments to start with a '-' instead of '--' unless there is a
586   * conflict with a short option name.
587   *
588   * @param progname The name to display as the program name when printing errors
589   * @param argv The String array passed as the command ilne to the program
590   * @param optstring A String containing a description of the valid short args for this program
591   * @param long_options An array of LongOpt objects that describes the valid long args for this program
592   * @param long_only true if long options that do not conflict with short options can start with a '-' as well as '--'
593   */

594 public
595 Getopt(String JavaDoc progname, String JavaDoc[] argv, String JavaDoc optstring,
596        LongOpt[] long_options, boolean long_only)
597 {
598   if (optstring.length() == 0)
599     optstring = " ";
600
601   // This function is essentially _getopt_initialize from GNU getopt
602
this.progname = progname;
603   this.argv = argv;
604   this.optstring = optstring;
605   this.long_options = long_options;
606   this.long_only = long_only;
607
608   // Check for property "gnu.posixly_correct" to determine whether to
609
// strictly follow the POSIX standard. This replaces the "POSIXLY_CORRECT"
610
// environment variable in the C version
611
if (System.getProperty("gnu.posixly_correct", null) == null)
612     posixly_correct = false;
613   else
614     {
615       posixly_correct = true;
616       _messages = PropertyResourceBundle.getBundle("gnu/getopt/MessagesBundle",
617                                                    Locale.US);
618     }
619
620   // Determine how to handle the ordering of options and non-options
621
if (optstring.charAt(0) == '-')
622     {
623       ordering = RETURN_IN_ORDER;
624       if (optstring.length() > 1)
625         this.optstring = optstring.substring(1);
626     }
627   else if (optstring.charAt(0) == '+')
628     {
629       ordering = REQUIRE_ORDER;
630       if (optstring.length() > 1)
631         this.optstring = optstring.substring(1);
632     }
633   else if (posixly_correct)
634     {
635       ordering = REQUIRE_ORDER;
636     }
637   else
638     {
639       ordering = PERMUTE; // The normal default case
640
}
641 }
642
643 /**************************************************************************/
644  
645 /*
646  * Instance Methods
647  */

648
649 /**
650   * In GNU getopt, it is possible to change the string containg valid options
651   * on the fly because it is passed as an argument to getopt() each time. In
652   * this version we do not pass the string on every call. In order to allow
653   * dynamic option string changing, this method is provided.
654   *
655   * @param optstring The new option string to use
656   */

657 public void
658 setOptstring(String JavaDoc optstring)
659 {
660   if (optstring.length() == 0)
661     optstring = " ";
662
663   this.optstring = optstring;
664 }
665
666 /**************************************************************************/
667
668 /**
669   * optind it the index in ARGV of the next element to be scanned.
670   * This is used for communication to and from the caller
671   * and for communication between successive calls to `getopt'.
672   *
673   * When `getopt' returns -1, this is the index of the first of the
674   * non-option elements that the caller should itself scan.
675   *
676   * Otherwise, `optind' communicates from one call to the next
677   * how much of ARGV has been scanned so far.
678   */

679 public int
680 getOptind()
681 {
682   return(optind);
683 }
684
685 /**************************************************************************/
686
687 /**
688   * This method allows the optind index to be set manually. Normally this
689   * is not necessary (and incorrect usage of this method can lead to serious
690   * lossage), but optind is a public symbol in GNU getopt, so this method
691   * was added to allow it to be modified by the caller if desired.
692   *
693   * @param optind The new value of optind
694   */

695 public void
696 setOptind(int optind)
697 {
698   this.optind = optind;
699 }
700
701 /**************************************************************************/
702
703 /**
704   * Since in GNU getopt() the argument vector is passed back in to the
705   * function every time, the caller can swap out argv on the fly. Since
706   * passing argv is not required in the Java version, this method allows
707   * the user to override argv. Note that incorrect use of this method can
708   * lead to serious lossage.
709   *
710   * @param argv New argument list
711   */

712 public void
713 setArgv(String JavaDoc[] argv)
714 {
715   this.argv = argv;
716 }
717
718 /**************************************************************************/
719
720 /**
721   * For communication from `getopt' to the caller.
722   * When `getopt' finds an option that takes an argument,
723   * the argument value is returned here.
724   * Also, when `ordering' is RETURN_IN_ORDER,
725   * each non-option ARGV-element is returned here.
726   * No set method is provided because setting this variable has no effect.
727   */

728 public String JavaDoc
729 getOptarg()
730 {
731   return(optarg);
732 }
733
734 /**************************************************************************/
735
736 /**
737   * Normally Getopt will print a message to the standard error when an
738   * invalid option is encountered. This can be suppressed (or re-enabled)
739   * by calling this method. There is no get method for this variable
740   * because if you can't remember the state you set this to, why should I?
741   */

742 public void
743 setOpterr(boolean opterr)
744 {
745   this.opterr = opterr;
746 }
747
748 /**************************************************************************/
749
750 /**
751   * When getopt() encounters an invalid option, it stores the value of that
752   * option in optopt which can be retrieved with this method. There is
753   * no corresponding set method because setting this variable has no effect.
754   */

755 public int
756 getOptopt()
757 {
758   return(optopt);
759 }
760
761 /**************************************************************************/
762
763 /**
764   * Returns the index into the array of long options (NOT argv) representing
765   * the long option that was found.
766   */

767 public int
768 getLongind()
769 {
770   return(longind);
771 }
772
773 /**************************************************************************/
774
775 /**
776   * Exchange the shorter segment with the far end of the longer segment.
777   * That puts the shorter segment into the right place.
778   * It leaves the longer segment in the right place overall,
779   * but it consists of two parts that need to be swapped next.
780   * This method is used by getopt() for argument permutation.
781   */

782 protected void
783 exchange(String JavaDoc[] argv)
784 {
785   int bottom = first_nonopt;
786   int middle = last_nonopt;
787   int top = optind;
788   String JavaDoc tem;
789
790   while (top > middle && middle > bottom)
791     {
792       if (top - middle > middle - bottom)
793         {
794           // Bottom segment is the short one.
795
int len = middle - bottom;
796           int i;
797
798           // Swap it with the top part of the top segment.
799
for (i = 0; i < len; i++)
800             {
801               tem = argv[bottom + i];
802               argv[bottom + i] = argv[top - (middle - bottom) + i];
803               argv[top - (middle - bottom) + i] = tem;
804             }
805           // Exclude the moved bottom segment from further swapping.
806
top -= len;
807         }
808       else
809         {
810           // Top segment is the short one.
811
int len = top - middle;
812           int i;
813
814           // Swap it with the bottom part of the bottom segment.
815
for (i = 0; i < len; i++)
816             {
817               tem = argv[bottom + i];
818               argv[bottom + i] = argv[middle + i];
819               argv[middle + i] = tem;
820             }
821           // Exclude the moved top segment from further swapping.
822
bottom += len;
823         }
824     }
825
826   // Update records for the slots the non-options now occupy.
827

828   first_nonopt += (optind - last_nonopt);
829   last_nonopt = optind;
830 }
831
832 /**************************************************************************/
833
834 /**
835   * Check to see if an option is a valid long option. Called by getopt().
836   * Put in a separate method because this needs to be done twice. (The
837   * C getopt authors just copy-pasted the code!).
838   *
839   * @param longind A buffer in which to store the 'val' field of found LongOpt
840   *
841   * @return Various things depending on circumstances
842   */

843 protected int
844 checkLongOption()
845 {
846   LongOpt pfound = null;
847   int nameend;
848   boolean ambig;
849   boolean exact;
850   
851   longopt_handled = true;
852   ambig = false;
853   exact = false;
854   longind = -1;
855
856   nameend = nextchar.indexOf("=");
857   if (nameend == -1)
858     nameend = nextchar.length();
859   
860   // Test all lnog options for either exact match or abbreviated matches
861
for (int i = 0; i < long_options.length; i++)
862     {
863       if (long_options[i].getName().startsWith(nextchar.substring(0, nameend)))
864         {
865           if (long_options[i].getName().equals(nextchar.substring(0, nameend)))
866             {
867               // Exact match found
868
pfound = long_options[i];
869               longind = i;
870               exact = true;
871               break;
872             }
873           else if (pfound == null)
874             {
875               // First nonexact match found
876
pfound = long_options[i];
877               longind = i;
878             }
879           else
880             {
881               // Second or later nonexact match found
882
ambig = true;
883             }
884         }
885     } // for
886

887   // Print out an error if the option specified was ambiguous
888
if (ambig && !exact)
889     {
890       if (opterr)
891         {
892           Object JavaDoc[] msgArgs = { progname, argv[optind] };
893           System.err.println(MessageFormat.format(
894                              _messages.getString("getopt.ambigious"),
895                              msgArgs));
896         }
897
898        nextchar = "";
899        optopt = 0;
900        ++optind;
901  
902        return('?');
903     }
904  
905   if (pfound != null)
906     {
907       ++optind;
908  
909       if (nameend != nextchar.length())
910         {
911           if (pfound.has_arg != LongOpt.NO_ARGUMENT)
912             {
913               if (nextchar.substring(nameend).length() > 1)
914                 optarg = nextchar.substring(nameend+1);
915               else
916                 optarg = "";
917             }
918           else
919             {
920               if (opterr)
921                 {
922                   // -- option
923
if (argv[optind - 1].startsWith("--"))
924                     {
925                       Object JavaDoc[] msgArgs = { progname, pfound.name };
926                       System.err.println(MessageFormat.format(
927                                   _messages.getString("getopt.arguments1"),
928                                   msgArgs));
929                     }
930                   // +option or -option
931
else
932                     {
933                       Object JavaDoc[] msgArgs = { progname, new
934                                Character JavaDoc(argv[optind-1].charAt(0)).toString(),
935                                pfound.name };
936                       System.err.println(MessageFormat.format(
937                                _messages.getString("getopt.arguments2"),
938                                msgArgs));
939                     }
940                  }
941    
942               nextchar = "";
943               optopt = pfound.val;
944    
945               return('?');
946             }
947         } // if (nameend)
948
else if (pfound.has_arg == LongOpt.REQUIRED_ARGUMENT)
949         {
950           if (optind < argv.length)
951             {
952                optarg = argv[optind];
953                ++optind;
954             }
955           else
956             {
957               if (opterr)
958                 {
959                   Object JavaDoc[] msgArgs = { progname, argv[optind-1] };
960                   System.err.println(MessageFormat.format(
961                                      _messages.getString("getopt.requires"),
962                                      msgArgs));
963                 }
964    
965               nextchar = "";
966               optopt = pfound.val;
967               if (optstring.charAt(0) == ':')
968                 return(':');
969               else
970                 return('?');
971             }
972         } // else if (pfound)
973

974       nextchar = "";
975
976       if (pfound.flag != null)
977         {
978           pfound.flag.setLength(0);
979           pfound.flag.append(pfound.val);
980    
981           return(0);
982         }
983
984       return(pfound.val);
985    } // if (pfound != null)
986

987   longopt_handled = false;
988
989   return(0);
990 }
991
992 /**************************************************************************/
993
994 /**
995   * This method returns a char that is the current option that has been
996   * parsed from the command line. If the option takes an argument, then
997   * the internal variable 'optarg' is set which is a String representing
998   * the the value of the argument. This value can be retrieved by the
999   * caller using the getOptarg() method. If an invalid option is found,
1000  * an error message is printed and a '?' is returned. The name of the
1001  * invalid option character can be retrieved by calling the getOptopt()
1002  * method. When there are no more options to be scanned, this method
1003  * returns -1. The index of first non-option element in argv can be
1004  * retrieved with the getOptind() method.
1005  *
1006  * @return Various things as described above
1007  */

1008public int
1009getopt()
1010{
1011  optarg = null;
1012
1013  if ((nextchar == null) || (nextchar.equals("")))
1014    {
1015      // If we have just processed some options following some non-options,
1016
// exchange them so that the options come first.
1017
if (last_nonopt > optind)
1018        last_nonopt = optind;
1019      if (first_nonopt > optind)
1020        first_nonopt = optind;
1021
1022      if (ordering == PERMUTE)
1023        {
1024          // If we have just processed some options following some non-options,
1025
// exchange them so that the options come first.
1026
if ((first_nonopt != last_nonopt) && (last_nonopt != optind))
1027            exchange(argv);
1028          else if (last_nonopt != optind)
1029            first_nonopt = optind;
1030
1031          // Skip any additional non-options
1032
// and extend the range of non-options previously skipped.
1033
while ((optind < argv.length) && (argv[optind].equals("") ||
1034            (argv[optind].charAt(0) != '-') || argv[optind].equals("-")))
1035            {
1036              optind++;
1037            }
1038          
1039          last_nonopt = optind;
1040        }
1041
1042      // The special ARGV-element `--' means premature end of options.
1043
// Skip it like a null option,
1044
// then exchange with previous non-options as if it were an option,
1045
// then skip everything else like a non-option.
1046
if ((optind != argv.length) && argv[optind].equals("--"))
1047        {
1048          optind++;
1049
1050          if ((first_nonopt != last_nonopt) && (last_nonopt != optind))
1051            exchange (argv);
1052          else if (first_nonopt == last_nonopt)
1053            first_nonopt = optind;
1054
1055          last_nonopt = argv.length;
1056
1057          optind = argv.length;
1058        }
1059
1060      // If we have done all the ARGV-elements, stop the scan
1061
// and back over any non-options that we skipped and permuted.
1062
if (optind == argv.length)
1063        {
1064          // Set the next-arg-index to point at the non-options
1065
// that we previously skipped, so the caller will digest them.
1066
if (first_nonopt != last_nonopt)
1067            optind = first_nonopt;
1068
1069          return(-1);
1070        }
1071
1072      // If we have come to a non-option and did not permute it,
1073
// either stop the scan or describe it to the caller and pass it by.
1074
if (argv[optind].equals("") || (argv[optind].charAt(0) != '-') ||
1075          argv[optind].equals("-"))
1076        {
1077          if (ordering == REQUIRE_ORDER)
1078            return(-1);
1079
1080            optarg = argv[optind++];
1081            return(1);
1082        }
1083      
1084      // We have found another option-ARGV-element.
1085
// Skip the initial punctuation.
1086
if (argv[optind].startsWith("--"))
1087        nextchar = argv[optind].substring(2);
1088      else
1089        nextchar = argv[optind].substring(1);
1090   }
1091
1092  // Decode the current option-ARGV-element.
1093

1094  /* Check whether the ARGV-element is a long option.
1095
1096     If long_only and the ARGV-element has the form "-f", where f is
1097     a valid short option, don't consider it an abbreviated form of
1098     a long option that starts with f. Otherwise there would be no
1099     way to give the -f short option.
1100
1101     On the other hand, if there's a long option "fubar" and
1102     the ARGV-element is "-fu", do consider that an abbreviation of
1103     the long option, just like "--fu", and not "-f" with arg "u".
1104
1105     This distinction seems to be the most useful approach. */

1106  if ((long_options != null) && (argv[optind].startsWith("--")
1107      || (long_only && ((argv[optind].length() > 2) ||
1108      (optstring.indexOf(argv[optind].charAt(1)) == -1)))))
1109    {
1110       int c = checkLongOption();
1111
1112       if (longopt_handled)
1113         return(c);
1114         
1115      // Can't find it as a long option. If this is not getopt_long_only,
1116
// or the option starts with '--' or is not a valid short
1117
// option, then it's an error.
1118
// Otherwise interpret it as a short option.
1119
if (!long_only || argv[optind].startsWith("--")
1120        || (optstring.indexOf(nextchar.charAt(0)) == -1))
1121        {
1122          if (opterr)
1123            {
1124              if (argv[optind].startsWith("--"))
1125                {
1126                  Object JavaDoc[] msgArgs = { progname, nextchar };
1127                  System.err.println(MessageFormat.format(
1128                                   _messages.getString("getopt.unrecognized"),
1129                                   msgArgs));
1130                }
1131              else
1132                {
1133                  Object JavaDoc[] msgArgs = { progname, new
1134                                 Character JavaDoc(argv[optind].charAt(0)).toString(),
1135                                 nextchar };
1136                  System.err.println(MessageFormat.format(
1137                                 _messages.getString("getopt.unrecognized2"),
1138                                 msgArgs));
1139                }
1140            }
1141
1142          nextchar = "";
1143          ++optind;
1144          optopt = 0;
1145    
1146          return('?');
1147        }
1148    } // if (longopts)
1149

1150  // Look at and handle the next short option-character */
1151
int c = nextchar.charAt(0); //**** Do we need to check for empty str?
1152
if (nextchar.length() > 1)
1153    nextchar = nextchar.substring(1);
1154  else
1155    nextchar = "";
1156  
1157  String JavaDoc temp = null;
1158  if (optstring.indexOf(c) != -1)
1159    temp = optstring.substring(optstring.indexOf(c));
1160
1161  if (nextchar.equals(""))
1162    ++optind;
1163
1164  if ((temp == null) || (c == ':'))
1165    {
1166      if (opterr)
1167        {
1168          if (posixly_correct)
1169            {
1170              // 1003.2 specifies the format of this message
1171
Object JavaDoc[] msgArgs = { progname, new
1172                                   Character JavaDoc((char)c).toString() };
1173              System.err.println(MessageFormat.format(
1174                            _messages.getString("getopt.illegal"), msgArgs));
1175            }
1176          else
1177            {
1178              Object JavaDoc[] msgArgs = { progname, new
1179                                   Character JavaDoc((char)c).toString() };
1180              System.err.println(MessageFormat.format(
1181                            _messages.getString("getopt.invalid"), msgArgs));
1182            }
1183        }
1184
1185      optopt = c;
1186
1187      return('?');
1188    }
1189
1190  // Convenience. Treat POSIX -W foo same as long option --foo
1191
if ((temp.charAt(0) == 'W') && (temp.length() > 1) && (temp.charAt(1) == ';'))
1192    {
1193      if (!nextchar.equals(""))
1194        {
1195          optarg = nextchar;
1196        }
1197      // No further cars in this argv element and no more argv elements
1198
else if (optind == argv.length)
1199        {
1200          if (opterr)
1201            {
1202              // 1003.2 specifies the format of this message.
1203
Object JavaDoc[] msgArgs = { progname, new
1204                                   Character JavaDoc((char)c).toString() };
1205              System.err.println(MessageFormat.format(
1206                            _messages.getString("getopt.requires2"), msgArgs));
1207            }
1208
1209          optopt = c;
1210          if (optstring.charAt(0) == ':')
1211            return(':');
1212          else
1213            return('?');
1214        }
1215      else
1216        {
1217          // We already incremented `optind' once;
1218
// increment it again when taking next ARGV-elt as argument.
1219
nextchar = argv[optind];
1220          optarg = argv[optind];
1221        }
1222
1223      c = checkLongOption();
1224
1225      if (longopt_handled)
1226        return(c);
1227      else
1228        // Let the application handle it
1229
{
1230          nextchar = null;
1231          ++optind;
1232          return('W');
1233        }
1234    }
1235
1236  if ((temp.length() > 1) && (temp.charAt(1) == ':'))
1237    {
1238      if ((temp.length() > 2) && (temp.charAt(2) == ':'))
1239        // This is an option that accepts and argument optionally
1240
{
1241          if (!nextchar.equals(""))
1242            {
1243               optarg = nextchar;
1244               ++optind;
1245            }
1246          else
1247            {
1248              optarg = null;
1249            }
1250
1251          nextchar = null;
1252        }
1253      else
1254        {
1255          if (!nextchar.equals(""))
1256            {
1257              optarg = nextchar;
1258              ++optind;
1259            }
1260          else if (optind == argv.length)
1261            {
1262              if (opterr)
1263                {
1264                  // 1003.2 specifies the format of this message
1265
Object JavaDoc[] msgArgs = { progname, new
1266                                       Character JavaDoc((char)c).toString() };
1267                  System.err.println(MessageFormat.format(
1268                            _messages.getString("getopt.requires2"), msgArgs));
1269                }
1270
1271              optopt = c;
1272 
1273              if (optstring.charAt(0) == ':')
1274                return(':');
1275              else
1276                return('?');
1277            }
1278          else
1279            {
1280              optarg = argv[optind];
1281              ++optind;
1282            }
1283
1284          nextchar = null;
1285        }
1286    }
1287
1288  return(c);
1289}
1290
1291} // Class Getopt
1292

1293
1294
Popular Tags