edu.toronto.cs.util
Class Clapi.OptParser

java.lang.Object
  extended by edu.toronto.cs.util.Clapi.OptParser
Enclosing class:
Clapi

public static class Clapi.OptParser
extends java.lang.Object

The Option Parser.

Responsible for creating options and parsing String arrays into OptResults.

There are two ways to invoke the compiler. The first, run() does everything for you: it prints usage information, calls System.exit() if there is any errors, and mostly goes about making itself useful.

For second mode of running, call parse(). If there is any error, this method throws a subclass of OptParseException. You can deal with this, if you like, by calling printUsage, and then taking whichever steps you'd like to deal with the error condition.

If there is any problem with the specification of the options by you, the programmer, the runtime exception OptCompilationFailedException is thrown. This exception should probably not be caught and handled. As much as possible, static typing has been used to remove sources of errors in the specification.

parse or run may be called multiple times, and new options may be added to the parser between runs.

The parser, on construction, automatically adds the options --help, -h, and -?. These options all print usage information. There is currently no way of supressing this behavior.

See Also:
opt(), run(String[]), parse(String[])

Constructor Summary
Clapi.OptParser()
          Make a new option parser.
 
Method Summary
 Clapi.Opt addOpt(Clapi.Opt opt)
          Adds a new option to this OptParser.
 Clapi.OptParser author(java.lang.String v)
          Specify the name of the program's author (banner information)
static java.util.List breakIntoWords(java.lang.String s)
          Breaks the given string into words.
protected  void compile()
          Initializes internal data structures and keys for the options, in preparation for parsing and/or printing usage information.
static int contains(java.lang.String val, java.lang.String subject, boolean cases)
          Support method for printColumn
 Clapi.OptParser copyrightNotice(java.lang.String v)
          Specify the program's copyright notice (banner information)
protected  Clapi.Opt getLongOpt(java.lang.String longName)
           
protected  java.util.List loadTokenFile(java.lang.String fileName)
          Load the named @-option file into a List.
protected  Clapi.Opt matchNamelessToken(java.lang.String token)
          Attempts to match the given token against all suffix, prefix, equals, or nameless rules.
 Clapi.OptSpec opt()
          Start making a new Option.
 Clapi.OptResult parse(java.lang.String[] _tokens)
          Parses the given token array, returning the result of the parse.
protected  java.lang.String[] preprocessTokens(java.lang.String[] tokens)
          Process '@' options, loading sets of options from named files.
 void printBanner(java.io.PrintWriter out)
          Prints a pleasant banner describing the program.
 void printOptDescriptions(java.io.PrintWriter out)
          Prints descriptions of all the options to the given writer.
 void printSummaryUsage(java.io.PrintWriter _out)
          Prints summary usage information to the given PrintWriter.
 void printUsage(java.io.PrintWriter out)
          Prints usage information for a program based on the specified options and program information.
 void printUsage(java.io.PrintWriter out, Clapi.OptParseException ex)
          Prints usage information for a program based on the specified options and program information.
 Clapi.OptParser programDescription(java.lang.String v)
          Specify the program's description (banner information)
 Clapi.OptParser programName(java.lang.String v)
          Specify the name of the program (banner information)
 Clapi.OptParser quote(java.lang.String quote)
          Add a random quote to the set of quotes that can be randomly printed with the usage information.
 Clapi.OptResult run(java.lang.String[] tokens)
          Defined as running and returning the result of parse() with the given tokens.
 Clapi.OptParser startClass(java.lang.Class v)
          Specify the startup class, for usage information.
 Clapi.OptParser startClassName(java.lang.String v)
          Specify the name of the startup class, for usage information.
 Clapi.OptParser version(java.lang.String v)
          Specify the version of the program (banner information)
 Clapi.OptParser webPage(java.lang.String v)
          Specify the name of the program's webpage (banner information)
static void wordWrap(java.io.PrintWriter out, java.lang.String t, int leftMargin, int rightMargin)
          Word-wrap the specified text to an 80-column screen.
static void wordWrap(java.io.PrintWriter out, java.lang.String text, int leftMargin, int rightMargin, int pageWidth)
          Word-wrap the specified text to a PrintWriter.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Clapi.OptParser

public Clapi.OptParser()
Make a new option parser.

Method Detail

startClass

public Clapi.OptParser startClass(java.lang.Class v)
Specify the startup class, for usage information.


startClassName

public Clapi.OptParser startClassName(java.lang.String v)
Specify the name of the startup class, for usage information.


programName

public Clapi.OptParser programName(java.lang.String v)
Specify the name of the program (banner information)


version

public Clapi.OptParser version(java.lang.String v)
Specify the version of the program (banner information)


author

public Clapi.OptParser author(java.lang.String v)
Specify the name of the program's author (banner information)


webPage

public Clapi.OptParser webPage(java.lang.String v)
Specify the name of the program's webpage (banner information)


copyrightNotice

public Clapi.OptParser copyrightNotice(java.lang.String v)
Specify the program's copyright notice (banner information)


programDescription

public Clapi.OptParser programDescription(java.lang.String v)
Specify the program's description (banner information)


quote

public Clapi.OptParser quote(java.lang.String quote)
Add a random quote to the set of quotes that can be randomly printed with the usage information.


