Back

Percolator beta3

Introduction

For those who just want to get the software I've made it available in UNIX .tar.gz format and Windows .zip format. Brief installation instructions are found in the archive. Note that this is NOT a production release. The current version is hopefully free of major bugs but is feature complete.

• percolator.tar.gz (112k)
• percolator.zip (112k)

If you'd like to be placed on a mailing list which announces when new versions are released just send me mail.

For a list of what's new in beta3 check out the ChangeLog.

The following text is taken from the README in the archive.

What is it?

I am writing Percolator as part of my Masters degree requirements. It could best be defined as a Java source code pretty printer but its abilities go beyond that of simple code formatting.

Percolator can ONLY be used on syntactically correct Java source. In other words, if javac won't compile it, Percolator won't like it. Percolator has been tested with the JDK 1.1.3 on both Solaris and Win32. Percolator can view both Java 1.0 and Java 1.1 source files.

Who would want to use it?

Users of Percolator fall into two categories. Firstly, there are those who commonly read and try to understand third party source code (for business, interest, whatever) and are frustrated by the often vastly differing styles of coding not just between themselves and the code they are reading but by all the different authors out there. Nothing makes understanding code mode difficult than a poor style. Of course, the definition of a poor coding style is subjective; I'm sure the author didn't think his style was poor! Nevertheless, differing coding styles present a hurdle to code understanding. Percolator for these people is a source code browser which will preformat the source code, among other things (see below), before viewing. Since all source is now presented in a common style, it is much easier for the viewer to understand the control flow, etc. based on formatting cues.

Secondly, there are those who want to consolidate source code from different authors (or even the same author if the style of said author tends to fluctuate) into a single style, perhaps in anticipation of source code distribution. For them Percolator is simply a filter of Java source (hence its name).

What can it do?

Beyond the source code formatting capabilities, Percolator can perform the following operations on the source code:

• Expand the import statements of a source file, removing all .* references and replacing them with fully qualified import statements for ONLY those classes used in the source file. This allows the viewer to see at a glance all classes which the source file uses, rather than having to guess at which classes from the java.awt package, for example, the program uses. Percolator will always sort the import statements of a source file alphabetically regardless of whether or not this expansion option is selected.
• Fully qualify all class name references in the source code. Consider a third-party collection package which implements a List class to represent a linked list. Now consider a source file which uses said List class. First time viewers of the source may (logically) conclude, when they see the List reference buried in the source, that it refers to java.awt.List. This option will replace all class references with their fully qualified name. For example, any uses of "Vector" in the source will be replaced by "java.util.Vector" (assuming of course that Vector was imported from java.util!). By default, Percolator will not expand the classes in java.lang, but this option can be enabled.
• Sorting and grouping of nested top-level classes, member classes, initializers (no sorting allowed), static fields, static methods, constructors, methods implementing interfaces, instance fields and instance methods. Find fields and methods quickly.
• Insertion of comments for interfaces and overridden methods. Grouped interface implementation methods are grouped, sorted and prepended with a comment detailing which interface is being implemented by the following methods. As well, any method which overrides a method in an ancestor class can be prepended with a comment detailing the method signature and in which ancestor class the same method was defined (ie. the method called when "super" is issued within the new method).

What can you do?

I am releasing Percolator in its current form to solicit comments, suggestions and criticisms. The formatting style that Percolator performs is obviously very close to my own natural coding style. I realize that this may be quite different from other people's coding styles. I would like such people to respond with what options they would like to be included in Percolator so that the output comes closer to their preferred style. Non-style related features requests also appreciated.

Send all feedback to: Jean-Guy Speton speton@cs.orst.edu.

Since 08/01/97: