Refactoring Browser

For the latest information on the Refactoring Browser see the HyperNews page.

The Refactoring Browser is an advanced browser for VisualWorks, VisualWorks/ENVY, and IBM Smalltalk. It includes all the features of the standard browsers plus several enhancements. Some of its enhancements are:

Buffers: You can edit many methods at the same time without opening other browsers. For example, while you are editing one method, you can switch to a new buffer to lookup some value in another method, and then return back to your edited method without opening a new browser.
Drag & drop: You can drag & drop methods on classes or protocols; protocols on other classes or on protocols; classes on other categories; and categories on other categories.
Hierarchy: You can easily switch between a hierarchy view and the normal category view without spawning a hierarchy view window. This picture shows the hierarchy view on the `VisualLauncher` class. Also, it shows a resource viewer displaying an icon.
Lint: Automatically look for over 60 types of common Smalltalk bugs in your program.
Menus: The browser has window menus, so you can use the short-cut keys for selecting items from the menu and rely less on the mouse.
Multi-window: You can have many different code tools in different windows with only one navigator controlling them. In this mode, only the top most code tool will be updated when you change the navigators selection. If you want to use the multi-window browser, see the customization section below.
Old methods: No more accidentally accepting changed methods. Whenever you change a method in one window, all other browsers viewing the methods will turn their code tools red until you update their code or accept the method. If you do not like the color selection, you can change it in `BrowserCodeTool>>modifiedTextColor`.
Refactorings: Automatically perform some behavior preserving transformations such as abstracting references to an instance variable. Many of the refactorings are from Bill Opdyke's thesis.
Resource viewers: View resource methods in their more natural look instead of text. For example, a menu resource method appears as menu, not as text, although you can switch to a textual view if you want. This picture shows a canvas viewer viewing the `ClassNavigator>windowSpec` method.
Rewrite tool: Specify new rules to make source to source transformations. For example, you can create a rule to automatically convert uses of "aCollection size == 0" to be "aCollection isEmpty". Documentation for the rewrite tool can be found on this page.
Undo support: The Refactoring Browser can undo/redo refactorings, method changes, and class changes. The class variable, UndoSize, in RefactoringManager specifies the number of undos that can be undone. The default size is 5.

The icons signify that the feature is not implemented for IBM Smalltalk.

Installation:

To install the browser in an ENVY environment, you need to decompress the ENVY-Browser.zip file to create the Browser.dat file. Once you have done this, you'll first import the "Refactoring Browser" configuration map for the browser into ENVY and then load the config map for the browser.

If you are using VisualWorks 3.0 without ENVY, you need to download VW30-Parcels.zip. After downloading, simply unzip the file into a parcel directory and load the RefactoringBrowser parcel. You might need to edit your parcel path so that the RefactoringBrowser parcel that was sent with VisualWorks isn't loaded instead of this one (or you could just remove the RefactoringBrowser parcel from the goodies/other directory).

If you are using VW2.5 without ENVY, you can download a previous version of the browser.

Joseph Pelrine has ported the refactorings from the Refactoring Browser to VSE. You can download them from ftp://st.cs.uiuc.edu/Smalltalk/STV/st_v/v_win32/refbrwsr/.

If you have problems using any of the ftp://st.cs.uiuc.edu links above, then your machine probably doesn't allow reverse DNS. In this case you can download the files by replacing ftp://st.cs.uiuc.edu with http://st-www.cs.uiuc.edu/ftp/. Also, you could use one of the mirror sites.

If you wish to see what has changed between the versions, you can look at the fixes file.

Other Refactoring Information:

Patrick Ryan has been working on some enhancements to the Refactoring Browser for ENVY.
There is a refactoring@cs.uiuc.edu mailing list for the Refactoring Browser and general refactoring information. You can subscribe by using this form or by sending email to refactoring-request@cs.uiuc.edu with the SUBJECT of "subscribe".
There is a HyperNews page for discussing Refactoring Browser issues, problems, etc.
The slides from Smalltalk Solutions '99 have been translated into html documents.
Various slides on the browser architecture, Smalllint, and the rewrite tool.
A Refactoring Tool for Smalltalk. published in Theory and Practice of Object Systems special issue on software reengineering.
Other papers on refactoring can be found on the Smalltalk ftp site.

