com.sun.jini.system
Class MultiCommandLine

java.lang.Object
  extended by com.sun.jini.system.CommandLine
      extended by com.sun.jini.system.MultiCommandLine

public class MultiCommandLine
extends CommandLine

This class parses a command line that uses multi-character options, such as -verbose or -help.

To use MultiCommandLine, create a MultiCommandLine 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 MultiCommandLine 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 MultiCommandLine.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.

No options can be consumed after getOperands is invoked. Each option may be used only once. Failure to follow these rule is a programmer error that will result in a CommandLine.ProgrammingException.

MultiCommandLine 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
private static class MultiCommandLine.Opt
          Used to store known option types so we can generate a usage message.
 
Nested classes/interfaces inherited from class com.sun.jini.system.CommandLine
CommandLine.BadInvocationException, CommandLine.HelpOnlyException, CommandLine.ProgrammingException
 
Field Summary
private  boolean allUsed
          Have all the options been consumed?
private  String[] args
          The args provided.
private  String opt
           
private  ArrayList options
          The list of known options for the usage message.
private  String prog
          The program name (if specified).
private  int str
           
private  BitSet used
          which ones have been used?
private  boolean usedUp
          Has the whole command line been eaten (via getOperands)?
 
Constructor Summary
MultiCommandLine(String[] args)
          Create a new MultiCommandLine object that will return specified options, arguments, and operands.
MultiCommandLine(String prog, String[] args)
          Create a new MultiCommandLine object that will return specified options, arguments, and operands.
 
Method Summary
private  void addOpt(String opt, String optType)
          Add the given option of the given type to the list of known options. "-?"
private  boolean findOpt(String opt)
          Find the given option somewhere in the command line.
private  String getArgument(String opt)
          Return the argument for the given option.
 boolean getBoolean(String opt)
          Return true if the given option is specified on the command line.
 double getDouble(String opt, double defaultValue)
          Return the value of the given double from the command line.
 InputStream getInputStream(String 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(String 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(String opt, int defaultValue)
          Return the argument of the given int option from the command line.
 long getLong(String 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(String 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(String 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(String 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(String 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(String 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(String 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(String opt, String defaultValue)
          Return the argument of the given string option from the command line.
 Writer getWriter(String 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(String 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 static boolean isHelp(String opt)
           
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 com.sun.jini.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

args

private String[] args
The args provided.


used

private BitSet used
which ones have been used?


allUsed

private boolean allUsed
Have all the options been consumed?


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

opt

private String opt
Constructor Detail

MultiCommandLine

public MultiCommandLine(String[] args)
Create a new MultiCommandLine object that will return specified options, arguments, and operands.


MultiCommandLine

public MultiCommandLine(String prog,
                        String[] args)
Create a new MultiCommandLine object that will return specified options, arguments, and operands. The prog parameter is the program name.

Method Detail

getBoolean

public boolean getBoolean(String opt)
Return true if the given option is specified on the command line.


getArgument

private String getArgument(String 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(String 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(String 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(String 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(String 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(String 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(String 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(String 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(String 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(String 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 option is not specified, return defaultValue.

Throws:
IOException
CommandLine.BadInvocationException
See Also:
CommandLine.parseOutputStream(java.lang.String,java.io.OutputStream)

getOutputStream

public OutputStream getOutputStream(String 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(String 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(String 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(String 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(String 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)

findOpt

private boolean findOpt(String 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(String opt,
                    String optType)
Add the given option of the given type to the list of known options. "-?" and "-help" are handled separately in getOperands.

See Also:
getOperands(), usage()

isHelp

private static boolean isHelp(String opt)

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()


Copyright 2007-2010, multiple authors.
Licensed under the Apache License, Version 2.0, see the NOTICE file for attributions.