org.apache.river.system

Class POSIXCommandLine

java.lang.Object

org.apache.river.system.CommandLine

org.apache.river.system.POSIXCommandLine

public class POSIXCommandLine
extends CommandLine

This class parses a command line using POSIX 1003.2-1992 rules. These are:

• Each option name is a single alphanumeric character.
• All options should be preceded by the "-" character
• Options that take no arguments can be grouped together behind a single - (e.g., -nek)
• Each option that takes an argument should be specified separately.
• Arguments to options are not optional; an option either always takes an argument or it doesn't.
• If multiple arguments are given to the same option, they should be separated by commas (e.g., -f path1,path2,path3).
• All options should precede operands on the command line. ("Operands" are the arguments that are not options; in cat -u x y, x and y are operands.)
• The argument -- signals the end of options. All remaining words on the command line are operands
• The order of options relative to one another should not matter.
• For utilities that use operands to specify files to be opened, the "-" should mean standard input or output.

POSIXCommandLine does not enforce the alphanumeric property of option characters, nor that options with arguments must be alone on a line (-nekfpath vs. -nek -fpath). POSIXCommandLine also recognizes the common style of using a -? option to get command usage; nothing prevents you from adding your own option for this purpose. POSIXCommandLine does not aid in splitting up multiple arguments to one option; java.util.StringTokenizer does this quite well enough.