User instructions:

To open the refactoring browser select the button or evaluate "RefactoringBrowser open". If you're using ENVY, then you can select the "RefactoringBrowser" from the ENVY menu in the launcher. This will open a window that is similar to this picture.

Common Questions & Answers:

What does the ____ refactoring do?

This page contains a description of the refactorings.
Is there a Java (or C++) version?

We do not have and are not currently working on a Java version. While a Java version is definitely needed, we have other things we need to do (e.g., get our degrees). However, given the right incentive (i.e., $$$), we could implement a Java version.
How can I tell what version of the Refactoring Browser I currently have?

If you are using ENVY, then you can simply look at the version number of the Refactoring Browser configuration map. It should be something like R3.0.0. If you are using the parceled version of the Refactoring Browser, you can look at the parcel versions. Finally, if you are using the non-ENVY VW2.5, you can look at the RefactoringBrowser class. It contains two class variables (Version & PatchLevel). By concatenating these two numbers together, you can get the overall version number.
I've found a bug, how should I report it?

The first thing you should do is to determine that you are running the latest version of the browser (see previous question). After seeing that you have the latest version, please try to find a simple reproduceable case that you can post to the HyperNews page. If you cannot find a reproduceable case, you can still post the problem (it will just be harder for us to find the problem). It is your responsibility to report the bugs (since we don't charge anything for the browser, you should atleast be able to report bugs). We cannot fix any problems that we don't know about.
Is there a port for GemStone?

No, we don't have GemStone on our machines, so it would be difficult for us to create one. If someone creates a version, we would be happy to include it.
Can I only rename methods in my application; not the whole image?

Currently, the Refactoring Browser renames everything when performing a renaming refactoring. Since we cannot determine which implementors of a method are polymorphic, we must rename everything (else we might miss some senders). In the future, we may relax this restriction to allow you to specify which ones to rename.
If you are using ENVY, then you may want to follow the suggestion by Niall Ross.
Does the Refactoring Browser have to format a method when it changes the method by a refactoring?

The Refactoring Browser uses parse tree to perform its transformations on. Since parse tree are used, it is easiest to just have the parse tree to format themselves whenever they are changed. It is definitely possible to not have to reformat for every change. However, this has not been implemented and is not a high priority for us. Therefore, either some user can implement it themselves, or we would be open to implementing it if someone is willing to pay for it.
What are the BR prefixes for?

The BR prefix stands for Brant & Roberts. Only after being questioned about the prefixes did we realize that it should have been RB (which works for both Refactoring Browser and Roberts & Brant).
How does the Refactoring Browser determine if a class is abstract?

Smalltalk doesn't have any language feature that denotes an abstract class like C++ or Java. As a result, we check for a couple things when looking for an abstract class. If the class contains any method that sends #subclassResponsibility, the we consider the class as abstract. A method that sends subclassResponsibility signifies that users should override this method in every subclass to have all the class' functionality to work. Another check we use to determine if a class is abstract is to look for references to the class. If the class is not referenced then the class is considered to be abstract, since there is no way to create an instance of the class.
Why does the Refactoring Browser care if a class is abstract?

The Refactoring Browser can only perform some refactorings if the class is abstract. For example, it can only push a method down if it can determine that the method can never be called on the class that the method is being pushed out of.
Are there any restrictions on the Refactoring Browser's code (e.g., GNU copyleft)?

We don't have any restrictions on the code. You are free to use it for what ever you want. However, we do request two things if you use or modify the code. If you modify the browser, please submit your changes back to us. We will try to integrate your changes back into the browser. The other request is that if you use the code in some project, we would appreciate some recognition of its use (e.g., an acknowledgement in a readme file). It is always pleasing to see your code running in several different applications.
While we don't expect any major problems, we assume no responsibility for any damages it may cause. We've been using it for over three years without any major problems. If you find any problems, please send us a description so that it won't happen to others.

Customization:

The new browser was designed to be extensible and customizable. There are several methods that you can modify and/or execute to change its behavior.

Multi-window support: You can change the browser so that each code tool is opened in a new window, instead of creating buffers for each tool. To change the browser to be multi-window evaluate "`RefactoringBrowser beMultiWindow`", and to change it back to single window mode evaluate "`RefactoringBrowser beSingleWindow`". Once you evaluate either selection, you must open a new browser.
Vertical navigators: You can change the navigator from it's default horizontal position to a vertical one by evaluating "`RefactoringBrowser beVertical`" and switch it back to horizontal by evaluating "`RefactoringBrowser beHorizontal`".
Resource editors: You can change the editor and/or viewer for a resource (menus, canvases, etc.) by changing `ResourceTool>initialize` method. For example, to change the menu editor, so that the new VisualWorks 2.5 enhanced menu editor is opened, change `UIMenuEditor` to `MenuEditor`, and then re-initialize the `ResourceTool` class.
Code tools: You can create a new code tool and add it to the browser by modifying the `CodeModel>codeToolClass` method. This method determines which code tool is used for the navigator's selection. Code tools can be created by creating a subclass of `CodeTool`, defining its interface functions, and defining the `updateContents` method. The `updateContents` message is sent to the code tool so that the code tool can stay current with the navigator's selection.

Bugs/Limitations:

This section lists the known bugs and their work arounds (if they exist). If you know of a bug that is not listed in this section, please mail us. If we know of the bug, we might fix it, but we can't fix bugs that we don't know about .

Undo convert to instance variable: The VA version will not undo the convert to instance variable refactoring, since the inverse operations can't be performed in reverse.
Class Variables in VisualWorks ENVY: The Class>>removeClassVarName: in VisualWorks ENVY has a bug in that it doesn't remove the class variable. This bug affects the push up/down class variable, remove class variable, and rename class variable refactorings. For the rename class variable refactoring, the code will be transformed, but the renamed variable will not be removed. One fix for the problem is to change the code in Class>>removeClassVarName: from:

	self classVarNames asOrderedCollection
			remove: existingClassVarName asString ifAbsent:[];
			yourself

to:

	self classVarNames asOrderedCollection
			remove: existingClassVarName asSymbol ifAbsent:[];
			yourself

Since class variables are symbols in VisualWorks, the "existingClassVarName asString" will never be found as a class variable name.

Spawn hierarchy: If you add a new class in a "spawned hierarchy" browser, you may not be able to see the new protocols that you add for the new class.
Drag & Drop: If you drag a selection from the browser that has multiple categories or protocols selected and drop it on the original VisualWorks browser icon, you can generate exceptions if the first class/method selected is not in the first category/protocol selected.
Symbol References: When you are "safe removing" a class and there are references, the option to browse the references doesn't not browse the indirect references through symbols.
Comments in extracted code: When extracting code, the comments in that are in the extracted code, will appear both in the method that was extracted as well as the method it was extracted from.
Spawn browser: When you select spawn browser from the editor for the "Missing subclassResponsibility" lint rule, you will get a doesNotUnderstand: error. This does not affect any of the other browsers or lint rule editors, only the missing subclassResponsibility rule.
Dialog: When you open a browser and there are no methods for it to inspect, it will open a dialog saying "Nobody". If there are no active controllers, then it will fail with a doesNotUnderstand: message. You can either terminate this process, or open the debugger and restart the method.
Slow response: When running the multi-window browser under Motif (maybe other unix window managers?), it may take longer to update the window. Since only the top most window is updated after a change, the program must get the stacked window order from a primitive. While this primitive is fast on MS-Windows, it is slow under Motif so the resulting update is slow for Motif. If you have a better way to get the stacked order of the windows, please mail us.
Slow dialog close: When running VisualWorks 2.5 with the events file-in, the dialog warning takes longer to close after the close button is pressed. This is probably a bug in VisualWorks 2.5 events code.
Menu bug: When running VisualWorks 2.5 with the events file in, the pop-up menu automatically select the first item that has a submenu instead of the top-most item. Again, this is probably a bug in VisualWorks 2.5 event code.
File out: Selecting file out from the category, class or protocol menu will file out all methods for the selection, instead of filing out only the methods that you are browsing. For example, if you spawn class Object and then select file out from the category menu, you will file out all classes in the Kernel-Objects category instead of just Object.

Comments or suggestions can be sent to brant@cs.uiuc.edu and droberts@cs.uiuc.edu.
Last updated on 18-Jul-1999.