This guide is intended as a roadmap for those who wish to extend Transmogrify with new refactorings, support a new IDE, or use the symbol table (Thaumaturge) package to produce new code analysis tools. If you would like to contribute your extensions/changes, see this. This guide consists of the following sections:

• The symbol table and AST
• The refactoring framework
• The Hook interface
• Building Transmogrify

The meat of Transmogrify lies in the construction and analysis an Abstract Syntax Table (AST) to link definitions with their various references.

This is accomplished in four steps:

• Source is parsed and translated into an AST. For this purpose you need a parser and lexer, and rather than write our own, we used ANTLR written by Terence Parr.
• An initial walk of the tree is performed wherein scopes are created and their spans (the line and columns over which scopes exist) are calculated. In addition, definitions are created for every class, variable, and method encountered.
• The definitions of classes and methods are "finished". i.e. the throws clauses of methods, the extends and implements clauses of classes, import statements, method signatures, and method return types are all resolved.
• All references are resolved. The work of the previous step completes all knowledge the symbol table has about definitions, and this allows the symbol table to determine what each non-definition token is referring to.

Now that the construction of the symbol table is complete, the symbol table knows (if we have done the above steps correctly) what the defintion of every symbol in the codebase is. This means that at the very least, the system can be used as reference finder/counter, but the fact that we also still have the AST means that we can do just about any kind of code analysis and manipulation imagineable.

• a lint tool
• call graph creation
• find functions that don't get called
• find variables that aren't used
• wrap a block of code in an appropriate try/catch expression
• an HTML source browser (display source code with hyperlinks to definitions)
• create UML diagrams
• a javadoc stub generator

It is recommended that you first read and understand the section on the symbol table before continuing.

Now that we have the symbol table and corresponding AST, its time to put it to good use. Our first use is a refactoring tool. For a discussion of its capabilities, see this.

The system has been designed to make development of a new refactoring (relatively) easy. In general, the refactorings are done by getting the cursor position from the IDE via Hook, determining what symbol the cursor points at, and doing various pieces of analysis and AST manipulation. When the refactoring is complete, the resulting AST is streamed to disk. The key here is that the code is changed via manipulation of the AST. Once the symbol at the cursor (or symbols in the selection) have been determined, no other interaction with the source file is necessary. AST nodes are pruned, added, and changed in memory. When you implement your own refactoring, it is important that you use the manipulation functions contained in Refactorer the system knows which files have ASTs that have been changed.

The Hook interface

If you want to plug Transmogrify into a different pure-java IDE, all you have to do is extend Hook and implement the abstract methods according to the IDEs plug-in architecture. The IDE must have a few things exposed in its plug-in architecture, but we feel these are fairly standard.

• cursor position
• position of beginning and end of the selection
• current file
• files in a project

Setup

It doesn't really matter how you build Transmogrify, but we use Ant so I'll describe that build process here.

First you will need to get Ant from http://jakarta.apache.org/ant/ and install it. You'll probably want to read the Installation notes in the Ant user's guide to learn how to set up your environment appropriately.

You'll also need a JAXP compliant parser. Xerces is a good one, though any will do. See http://xml.apache.org/xerces-j/ for information about Xerces.

Building

In your project directory, run the following from the command line:

> ant

Testing

In your project directory, run the following:

> run-tests net.sourceforge.transmogrify.refactorer.test.AllTests

Making the javadoc

To build the javadocs, run the following in your project directory:

> ant javadoc

Note: Code changes frequently, so only the most central classes and functions will produce javadoc. In addition, it may be out of date because people who modify functions are, in general, unlikely to also modify the javadoc.

Displaying the AST

Looking at the AST is often helpful for debugging and writing new refactorings. To see it, run the following in your project directory:

> run-tests net.sourceforge.transmogrify.symtab.Main filesToParse

where filesToParse is a space delimited list of files or directories to parse. Specifying a directory will parse all .java files in that directory, as well as recursively descend into subdirectories.

Determining resolution coverage

Transmogrify is a work in progress, and as such isn't guaranteed to cover all the esotera of Java just yet. To see if your source code contains expressions Transmogrify can't handle, run the following in your project directory:

> run-tests net.sourceforge.transmogrify.symtab.ReferenceCounter filesToParse

where filesToParse is a space delimited list of files or directories to parse. Specifying a directory will parse all .java files in that directory, as well as recursively descend into subdirectories.