opt

public Clapi.OptSpec opt()

Start making a new Option.

This method returns an OptSpec instance, which has a builder API upon it with which you specify things about the option you want to build (i.e. - long & short names, description, min/max arities, etc).

When you're done, call one of the asType() (i.e. - asInt(), asString(), etc) methods to get an Opt instance of the appropriate type.


addOpt

public Clapi.Opt addOpt(Clapi.Opt opt)

Adds a new option to this OptParser. Normally, you do not call this method directly, instead calling opt and using the builder API provided.


run

public Clapi.OptResult run(java.lang.String[] tokens)

Defined as running and returning the result of parse() with the given tokens.

If there is an OptParseException during the execution of parse(), it is caught, usage information is printed to System.out, and System.exit(1) is called.

Parameters:
tokens - The tokens to parse
Returns:
The parse result data structure
Throws:
Clapi.OptHelpRequestedException - If there is an error in the specified options
See Also:
parse(String[]), #printUsage(PrintWriter,OptParseException)

parse

public Clapi.OptResult parse(java.lang.String[] _tokens)
                      throws Clapi.OptParseException

Parses the given token array, returning the result of the parse.

If one of the constraints specified when building the options is violated, an instance of OptParseException is thrown.

Parameters:
tokens - The tokens to parse
Returns:
The parse result data structure
Throws:
Clapi.OptParseException - If there is an error whilst parsing the tokens.
Clapi.OptHelpRequestedException - If there is an error in the specified options
See Also:
parse(String[]), #printUsage(PrintWriter,OptParseException)

printUsage

public void printUsage(java.io.PrintWriter out,
                       Clapi.OptParseException ex)

Prints usage information for a program based on the specified options and program information.

Also prints the message from the exception before printing usage.

Parameters:
out - The PrintWriter to write the usage info to.
ex - The throwable which caused the usage information to be printed..

printUsage

public void printUsage(java.io.PrintWriter out)

Prints usage information for a program based on the specified options and program information.

Prints a banner, summary usage, and option descriptions.

Parameters:
out - The PrintWriter to write the usage info to.

printBanner

public void printBanner(java.io.PrintWriter out)

Prints a pleasant banner describing the program. The information used for this banner is specified by calls to the OptParser object.

Parameters:
out - The PrintWriter to write the usage info to.

printSummaryUsage

public void printSummaryUsage(java.io.PrintWriter _out)

Prints summary usage information to the given PrintWriter.

Parameters:
out - The PrintWriter to write the usage info to.

printOptDescriptions

public void printOptDescriptions(java.io.PrintWriter out)

Prints descriptions of all the options to the given writer.

Parameters:
out - The PrintWriter to write the usage info to.

compile

protected void compile()

Initializes internal data structures and keys for the options, in preparation for parsing and/or printing usage information.

This method only rebuilds these data structures if the option specifications are 'dirty': that is, if they have been changed.


preprocessTokens

protected java.lang.String[] preprocessTokens(java.lang.String[] tokens)
                                       throws Clapi.OptParseException

Process '@' options, loading sets of options from named files.

Parameters:
tokens - The tokens to process
Returns:
The given tokens, with @ options expanded.
Throws:
Clapi.OptParseException - Thrown if there is an error loading or parsing an

getLongOpt

protected Clapi.Opt getLongOpt(java.lang.String longName)
                        throws Clapi.OptParseException
Throws:
Clapi.OptParseException

matchNamelessToken

protected Clapi.Opt matchNamelessToken(java.lang.String token)

Attempts to match the given token against all suffix, prefix, equals, or nameless rules.

Parameters:
token - The token to try to match
Returns:
The matched option, or null, if there is no match.

loadTokenFile

protected java.util.List loadTokenFile(java.lang.String fileName)
                                throws Clapi.OptParseException,
                                       java.io.IOException

Load the named @-option file into a List.

Parameters:
fileName - The name of the file to load.
Returns:
A List containing the options loaded from the file.
Throws:
Clapi.OptParseException - Thrown if there is an error loading or parsing the file.
java.io.IOException

wordWrap

public static void wordWrap(java.io.PrintWriter out,
                            java.lang.String t,
                            int leftMargin,
                            int rightMargin)

Word-wrap the specified text to an 80-column screen.

See Also:
wordWrap(PrintWriter,String,int,int,int)

wordWrap

public static void wordWrap(java.io.PrintWriter out,
                            java.lang.String text,
                            int leftMargin,
                            int rightMargin,
                            int pageWidth)

Word-wrap the specified text to a PrintWriter.

The algorithm used here is very expensive, and so has limited applicability. For use in a usage printing scenario, this is fine. Simplicity and straightforwardness matters more to me here than screaming performance while printing how to use grep.

Parameters:
out - the PrintWriter used to wrap words
text - the text to print.
leftMargin - the left margin (in characters)
rightMargin - the right margin (in characters)
pageWidth - the width of the page (in characters)

breakIntoWords

public static java.util.List breakIntoWords(java.lang.String s)
Breaks the given string into words. Used in support of wordWrap and friends.


contains

public static int contains(java.lang.String val,
                           java.lang.String subject,
                           boolean cases)
Support method for printColumn