LAPIS

LAPIS Coding Conventions

Package Structure

The LAPIS classes are divided into a number of packages. Any new classes you create should be put into the appropriate package.

The classes for LAPIS itself are found in lapis and its subpackages:
lapis
 classes and interfaces for dealing with documents and region sets, abstractly
lapis.tools
 text-processing commands, like Sort and Extract
lapis.tc
 text constraint (TC) pattern matching
lapis.tcl
 Tcl interpreter interface
lapis.maps
 implementations of lapis.CoordinateMap
lapis.trees
 implementations of lapis.RegionSet
lapis.ml
 machine-learning code, like simultaneous editing and outlier finding
lapis.swing
 Swing user interface code
lapis.parsers
 built-in parsers, like HTML, Java, and Characters

The Tcl interpreter included in LAPIS can be found in the tcl package and its subpackages.
tcl.lang,
tcl.lang.reflect,
tcl.regex
 the Tcl interpreter, which is called Jacl. We didn't write this ourselves, but we modified it slightly.

Auxilliary classes which are needed by LAPIS but do not depend on the rest of LAPIS are found in lapisx and its subpackages:
lapisx.io
 IO-related classes (analogous to java.io)
lapisx.net networking code (analogous to java.net)
lapisx.swing
 auxilliary UI classes (analogous to javax.swing)
lapisx.util
 auxilliary classes that didn't fit anywhere else (analogous to java.util)
lapisx.enum helpful Enumeration implementations.  Enumeration is a Java iteration interface that predates Iterator.  The classes in this package should eventually be phased out and replaced by Iterator implementations.
lapisx.sort various sort algorithms.  These classes predate the Java Collections API, and should eventually be phased out.  For new code, you should use java.util.Collections.sort() instead.
lapisx.progress progress generators and observers, used to implement progress bars.
lapisx.progress.swing Swing-specific code for lapisx.progress


Package Dependency Rules

We want LAPIS to be independent of AWT/Swing as much as possible, so that we can write new frontends in the future (e.g. lapis.mozilla, lapis.eclipse, lapis.emacs). 

We also want LAPIS to be independent of the scripting language interpreter, so that we can substitute others (e.g. lapis.python). 

Finally, we want the lapisx packages to be independent of the rest of LAPIS, so that we can reuse lapisx classes in other Java projects without having to drag in all of LAPIS.

So the basic rules are:

Don't Use System.out or System.err; use Debug instead

Use lapisx.util.Debug for all your debugging output.  Don't use System.out or System.err, because people working on other parts of LAPIS shouldn't have to see your debugging output unless they need to.  Don't just tell yourself, "I'll only use System.err temporarily while I'm finding this bug, then I'll comment out or delete all the output statements before I commit to CVS."  That's a dumb idea for two reasons -- first, you'll forget to remove the output statements; and second, if the output statements were useful to you once, they may be useful to you again for a different bug.  There's no point in inserting them and removing them repeatedly.

The Debug class provides a systematic way to enable and disable debugging output on a class-by-class basis.  The default debug level, QUIET, doesn't print anything but exception stack traces and assertion failures.  With a command-line switch, you can tell LAPIS to switch debugging for the classes you care about to the VERBOSE debug level.

Read the documentation for lapisx.util.Debug to learn how to use it.


LAPIS Should Support Java 1.4

We don't want to force users to upgrade Java unnecessarily, so limit yourself to features of Java that are supported on Java 1.4.