|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectedu.toronto.cs.util.Clapi.OptParser
public static class Clapi.OptParser
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.
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 |
---|
public Clapi.OptParser()
Method Detail |
---|
public Clapi.OptParser startClass(java.lang.Class v)
public Clapi.OptParser startClassName(java.lang.String v)
public Clapi.OptParser programName(java.lang.String v)
public Clapi.OptParser version(java.lang.String v)
public Clapi.OptParser author(java.lang.String v)
public Clapi.OptParser webPage(java.lang.String v)
public Clapi.OptParser copyrightNotice(java.lang.String v)
public Clapi.OptParser programDescription(java.lang.String v)
public Clapi.OptParser quote(java.lang.String quote)
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.
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.
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.
tokens
- The tokens to parse
Clapi.OptHelpRequestedException
- If there is an error in the specified optionsparse(String[])
,
#printUsage(PrintWriter,OptParseException)
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.
tokens
- The tokens to parse
Clapi.OptParseException
- If there is an error whilst parsing the tokens.
Clapi.OptHelpRequestedException
- If there is an error in the specified optionsparse(String[])
,
#printUsage(PrintWriter,OptParseException)
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.
out
- The PrintWriter to write the usage info to.ex
- The throwable which caused the usage information
to be printed..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.
out
- The PrintWriter to write the usage info to.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.
out
- The PrintWriter to write the usage info to.public void printSummaryUsage(java.io.PrintWriter _out)
Prints summary usage information to the given PrintWriter.
out
- The PrintWriter to write the usage info to.public void printOptDescriptions(java.io.PrintWriter out)
Prints descriptions of all the options to the given writer.
out
- The PrintWriter to write the usage info to.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.
protected java.lang.String[] preprocessTokens(java.lang.String[] tokens) throws Clapi.OptParseException
Process '@' options, loading sets of options from named files.
tokens
- The tokens to process
Clapi.OptParseException
- Thrown if there is an error loading or parsing anprotected Clapi.Opt getLongOpt(java.lang.String longName) throws Clapi.OptParseException
Clapi.OptParseException
protected Clapi.Opt matchNamelessToken(java.lang.String token)
Attempts to match the given token against all suffix, prefix, equals, or nameless rules.
token
- The token to try to match
null
, if
there is no match.protected java.util.List loadTokenFile(java.lang.String fileName) throws Clapi.OptParseException, java.io.IOException
Load the named @-option file into a List.
fileName
- The name of the file to load.
Clapi.OptParseException
- Thrown if there is an error loading or parsing
the file.
java.io.IOException
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.
wordWrap(PrintWriter,String,int,int,int)
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.
out
- the PrintWriter used to wrap wordstext
- the text to print.leftMargin
- the left margin (in characters)rightMargin
- the right margin (in characters)pageWidth
- the width of the page (in characters)public static java.util.List breakIntoWords(java.lang.String s)
wordWrap
and friends.
public static int contains(java.lang.String val, java.lang.String subject, boolean cases)
printColumn
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |