| ### The Reform (Pretty Printing) Tool

Reform is a tool that formats .java and .jak files to produce prettier versions of these files according to a uniform format specified by users. This document discusses detailed use and features of Reform.

- Reform features
  - Indentation
  - Parenthesis Style
  - Brace Style
  - Comments Processing
- Architecture
- Command-line options

## Reform features

Features of Reform include indentation, parenthesis style transformation, brace style transformation and comments processing.

### Indentation

The tool will determine places in source files where indentations are needed and generate a Tab indent for each place. Users can specify the desired tabular size of the source code to process with command-line options, and each Tab indent will be replaced with the specified number of white spaces. (Our experiences have indicated that around 4 spaces for indentation is optimal)

public class Preferences {
--->//~ Constructors ............................................................
--->private Preferences() {}
--->//~ Methods .................................................................
--->public static void main( String[] args ) {
------->int s;
------->for (int i=1; i<10; i++) {
----------->s += i;
------->}
.................................................................
--->}
}

### Parenthesis Style

This feature applies to parentheses in expressions and method invocations. One white space will be inserted after an open parenthesis and before a close parenthesis.

n = a * ( b + c );

String s = line.substring( i, i+2 );

Foo aFoo = new Foo();

### Brace Style

This feature controls how the enclosing block delimeters - opening and closing curly brace - are printed. It uses the Sun indent style.

if ( !isDone ) {
doSomething();
}
else {
System.err.println( "Finished" );
}

### Comments Processing

Comments have two types: stand-alone comments which takes one or more lines or in-line (or end-of-the-line) comments. For in-line comments, the tool will keep them unchanged; for stand-alone comments, the toll will align them up to the corresponding code segments.

--->// calculate Method
--->// this method calculates the sum of
--->// first n positive integers
--->public int calculate( int n ) {
------->int sum = 0;
------->// test if n is less than 1;
------->// if so return immediately
------->if ( n < 1 )
----------->return sum;
------->for (int i=1; i<=n; i++) { //loop from 1 to n
----------->sum += i;
------->}
------->return sum;
--->}

JavaDoc comments, which are stand-alone comments, are comments that start with "/**" and end with "*/". If layer-name (-n) option is set (see command-line options), the tool will detect JavaDoc comments and augment it with @layer<layer-name> decoration, if such a decoration does not exist already. For example,

/** ...........
* ...........
*/

will be re-written as

/** ...........
* ...........
*@layer<layer-name>
*/

## Architecture

Reform is written in a layered-structure. Since the tool must handle source files of different grammars, a layer is constructed for each grammar. Besides these grammar-specific layers, the tool also contain a non grammar-specific layer to perform some common tasks.

- Non grammar-specific layer
  - FormatBase: establishes the framework of the tool and handles tasks that are common to all grammars, e.g. command line argument processing
- Grammar-specific layers
  - FormatJava: specifies actions for formatting Java grammar code
  - FormatAst: specifies actions for formatting ast grammar code
  - FormatGscope: specifies actions for formatting gscope grammar code
  - FormatAhead: specifies actions for formatting Ahead grammar code
  - FormatSource: specifies actions for formatting Source grammar code
  - FormatLocalId: specifies actions for formatting LocalId grammar code
  - FormatLayer: specifies actions for formatting Layer grammar code
  - FormatSm: specifies actions for formatting Sm grammar code
  - FormatClassX: specifies actions for formatting ClassX grammar code
  - FormatIntX: specifies actions for formatting IntX grammar code
  - FormatSmX: specifies actions for formatting SmX grammar code

All these layers must sit above kernel, Java and Comments layers which are part of the existing JTS system. The following graph shows the architecture of FormatTool:

## Command-line options

To call Reform from the command line:

>     > java Reform.Main [-t number] [-l number] [-n string] [-s] [-verbose] [-quiet]  <list of 1 or more files to format>

or

        > java Reform.Main [-t number] [-l number] [-n string] [-s] [-verbose] [-quiet] -d directory -e extension

where:

- option -t : number of white spaces for a Tab
- option -l : maximum number of consecutive white lines in the program
- option -n : layer name to be added into JavaDoc comments
- option -s : safe mode - prompt before replacing file archives
- option -verbose : enables verbose output (default)
- option -quiet : disables verbose output
- option -d : source directory to be RECURSIVELY searched; will void source file argument(s)
- option -e : source file extension to be searched; will void source file argument(s)

The tool will format the list of given files and backup old (un-formatted) copies by appending ~ to the end of the file names. For example, if a file is named Foo.jak, the tool will save its old copy as Foo.Jak~

While formatting a file, if the tool finds its backup copy under the same directory, it will force replacing the backup (when -f option is set) or ask the user whether to skip the file (when -f option is not set).

ATS Home Page

Copyright © Software Systems Generator Research Group. All rights reserved.
Revised: January 25, 2006.