--All Packages Class Hierarchy This Package Previous Next Index-
-java.lang.Object - | - +----gnu.getopt.Getopt --
- 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. -
- 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. -
- 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. -
- 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. -
- 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". -
- 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. -
- Here is a basic example of using Getopt: -
-
- 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");
- }
- }
-
- - 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. -
- 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. -
- 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. -
- 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". -
- 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(). -
- 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. -
- 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. -
- 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". -
- 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". -
- 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. -
- 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 '?'. -
- 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. -
- 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). -
- 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. -
- 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. -
- 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. -
- Here is an expanded Getopt example using long options and various - techniques described above: -
-
- 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;
- //
- case ':':
- System.out.println("Doh! You need an argument for option " +
- (char)g.getOptopt());
- break;
- //
- case '?':
- System.out.println("The option '" + (char)g.getOptopt() +
- "' is not valid");
- break;
- //
- default:
- System.out.println("getopt() returned " + c);
- break;
- }
- //
- for (int i = g.getOptind(); i < argv.length ; i++)
- System.out.println("Non option argv element: " + argv[i] + "\n");
-
- - There is an alternative form of the constructor used for long options - above. This takes a trailing boolean flag. If set to false, Getopt - performs identically to the example, but if the boolean flag is true - then long options are allowed to start with a single '-' instead of - "--". If the first character of the option is a valid short option - character, then the option is treated as if it were the short option. - Otherwise it behaves as if the option is a long option. Note that - the name given to this option - long_only - is very counter-intuitive. - It does not cause only long options to be parsed but instead enables - the behavior described above. -
- Note that the functionality and variable names used are driven from - the C lib version as this object is a port of the C code, not a - new implementation. This should aid in porting existing C/C++ code, - as well as helping programmers familiar with the glibc version to - adapt to the Java version even if it seems very non-Java at times. -
- In this release I made all instance variables protected due to - overwhelming public demand. Any code which relied on optarg, - opterr, optind, or optopt being public will need to be modified to - use the appropriate access methods. -
- Please send all bug reports, requests, and comments to - arenn@urbanophile.com. -
-
-
- Getopt(String, String[], String)
-
- Getopt(String, String[], String, LongOpt[])
-
- Getopt(String, String[], String, LongOpt[], boolean)
- 
-
- getLongind()
-
- getopt()
-
- getOptarg()
-
- getOptind()
-
- getOptopt()
-
- setArgv(String[])
-
- setOpterr(boolean)
-
- setOptind(int)
-
- setOptstring(String)
- 
-
-Getopt
-- public Getopt(String progname, - String argv[], - String optstring) --
-
-Getopt
-- public Getopt(String progname, - String argv[], - String optstring, - LongOpt long_options[]) --
-
-Getopt
-- public Getopt(String progname, - String argv[], - String optstring, - LongOpt long_options[], - boolean long_only) --
-
-
-setOptstring
-- public void setOptstring(String optstring) --
-
-getOptind
-- public int getOptind() --
-
-setOptind
-- public void setOptind(int optind) --
-
-setArgv
-- public void setArgv(String argv[]) --
-
-getOptarg
-- public String getOptarg() --
-
-setOpterr
-- public void setOpterr(boolean opterr) --
-
-getOptopt
-- public int getOptopt() --
-
-getLongind
-- public int getLongind() --
-
-getopt
-- public int getopt() --
-
-All Packages Class Hierarchy This Package Previous Next Index- - diff --git a/gnu/getopt/gnu.getopt.LongOpt.html b/gnu/getopt/gnu.getopt.LongOpt.html deleted file mode 100644 index ddc1186..0000000 --- a/gnu/getopt/gnu.getopt.LongOpt.html +++ /dev/null @@ -1,210 +0,0 @@ - - - - - -
-All Packages Class Hierarchy This Package Previous Next Index-
-java.lang.Object - | - +----gnu.getopt.LongOpt --
-
-
- NO_ARGUMENT
-
- OPTIONAL_ARGUMENT
-
- REQUIRED_ARGUMENT
-
-
- LongOpt(String, int, StringBuffer, int)
-
-
- getFlag()
-
- getHasArg()
-
- getName()
-
- getVal()
- 
-
-NO_ARGUMENT
-- public static final int NO_ARGUMENT --
-
-REQUIRED_ARGUMENT
-- public static final int REQUIRED_ARGUMENT --
-
-OPTIONAL_ARGUMENT
-- public static final int OPTIONAL_ARGUMENT --
-
-
-LongOpt
-- public LongOpt(String name, - int has_arg, - StringBuffer flag, - int val) throws IllegalArgumentException --
-
-
-getName
-- public String getName() --
-
-getHasArg
-- public int getHasArg() --
-
-getFlag
-- public StringBuffer getFlag() --
-
-getVal
-- public int getVal() --
-
-All Packages Class Hierarchy This Package Previous Next Index- - diff --git a/java-getopt-1.0.13.jar b/java-getopt-1.0.13.jar deleted file mode 100644 index d108633..0000000 Binary files a/java-getopt-1.0.13.jar and /dev/null differ diff --git a/java-getopt-1.0.13.tar.gz b/java-getopt-1.0.13.tar.gz deleted file mode 100644 index dec08da..0000000 Binary files a/java-getopt-1.0.13.tar.gz and /dev/null differ diff --git a/java-getopt-1.0.14.jar b/java-getopt-1.0.14.jar deleted file mode 100644 index afdd2b1..0000000 Binary files a/java-getopt-1.0.14.jar and /dev/null differ diff --git a/java-getopt-1.0.14.tar.gz b/java-getopt-1.0.14.tar.gz deleted file mode 100644 index ec8d79a..0000000 Binary files a/java-getopt-1.0.14.tar.gz and /dev/null differ diff --git a/src/gnu/getopt/.gitignore b/src/gnu/getopt/.gitignore new file mode 100644 index 0000000..92f9779 --- /dev/null +++ b/src/gnu/getopt/.gitignore @@ -0,0 +1,3 @@ +build +src + diff --git a/gnu/getopt/COPYING.LIB b/src/gnu/getopt/COPYING.LIB similarity index 100% rename from gnu/getopt/COPYING.LIB rename to src/gnu/getopt/COPYING.LIB diff --git a/gnu/getopt/ChangeLog b/src/gnu/getopt/ChangeLog similarity index 100% rename from gnu/getopt/ChangeLog rename to src/gnu/getopt/ChangeLog diff --git a/gnu/getopt/Getopt.java b/src/gnu/getopt/Getopt.java similarity index 100% rename from gnu/getopt/Getopt.java rename to src/gnu/getopt/Getopt.java diff --git a/gnu/getopt/LANGUAGES b/src/gnu/getopt/LANGUAGES similarity index 100% rename from gnu/getopt/LANGUAGES rename to src/gnu/getopt/LANGUAGES diff --git a/gnu/getopt/LongOpt.java b/src/gnu/getopt/LongOpt.java similarity index 100% rename from gnu/getopt/LongOpt.java rename to src/gnu/getopt/LongOpt.java diff --git a/gnu/getopt/MessagesBundle.properties b/src/gnu/getopt/MessagesBundle.properties similarity index 100% rename from gnu/getopt/MessagesBundle.properties rename to src/gnu/getopt/MessagesBundle.properties diff --git a/gnu/getopt/MessagesBundle_chs.properties b/src/gnu/getopt/MessagesBundle_chs.properties similarity index 100% rename from gnu/getopt/MessagesBundle_chs.properties rename to src/gnu/getopt/MessagesBundle_chs.properties diff --git a/gnu/getopt/MessagesBundle_cht.properties b/src/gnu/getopt/MessagesBundle_cht.properties similarity index 100% rename from gnu/getopt/MessagesBundle_cht.properties rename to src/gnu/getopt/MessagesBundle_cht.properties diff --git a/gnu/getopt/MessagesBundle_cs.properties b/src/gnu/getopt/MessagesBundle_cs.properties similarity index 100% rename from gnu/getopt/MessagesBundle_cs.properties rename to src/gnu/getopt/MessagesBundle_cs.properties diff --git a/gnu/getopt/MessagesBundle_de.properties b/src/gnu/getopt/MessagesBundle_de.properties similarity index 100% rename from gnu/getopt/MessagesBundle_de.properties rename to src/gnu/getopt/MessagesBundle_de.properties diff --git a/gnu/getopt/MessagesBundle_es.properties b/src/gnu/getopt/MessagesBundle_es.properties similarity index 100% rename from gnu/getopt/MessagesBundle_es.properties rename to src/gnu/getopt/MessagesBundle_es.properties diff --git a/gnu/getopt/MessagesBundle_fr.properties b/src/gnu/getopt/MessagesBundle_fr.properties similarity index 100% rename from gnu/getopt/MessagesBundle_fr.properties rename to src/gnu/getopt/MessagesBundle_fr.properties diff --git a/gnu/getopt/MessagesBundle_hu.properties b/src/gnu/getopt/MessagesBundle_hu.properties similarity index 100% rename from gnu/getopt/MessagesBundle_hu.properties rename to src/gnu/getopt/MessagesBundle_hu.properties diff --git a/gnu/getopt/MessagesBundle_it.properties b/src/gnu/getopt/MessagesBundle_it.properties similarity index 100% rename from gnu/getopt/MessagesBundle_it.properties rename to src/gnu/getopt/MessagesBundle_it.properties diff --git a/gnu/getopt/MessagesBundle_ja.properties b/src/gnu/getopt/MessagesBundle_ja.properties similarity index 100% rename from gnu/getopt/MessagesBundle_ja.properties rename to src/gnu/getopt/MessagesBundle_ja.properties diff --git a/gnu/getopt/MessagesBundle_nl.properties b/src/gnu/getopt/MessagesBundle_nl.properties similarity index 100% rename from gnu/getopt/MessagesBundle_nl.properties rename to src/gnu/getopt/MessagesBundle_nl.properties diff --git a/gnu/getopt/MessagesBundle_no.properties b/src/gnu/getopt/MessagesBundle_no.properties similarity index 100% rename from gnu/getopt/MessagesBundle_no.properties rename to src/gnu/getopt/MessagesBundle_no.properties diff --git a/gnu/getopt/MessagesBundle_pl.properties b/src/gnu/getopt/MessagesBundle_pl.properties similarity index 100% rename from gnu/getopt/MessagesBundle_pl.properties rename to src/gnu/getopt/MessagesBundle_pl.properties diff --git a/gnu/getopt/MessagesBundle_ro.properties b/src/gnu/getopt/MessagesBundle_ro.properties similarity index 100% rename from gnu/getopt/MessagesBundle_ro.properties rename to src/gnu/getopt/MessagesBundle_ro.properties diff --git a/gnu/getopt/README b/src/gnu/getopt/README similarity index 100% rename from gnu/getopt/README rename to src/gnu/getopt/README diff --git a/gnu/getopt/GetoptDemo.java b/src/gnu/getopt/demo/GetoptDemo.java similarity index 99% rename from gnu/getopt/GetoptDemo.java rename to src/gnu/getopt/demo/GetoptDemo.java index b57c5a8..fee94a6 100644 --- a/gnu/getopt/GetoptDemo.java +++ b/src/gnu/getopt/demo/GetoptDemo.java @@ -1,3 +1,5 @@ +package gnu.getopt.demo; + import gnu.getopt.LongOpt; import gnu.getopt.Getopt;