edu.toronto.cs.util
Class Clapi

java.lang.Object
  extended by edu.toronto.cs.util.Clapi

public class Clapi
extends java.lang.Object

Clapi - the Command Line API.

A fancy option parser.

Clapi has a webpage at http://www.svincent.com/shawn/software/Clapi/

Needs lots more features, some of them might be:

XXX bug: suffix, prefix, equals specifiers print out improperly.

XXX bug: should be error if more than one arg arity < 0 specified.

Here's a simple example of how to use it.

  

    import edu.toronto.cs.util.Clapi.*;  

    OptParser optParser = new OptParser ().startClass (MyClass.class);  
    FileNameOpt inputFileOpt = optParser.opt ().nameless ().required ().  
      description ("input file").asFileName ();  
    OptResult optResult = optParser.run (args);  
    String infileName = inputFileOpt.getString (optResult);  

 

Options in Clapi are specified using a builder API.

If you have never worked with a builder API before, it might be a little mysterious. The trick is that every setter method returns a reference to the this pointer, so that further setter methods can be directly chained.

For example, in a typical use of OptSpec:

  
    // --- get an option parser  
    OptParser optParser = new OptParser ();  
      
    // --- make an option.  
    StringOpt stringOpt = optParser.opt ().longName ("stringOpt").  
                          shortName ('s').asString ();  
 

In this example, the call to opt() returns an instance of OptSpec, which then gets longName() called upon it. longName() adds a long name and returns the option specifier again, so that shortName() can be called.

shortName() adds a short name, and returns the option specifier again. At this point, asString () is called, which wraps the OptSpec in a StringOpt, adds the StringOpt to the parser, and finally, returns the StringOpt.

Builder APIs provide a very compact way of specifying algorithms. If we hadn't used a builder API, the above code would have looked like this:

  
    // --- get an option parser  
    OptParser optParser = new OptParser ();  
      
    // --- make an option.  
    OptSpec stringOptSpec = optParser.opt ();  
    stringOptSpec.longName ("stringOpt");  
    stringOptSpec.shortName ('s');  
  
    StringOpt stringOpt = stringOptSpec.asString ();  
 

As you can see, the code is considerably bulkier, and for many sorts of data structures (particularly those you're building by hand all the time), a builder API can be a very succinct way of representing it.

Note that builder APIs are not without their drawbacks. Particularly in a statically typed language, it is often difficult to combine builder APIs with inheritance hierarchies. Often, an intermediate 'specification' object must be used. That approach has been taken with Clapi.


Nested Class Summary
static class Clapi.ArgumentParser
           
static class Clapi.BooleanArgumentParser
           
static class Clapi.BooleanOpt
           
static class Clapi.EatAllParser
           
static class Clapi.FileNameOpt
           
static class Clapi.FilterArgumentParser
           
static class Clapi.HelpArgumentParser
           
static class Clapi.HelpOpt
           
static class Clapi.IntArgumentParser
           
static class Clapi.IntOpt
           
static class Clapi.Opt
          Represents a command-line option.
static class Clapi.OptCompilationFailedException
           
static class Clapi.OptHelpRequestedException
           
static class Clapi.OptParseException
           
static class Clapi.OptParser
          The Option Parser.
static class Clapi.OptResult
           
static class Clapi.OptShortHelpRequestedException
           
static class Clapi.OptSpec
          An option specifier provides a builder API for specifying the features of an option.
static class Clapi.StringArgumentParser
           
static class Clapi.StringOpt
           
 
Constructor Summary
Clapi()
           
 
Method Summary
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Clapi

public Clapi()