getopt.java

it is a basic java browser

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

package gnu.getopt;

import java.util.Locale;
import java.util.ResourceBundle;
import java.util.PropertyResourceBundle;
import java.text.MessageFormat;

/**************************************************************************/

/**
  * This is a Java port of GNU getopt, a class for parsing command line
  * arguments passed to programs.  It it based on the C getopt() functions
  * in glibc 2.0.6 and should parse options in a 100% compatible manner.
  * If it does not, that is a bug.  The programmer's interface is also
  * very compatible.
  * <p>
  * To use Getopt, create a Getopt object with a argv array passed to the
  * main method, then call the getopt() method in a loop.  It will return an
  * int that contains the value of the option character parsed from the
  * command line.  When there are no more options to be parsed, it
  * returns -1.
  * <p>
  * A command line option can be defined to take an argument.  If an
  * option has an argument, the value of that argument is stored in an
  * instance variable called optarg, which can be accessed using the
  * getOptarg() method.  If an option that requires an argument is
  * found, but there is no argument present, then an error message is
  * printed. Normally getopt() returns a '?' in this situation, but
  * that can be changed as described below.
  * <p>
  * If an invalid option is encountered, an error message is printed
  * to the standard error and getopt() returns a '?'.  The value of the
  * invalid option encountered is stored in the instance variable optopt
  * which can be retrieved using the getOptopt() method.  To suppress
  * the printing of error messages for this or any other error, set
  * the value of the opterr instance variable to false using the 
  * setOpterr() method.
  * <p>
  * Between calls to getopt(), the instance variable optind is used to
  * keep track of where the object is in the parsing process.  After all
  * options have been returned, optind is the index in argv of the first
  * non-option argument.  This variable can be accessed with the getOptind()
  * method.
  * <p>
  * Note that this object expects command line options to be passed in the
  * traditional Unix manner.  That is, proceeded by a '-' character. 
  * Multiple options can follow the '-'.  For example "-abc" is equivalent
  * to "-a -b -c".  If an option takes a required argument, the value
  * of the argument can immediately follow the option character or be
  * present in the next argv element.  For example, "-cfoo" and "-c foo"
  * both represent an option character of 'c' with an argument of "foo"
  * assuming c takes a required argument.  If an option takes an argument
  * that is not required, then any argument must immediately follow the
  * option character in the same argv element.  For example, if c takes
  * a non-required argument, then "-cfoo" represents option character 'c'
  * with an argument of "foo" while "-c foo" represents the option
  * character 'c' with no argument, and a first non-option argv element
  * of "foo".
  * <p>
  * The user can stop getopt() from scanning any further into a command line
  * by using the special argument "--" by itself.  For example: 
  * "-a -- -d" would return an option character of 'a', then return -1
  * The "--" is discarded and "-d" is pointed to by optind as the first
  * non-option argv element.
  * <p>
  * Here is a basic example of using Getopt:
  * <p>
  * <pre>
  * Getopt g = new Getopt("testprog", argv, "ab:c::d");
  * //
  * int c;
  * String arg;
  * while ((c = g.getopt()) != -1)
  *   {
  *     switch(c)
  *       {
  *          case 'a':
  *          case 'd':
  *            System.out.print("You picked " + (char)c + "\n");
  *            break;
  *            //
  *          case 'b':
  *          case 'c':
  *            arg = g.getOptarg();
  *            System.out.print("You picked " + (char)c + 
  *                             " with an argument of " +
  *                             ((arg != null) ? arg : "null") + "\n");
  *            break;
  *            //
  *          case '?':
  *            break; // getopt() already printed an error
  *            //
  *          default:
  *            System.out.print("getopt() returned " + c + "\n");
  *       }
  *   }
  * </pre>
  * <p>
  * In this example, a new Getopt object is created with three params.
  * The first param is the program name.  This is for printing error
  * messages in the form "program: error message".  In the C version, this
  * value is taken from argv[0], but in Java the program name is not passed
  * in that element, thus the need for this parameter.  The second param is
  * the argument list that was passed to the main() method.  The third
  * param is the list of valid options.  Each character represents a valid
  * option.  If the character is followed by a single colon, then that
  * option has a required argument.  If the character is followed by two
  * colons, then that option has an argument that is not required.
  * <p>
  * Note in this example that the value returned from getopt() is cast to
  * a char prior to printing.  This is required in order to make the value
  * display correctly as a character instead of an integer.
  * <p>
  * If the first character in the option string is a colon, for example
  * ":abc::d", then getopt() will return a ':' instead of a '?' when it
  * encounters an option with a missing required argument.  This allows the
  * caller to distinguish between invalid options and valid options that
  * are simply incomplete.
  * <p>
  * In the traditional Unix getopt(), -1 is returned when the first non-option
  * charcter is encountered.  In GNU getopt(), the default behavior is to
  * allow options to appear anywhere on the command line.  The getopt()
  * method permutes the argument to make it appear to the caller that all
  * options were at the beginning of the command line, and all non-options
  * were at the end.  For example, calling getopt() with command line args
  * of "-a foo bar -d" returns options 'a' and 'd', then sets optind to 
  * point to "foo".  The program would read the last two argv elements as
  * "foo" and "bar", just as if the user had typed "-a -d foo bar". 
  * <p> 
  * The user can force getopt() to stop scanning the command line with
  * the special argument "--" by itself.  Any elements occuring before the
  * "--" are scanned and permuted as normal.  Any elements after the "--"
  * are returned as is as non-option argv elements.  For example, 
  * "foo -a -- bar -d" would return  option 'a' then -1.  optind would point 
  * to "foo", "bar" and "-d" as the non-option argv elements.  The "--"
  * is discarded by getopt().
  * <p>
  * There are two ways this default behavior can be modified.  The first is
  * to specify traditional Unix getopt() behavior (which is also POSIX
  * behavior) in which scanning stops when the first non-option argument
  * encountered.  (Thus "-a foo bar -d" would return 'a' as an option and
  * have "foo", "bar", and "-d" as non-option elements).  The second is to
  * allow options anywhere, but to return all elements in the order they
  * occur on the command line.  When a non-option element is ecountered,
  * an integer 1 is returned and the value of the non-option element is
  * stored in optarg is if it were the argument to that option.  For
  * example, "-a foo -d", returns first 'a', then 1 (with optarg set to
  * "foo") then 'd' then -1.  When this "return in order" functionality
  * is enabled, the only way to stop getopt() from scanning all command
  * line elements is to use the special "--" string by itself as described
  * above.  An example is "-a foo -b -- bar", which would return 'a', then
  * integer 1 with optarg set to "foo", then 'b', then -1.  optind would
  * then point to "bar" as the first non-option argv element.  The "--"
  * is discarded.
  * <p>
  * The POSIX/traditional behavior is enabled by either setting the 
  * property "gnu.posixly_correct" or by putting a '+' sign as the first
  * character of the option string.  The difference between the two 
  * methods is that setting the gnu.posixly_correct property also forces
  * certain error messages to be displayed in POSIX format.  To enable
  * the "return in order" functionality, put a '-' as the first character
  * of the option string.  Note that after determining the proper 
  * behavior, Getopt strips this leading '+' or '-', meaning that a ':'
  * placed as the second character after one of those two will still cause
  * getopt() to return a ':' instead of a '?' if a required option
  * argument is missing.
  * <p>
  * In addition to traditional single character options, GNU Getopt also
  * supports long options.  These are preceeded by a "--" sequence and
  * can be as long as desired.  Long options provide a more user-friendly
  * way of entering command line options.  For example, in addition to a
  * "-h" for help, a program could support also "--help".  
  * <p>
  * Like short options, long options can also take a required or non-required 
  * argument.  Required arguments can either be specified by placing an
  * equals sign after the option name, then the argument, or by putting the
  * argument in the next argv element.  For example: "--outputdir=foo" and
  * "--outputdir foo" both represent an option of "outputdir" with an
  * argument of "foo", assuming that outputdir takes a required argument.
  * If a long option takes a non-required argument, then the equals sign
  * form must be used to specify the argument.  In this case,
  * "--outputdir=foo" would represent option outputdir with an argument of
  * "foo" while "--outputdir foo" would represent the option outputdir
  * with no argument and a first non-option argv element of "foo".
  * <p>
  * Long options can also be specified using a special POSIX argument 
  * format (one that I highly discourage).  This form of entry is 
  * enabled by placing a "W;" (yes, 'W' then a semi-colon) in the valid
  * option string.  This causes getopt to treat the name following the
  * "-W" as the name of the long option.  For example, "-W outputdir=foo"
  * would be equivalent to "--outputdir=foo".  The name can immediately
  * follow the "-W" like so: "-Woutputdir=foo".  Option arguments are
  * handled identically to normal long options.  If a string follows the 
  * "-W" that does not represent a valid long option, then getopt() returns
  * 'W' and the caller must decide what to do.  Otherwise getopt() returns
  * a long option value as described below.
  * <p>
  * While long options offer convenience, they can also be tedious to type
  * in full.  So it is permissible to abbreviate the option name to as
  * few characters as required to uniquely identify it.  If the name can
  * represent multiple long options, then an error message is printed and
  * getopt() returns a '?'.  
  * <p>
  * If an invalid option is specified or a required option argument is 
  * missing, getopt() prints an error and returns a '?' or ':' exactly
  * as for short options.  Note that when an invalid long option is
  * encountered, the optopt variable is set to integer 0 and so cannot
  * be used to identify the incorrect option the user entered.
  * <p>
  * Long options are defined by LongOpt objects.  These objects are created
  * with a contructor that takes four params: a String representing the
  * object name, a integer specifying what arguments the option takes
  * (the value is one of LongOpt.NO_ARGUMENT, LongOpt.REQUIRED_ARGUMENT,
  * or LongOpt.OPTIONAL_ARGUMENT), a StringBuffer flag object (described
  * below), and an integer value (described below).
  * <p>
  * To enable long option parsing, create an array of LongOpt's representing
  * the legal options and pass it to the Getopt() constructor.  WARNING: If
  * all elements of the array are not populated with LongOpt objects, the
  * getopt() method will throw a NullPointerException.
  * <p>
  * When getopt() is called and a long option is encountered, one of two
  * things can be returned.  If the flag field in the LongOpt object 
  * representing the long option is non-null, then the integer value field
  * is stored there and an integer 0 is returned to the caller.  The val
  * field can then be retrieved from the flag field.  Note that since the
  * flag field is a StringBuffer, the appropriate String to integer converions
  * must be performed in order to get the actual int value stored there.
  * If the flag field in the LongOpt object is null, then the value field
  * of the LongOpt is returned.  This can be the character of a short option.
  * This allows an app to have both a long and short option sequence 
  * (say, "-h" and "--help") that do the exact same thing.
  * <p>
  * With long options, there is an alternative method of determining 
  * which option was selected.  The method getLongind() will return the
  * the index in the long option array (NOT argv) of the long option found.
  * So if multiple long options are configured to return the same value,
  * the application can use getLongind() to distinguish between them. 
  * <p>
  * Here is an expanded Getopt example using long options and various
  * techniques described above:
  * <p>
  * <pre>
  * int c;
  * String arg;
  * LongOpt[] longopts = new LongOpt[3];
  * // 
  * StringBuffer sb = new StringBuffer();
  * longopts[0] = new LongOpt("help", LongOpt.NO_ARGUMENT, null, 'h');
  * longopts[1] = new LongOpt("outputdir", LongOpt.REQUIRED_ARGUMENT, sb, 'o'); 
  * longopts[2] = new LongOpt("maximum", LongOpt.OPTIONAL_ARGUMENT, null, 2);
  * // 
  * Getopt g = new Getopt("testprog", argv, "-:bc::d:hW;", longopts);
  * g.setOpterr(false); // We'll do our own error handling
  * //
  * while ((c = g.getopt()) != -1)
  *   switch (c)
  *     {
  *        case 0:
  *          arg = g.getOptarg();
  *          System.out.println("Got long option with value '" +
  *                             (char)(new Integer(sb.toString())).intValue()
  *                             + "' with argument " +
  *                             ((arg != null) ? arg : "null"));
  *          break;
  *          //
  *        case 1:
  *          System.out.println("I see you have return in order set and that " +
  *                             "a non-option argv element was just found " +
  *                             "with the value '" + g.getOptarg() + "'");
  *          break;
  *          //
  *        case 2:
  *          arg = g.getOptarg();
  *          System.out.println("I know this, but pretend I didn't");
  *          System.out.println("We picked option " +
  *                             longopts[g.getLongind()].getName() +
  *                           " with value " + 
  *                           ((arg != null) ? arg : "null"));
  *          break;
  *          //
  *        case 'b':
  *          System.out.println("You picked plain old option " + (char)c);
  *          break;
  *          //
  *        case 'c':
  *        case 'd':
  *          arg = g.getOptarg();
  *          System.out.println("You picked option '" + (char)c + 
  *                             "' with argument " +
  *                             ((arg != null) ? arg : "null"));
  *          break;
  *          //
  *        case 'h':
  *          System.out.println("I see you asked for help");
  *          break;
  *          //
  *        case 'W':
  *          System.out.println("Hmmm. You tried a -W with an incorrect long " +
  *                             "option name");
  *          break;
  *          //