Clapi v1.1

Clapi is a Java library for parsing command-line arguments.

It has a number of useful features common to many command-line arg processors, including, but not limited to:

• Arbitrary number of specifications for each option (long names, short names, suffixes, prefixes, etc)
• Strongly typed options, currently with support for String, Integer, and Boolean options.
• Any option may have arbitrary arity..
• Automatic usage information generation.
• Builtin online help.
• To specify long options, only the minimal unique substring must be specified.
• Long options may be specified using '=' notation (as in --myOption=foobar)
• Option groups.
• @-file processing.

News

March 20^th/2000...7:39AM - First revision, V1.1

Clapi, previously known as OptionLib, has been moved to a new website, and got a bunch of new features. In particular, it now supports the use of '=' in long options, arbitrary argument arity for any option, and some other things that I forget at the moment.

Oh: you now only have to specify the minimally unique substring of long options.

The name Clapi is courtesy of Chris Thiessen.

Using Clapi

The real beauty of Clapi is its clean and powerful usage pattern. Here's an example of a simple use case:

  // --- import the Clapi classes
  import com.mudchicken.util.Clapi.*;

  ...

  public static void main (String[] args)
  {
    // --- make a new parser
    OptParser optParser = new OptParser ().startClass (MyClass.class);

    // --- specify some options
    FileNameOpt inputFileOpt = optParser.opt ().
      nameless ().required ().list ().
      description ("input files").asFileName ();

    // --- parse the tokens
    OptResult optResult = optParser.run (args);

    // --- retrieve the data
    String[] infileNames = inputFileOpt.getStringArray (optResult);

    // --- use the data
    ...
  }
    

With this tiny bit of code, you get online help, usage, fancy and rigorous parsing of typed options... everything that's such a pain to do normally. And it's pleasant to use.

Note that Clapi can do more powerful things than are illustrated here, as well. This example was kept deliberately simple for purposes of demonstration.

Prerequisites

Clapi is a JDK1.2 library: it uses, in particular, the java.util Collections API, and the Random.nextInt(int) method. It would be easy to remove these dependencies, and I am considering doing it in the next version of Clapi, so that Clapi can run in JDK1.1 environments. I have no plans to make Clapi compatible with JDK1.0 environments.

If you use a Microsoft JDK, I will not guarantee that Clapi will work. I refuse to test it there.

Obtaining Clapi

Clapi is a single Java source file, which can be downloaded here. It was deliberately kept contained, so that it would be easy to insert into arbitrary software projects.

download Clapi now...

Documentation

All documentation for Clapi is in the source code. You can build JavaDocs from Clapi.java, and it should be pretty good.

License

Clapi is copyright ©2000 by me, Shawn Vincent. Permission to use Clapi for any purpose is hereby granted: you can sell products based on Clapi, modify Clapi to your heart's content, etc.

I will gladly accept additions to Clapi. If you have a fun extension, and you're getting bored of re-patching the source every time a new version comes out, send me your patch, and I'll incorporate it. These patches, of course, will be placed under the same license as the rest of the product. Credit to the author will be inserted in the source file.

In Summary

I hope you enjoy Clapi. If you have any comments or requests for enhancements, mail me, and I'll see what I can do. Bugs, of course, will be fixed as soon as possible.

To Shawn Vincent's home page -- To www.svincent.com