To use POSIXCommandLine, create a POSIXCommandLine object with the array of strings you wish to parse (typically the array passed to the utility's main method), and then consume options from it, providing default values in case the option is not specified by the user. When you have consumed all the options, you invoke the POSIXCommandLine object's getOperands method to return the remaining operands on the command line. If -- is specified it is neither an option nor an operand, just a separator between the two lists. The CommandLine.BadInvocationException is used to signal errors in the construction of the strings, that is, a user error, such as specifying a option that takes an argument but forgetting to provide that argument. See the documentation for POSIXCommandLine.main for an example.

You must call getOperands for proper behavior, even if you do not use any operands in your command. getOperands checks for several user errors, including unknown options. If you do not expect to use operands, you should check the return value of getOperands and complain if any are specified.

You must consume (check for) all options that take arguments before you consume any boolean (no-argument) option. Further, no options can be consumed after getOperands is invoked. Each option character may be used only once. Failure to follow these rule is a programmer error that will result in a CommandLine.ProgrammingException.

POSIXCommandLine provides you several methods to get input streams from the command line. If these do not suffice for your particular needs, you can get the argument as a String and do your own processing.

Author:

Sun Microsystems, Inc.

See Also:

StringTokenizer

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	POSIXCommandLine.Opt Used to store known option types so we can generate a usage message.

Nested classes/interfaces inherited from class org.apache.river.system.CommandLine

CommandLine.BadInvocationException, CommandLine.HelpOnlyException, CommandLine.ProgrammingException

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	allUsed Have all the options been consumed?
private char[][]	args The words blown up into an array of array of characters.
private char	opt
private ArrayList	options The list of known options for the usage message.
private String[]	orig The original words provided.
private int	pos
private String	prog The program name (if specified).
private boolean	singles Have we been asked for any single-character (boolean) options?
private int	str
private static char	USED Marks a character as being used up in the options.
private boolean	usedUp Has the whole command line been eaten (via getOperands)?

Constructor Summary

Constructors

Constructor and Description
POSIXCommandLine(String[] args) Create a new CommandLine object that will return specified options, arguments, and operands.
POSIXCommandLine(String prog, String[] args) Create a new CommandLine object that will return specified options, arguments, and operands.

Method Summary

Modifier and Type	Method and Description
private void	addOpt(char opt, String optType) Add the given option of the given type to the list of known options
private void	assertNoSingles() Assert that no boolean options have yet been consumed.
private void	assertNotUsedUp() Assert that the entire command line hasn't been consumed, that is, that getOperands hasn't yet been called.
private boolean	findOpt(char opt) Find the given option somewhere in the command line.
private String	getArgument(char opt) Return the argument for the given option.
boolean	getBoolean(char opt) Return true if the given option is specified on the command line.
double	getDouble(char opt, double defaultValue) Return the value of the given double from the command line.
InputStream	getInputStream(char opt, InputStream defaultValue) Return a InputStream that is the result of creating a new FileInputStream object for the file named by the given option.
InputStream	getInputStream(char opt, String path) Return a InputStream that is the result of creating a new FileInputStream object for the file named by the given option.
int	getInt(char opt, int defaultValue) Return the argument of the given int option from the command line.
long	getLong(char opt, long defaultValue) Return the argument of the given long option from the command line.
String[]	getOperands() Return the command line operands that come after the options.
OutputStream	getOutputStream(char opt, OutputStream defaultValue) Return a OutputStream that is the result of creating a new FileOutputStream object for the file named by the given option.
OutputStream	getOutputStream(char opt, String path) Return a InputStream that is the result of creating a new FileInputStream object for the file named by the given option.
RandomAccessFile	getRandomAccessFile(char opt, RandomAccessFile defaultValue, String mode) Return a RandomAccessFile that is the result of creating a new RandomAccessFile object for the file named by the given option, using the given mode.
RandomAccessFile	getRandomAccessFile(char opt, String path, String mode) Return a RandomAccessFile that is the result of creating a new RandomAccessFile object for the file named by the given option, using the given mode.
Reader	getReader(char opt, Reader defaultValue) Return a Reader that is the result of creating a new FileReader object for the file named by the given option.
Reader	getReader(char opt, String path) Return a Reader that is the result of creating a new FileReader object for the file named by the given option.
String	getString(char opt, String defaultValue) Return the argument of the given string option from the command line.
Writer	getWriter(char opt, String path) Return a Writer that is the result of creating a new FileWriter object for the file named by the given option.
Writer	getWriter(char opt, Writer defaultValue) Return a Writer that is the result of creating a new FileWriter object for the file named by the given option.
private String	optArg() Return the current option's argument, marking its characters as USED.
void	usage() Print out a summary of the commands usage, inferred from the requested options.

Methods inherited from class org.apache.river.system.CommandLine

parseDouble, parseInputStream, parseInputStream, parseInt, parseLong, parseOutputStream, parseOutputStream, parseRandomAccessFile, parseRandomAccessFile, parseReader, parseReader, parseString, parseWriter, parseWriter

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

orig

private String[] orig

The original words provided.

args

private char[][] args

The words blown up into an array of array of characters.

allUsed

private boolean allUsed

Have all the options been consumed?

singles

private boolean singles

Have we been asked for any single-character (boolean) options?

usedUp

private boolean usedUp

Has the whole command line been eaten (via getOperands)?

options

private ArrayList options

The list of known options for the usage message.

prog

private String prog

The program name (if specified).

str

private int str

pos

private int pos

opt

private char opt

USED

private static final char USED

Marks a character as being used up in the options.

See Also:

Constant Field Values

Constructor Detail

POSIXCommandLine

public POSIXCommandLine(String[] args)

Create a new CommandLine object that will return specified options, arguments, and operands.

POSIXCommandLine

public POSIXCommandLine(String prog,
                        String[] args)

Create a new CommandLine object that will return specified options, arguments, and operands. The prog parameter is the program name.

Method Detail

getBoolean

public boolean getBoolean(char opt)

Return true if the given option is specified on the command line.

getArgument

private String getArgument(char opt)
                    throws CommandLine.BadInvocationException

Return the argument for the given option. This is a workhorse routine shared by all the methods that get options with arguments.

Throws:

CommandLine.BadInvocationException

getString

public String getString(char opt,
                        String defaultValue)
                 throws CommandLine.BadInvocationException

Return the argument of the given string option from the command line. If the option is not specified, return defaultValue.

Throws:

CommandLine.BadInvocationException

getInt

public int getInt(char opt,
                  int defaultValue)
           throws CommandLine.BadInvocationException,
                  NumberFormatException

Return the argument of the given int option from the command line. If the option is not specified, return defaultValue.

Throws:

CommandLine.BadInvocationException

NumberFormatException

See Also:

CommandLine.parseInt(java.lang.String, int)

getLong

public long getLong(char opt,
                    long defaultValue)
             throws CommandLine.BadInvocationException,
                    NumberFormatException

Return the argument of the given long option from the command line. If the option is not specified, return defaultValue.

Throws:

CommandLine.BadInvocationException

NumberFormatException

See Also:

CommandLine.parseLong(java.lang.String, long)

getDouble

public double getDouble(char opt,
                        double defaultValue)
                 throws CommandLine.BadInvocationException,
                        NumberFormatException

Return the value of the given double from the command line. If the option is not specified, return defaultValue.

Throws:

CommandLine.BadInvocationException

NumberFormatException

See Also:

CommandLine.parseDouble(java.lang.String, double)

getWriter

public Writer getWriter(char opt,
                        Writer defaultValue)
                 throws IOException,
                        CommandLine.BadInvocationException

Return a Writer that is the result of creating a new FileWriter object for the file named by the given option. If the option is not specified, return defaultValue.

Throws:

IOException

CommandLine.BadInvocationException

See Also:

CommandLine.parseWriter(java.lang.String,java.io.Writer)

getWriter

public Writer getWriter(char opt,
                        String path)
                 throws IOException,
                        CommandLine.BadInvocationException

Return a Writer that is the result of creating a new FileWriter object for the file named by the given option. If the option is not specified, the string path is used as the file name.

Throws:

IOException

CommandLine.BadInvocationException

See Also:

CommandLine.parseWriter(java.lang.String,java.lang.String)

getReader

public Reader getReader(char opt,
                        Reader defaultValue)
                 throws IOException,
                        CommandLine.BadInvocationException

Return a Reader that is the result of creating a new FileReader object for the file named by the given option. If the option is not specified, return defaultValue.

Throws:

IOException

CommandLine.BadInvocationException

See Also:

CommandLine.parseReader(java.lang.String,java.io.Reader)

getReader

public Reader getReader(char opt,
                        String path)
                 throws IOException,
                        CommandLine.BadInvocationException

Return a Reader that is the result of creating a new FileReader object for the file named by the given option. If the option is not specified, the string path is used as the file name.

Throws:

IOException

CommandLine.BadInvocationException

See Also:

CommandLine.parseReader(java.lang.String,java.lang.String)

getOutputStream

public OutputStream getOutputStream(char opt,
                                    OutputStream defaultValue)
                             throws IOException,
                                    CommandLine.BadInvocationException

Return a OutputStream that is the result of creating a new FileOutputStream object for the file named by the given option. If the argument is - then System.out is returned. If the option is not specified, return defaultValue.

Throws:

IOException

CommandLine.BadInvocationException

See Also:

CommandLine.parseOutputStream(java.lang.String,java.io.OutputStream)

getOutputStream

public OutputStream getOutputStream(char opt,
                                    String path)
                             throws IOException,
                                    CommandLine.BadInvocationException

Return a InputStream that is the result of creating a new FileInputStream object for the file named by the given option. If the option is not specified, the string path is used as the file name.

Throws:

IOException

CommandLine.BadInvocationException

See Also:

CommandLine.parseOutputStream(java.lang.String,java.lang.String)

getInputStream

public InputStream getInputStream(char opt,
                                  InputStream defaultValue)
                           throws IOException,
                                  CommandLine.BadInvocationException

Return a InputStream that is the result of creating a new FileInputStream object for the file named by the given option. If the option is not specified, return defaultValue.

Throws:

IOException

CommandLine.BadInvocationException

See Also:

CommandLine.parseInputStream(java.lang.String,java.io.InputStream)

getInputStream

public InputStream getInputStream(char opt,
                                  String path)
                           throws IOException,
                                  CommandLine.BadInvocationException

Return a InputStream that is the result of creating a new FileInputStream object for the file named by the given option. If the option is not specified, the string path is used as the file name.

Throws:

IOException

CommandLine.BadInvocationException

See Also:

CommandLine.parseInputStream(java.lang.String,java.lang.String)

getRandomAccessFile

public RandomAccessFile getRandomAccessFile(char opt,
                                            RandomAccessFile defaultValue,
                                            String mode)
                                     throws IOException,
                                            CommandLine.BadInvocationException

Return a RandomAccessFile that is the result of creating a new RandomAccessFile object for the file named by the given option, using the given mode. If the option is not specified, return defaultValue.

Throws:

IOException

CommandLine.BadInvocationException

See Also:

CommandLine.parseRandomAccessFile(java.lang.String,java.io.RandomAccessFile,java.lang.String)

getRandomAccessFile

public RandomAccessFile getRandomAccessFile(char opt,
                                            String path,
                                            String mode)
                                     throws IOException,
                                            CommandLine.BadInvocationException

Return a RandomAccessFile that is the result of creating a new RandomAccessFile object for the file named by the given option, using the given mode. If the option is not specified, the string path is used as the file name.

Throws:

IOException

CommandLine.BadInvocationException

See Also:

CommandLine.parseRandomAccessFile(java.lang.String,java.lang.String,java.lang.String)

assertNoSingles

private void assertNoSingles()

Assert that no boolean options have yet been consumed.

assertNotUsedUp

private void assertNotUsedUp()

Assert that the entire command line hasn't been consumed, that is, that getOperands hasn't yet been called.

findOpt

private boolean findOpt(char opt)

Find the given option somewhere in the command line. If the option is not found, return false. Otherwise set str, pos, and opt fields, mark the option character as USED, and then return true.

optArg

private String optArg()
               throws CommandLine.BadInvocationException

Return the current option's argument, marking its characters as USED.

Throws:

BadInvocationException - No argument is given.

CommandLine.BadInvocationException

getOperands

public String[] getOperands()
                     throws CommandLine.BadInvocationException,
                            CommandLine.HelpOnlyException

Return the command line operands that come after the options. This checks to make sure that all specified options have been consumed -- any options remaining at this point are assumed to be unknown options. If no operands remain, an empty array is returned.

This is also where -? is handled. If the user specifies -? then the method usage is invoked and HelpOnlyException is thrown. The program is expected to catch this exception and simply exit successfully.

Throws:

CommandLine.BadInvocationException

CommandLine.HelpOnlyException

See Also:

usage()

addOpt

private void addOpt(char opt,
                    String optType)

Add the given option of the given type to the list of known options. '?' is handled separately in getOperands.

See Also:

getOperands(), usage()

usage

public void usage()

Print out a summary of the commands usage, inferred from the requested options. You can override this to provide a more specific summary. This implementation is only valid after all known options have been requested and getOperands has been (or is being) called. Adds ... for operands.

See Also:

getOperands()