Basic usage in Emacs/XEmacs

The GNU Emacs and the XEmacs text editors are supported user interfaces. At least version 22 is required for Emacs and version 21 is required for XEmacs.

Refactoring is performed by an Erlang server process, which stores analysed source files in a database. This server is started automatically by the (X)Emacs interface, and it should be stopped manually before leaving (X)Emacs. Only those files that are loaded into the database are subjects to refactoring.

Configuration in XEmacs/Emacs

Loading RefactorErl

First of all, you need to load the RefactorErl library into XEmacs or into Emacs. You can do this by placing the following two lines into your .xemacs/init.el le in the former or into your .emacs file in the latter case (you can copy&paste it from the README.TXT file from the RefactorErl package):

(add-to-list 'load-path
"/path-to-root-dir/lib/referl_ui/emacs")
(require 'refactorerl)

If you don't know where your .emacs file is, the easiest way to locate it is to start Emacs and type C-x C-f ~/.emacs - this always opens the right file. Similar in XEmacs type C-x C-f ~/.xemacs/init.el

If you don't know what C-x C-f is, then you should read the (X)Emacs tutorial to get more familiar with the environment - you can access it by starting (X)Emacs and pressing the keys Ctrl+h, and then t.

Basic settings

Before you can run RefactorErl, you must make some settings through the Emacs customization system.

Type M-x customize-group, then enter refactorerl as the name of the group. Here you can change the following settings:

• Refactorerl Base Path: you must enter the full path to the root directory of the tool. Strictly speaking, this is the only required customization, every other setting has a sensible default.

• Refactorerl Erlang Runtime: if your PATH setting doesn't contain the Erlang commands, then you should enter the full path to the erl command here.

• Refactorerl Data Dir: you can change the location of the database here.

• Refactorerl Server Type: if you want to experiment with the command line interface of the tool, you should set this to "Managed server with shell access". This feature requires the standard Erlang editing mode.

• Refactorerl Sname Type: if you run RefactorErl within Emacs, you have to use Short name. Otherwise it has to match with the name convention of the RefactorErl server.

• RefactorErl Server Name: this field has to match with the RefactorErl server. If you run the tool within Emacs, use the default value value.

• RefactorErl Client Name: if you want to run more than one Emacs instance to use the same RefactorErl server, here you can set distinct names for them.

• RefactorErl Db Type: here you can choose the database type RefactorErl uses. Mnesia always works. If you use external server outside Emacs, it has no relevance which one you choose, so prefer Mnesia.

RefactorErl mode

Refactoring functionality is provided through an (X)Emacs minor mode1 that can be turned on using the command M-x refactorerl-mode. When this mode is active, there is a status display in the mode line that shows one of the following values:

• Refact means RefactorErl mode is active, and the file can be refactored.

• Refact:off means RefactorErl mode is active, but the file is not in the database, so it cannot be refactored.

• Refact:err means the file has some errors.

• Refact:??? means that RefactorErl mode is active, but there is no information available about the file. Normally this is shown only during processing, use the "update status" command if it doesn't go away.

When RefactorErl mode is active, functionality can be accessed through either the "Refactor" menu or keyboard shortcuts. Key sequences start with C-c C-r, and a complete list is given by C-c C-r C-h.

As a standard (X)Emacs feature, help on RefactorErl keyboard shortcuts is available by typing C-h k followed by the keyboard command itself. For example, C-h k C-c C-r r f provides help on the rename function refactoring. The same works with menus: selecting a menu item after typing C-h k gives help on the menu item.

The "Refactor" menu

Server sub-menu

Starting and stopping server

While working with Erlang files the sever process of the RefactorErl can be stopped or can be restarted if it is required. The refactoring server can be stopped by selecting the "Stop server" menu item from the "Refactor/Server" menu or typing the shortcut C-c C-r Q. The RefactorErl server can be started (or restarted) by selecting the menu item "Start server" from the "Refactor/Server" menu or typing the C-c C-r R shortcut.

Configure

Using this menu item you can modify the "Basic settings" described above.

Control buffer

Enabling refactorerl-mode in Emacs automatically starts the RefactorErl control buffer. This buffer contains some RefactorErl related functionality and settings.

Files sub-menu

Load directory

Using this item (or C-c C-r L) the whole contents of a directory can be loaded without going through the files one-by-one.

Database contents

The actual contents of the database are shown by this command (or C-c C-r C), the list is shown in the "RefactorErl File List" buffer with links to the files themselves.

Show parse errors

Selecting this item the parse errors in the database which arose while adding files to the database (parse errors for files where the indicated status is "error"). Every parse error is described in a separate row and gives information about the le which contains the actual parse error, the location in the le and context information about the error. The parse errors are listed in the "RefactorErl File List" buffer with links to the location of the error.

Draw graph

There is interface to visualise the content of the database. Choosing the "Draw graph" or typing the C-c C-r G shortcut the interface asks for a file name with extension .dot where to create the description of the database content. The tool creates the description of the graph to the given path and file, using Graphviz a graphic visualisation of the graph can be created. Note that the resulting graph may be too large for Graphviz to handle.

Reset database

With this item you can reset the content of the entire database. It removes every loaded module, header file from the database and deletes the previously set include directories too.

Adding and dropping files

A single file can be loaded into the database by opening it, enabling RefactorErl mode for it, and using the "Add file" command (in the menu, or by the keys C-c C-r a). The "Drop file" command (C-c C-r d) removes the file from the database. When a file is modified and saved, it is automatically updated by removing and re-adding its changed forms.

Undo

Undo is supported for all refactorings except for renaming a module. In order to use it, execute "Undo (one step only)" (C-c C-r U). This restores the files to their state before the last refactoring step. This restoration includes dropping all the changes that you may have done to these files. You have been warned.

For renaming a module, the easiest way to undo the transformation is to do the inverse transformation: rename the module to its previous name.

Clustering

For details about the clustering see page ModuleFunctionClustering.

Semantic Queries

You can use the "Semantic Query" menu item to run semantic queries or you can use the shortcut C-c C-r s q. For more details about the queries see page SemanticQuery.

Refactorings

You can use the menu or shortcuts to call a refactoring. For details about the refactorings see page RefactoringSteps. The following refactorings are available in version 0.9.12.01 of RefactorErl.

Transformation name	Selection	Shortcut
Rename function	Def, call	C-c C-r r f
Rename header	In module	C-c C-r r h
Rename macro	Def, use	C-c C-r r c
Rename module	In module	C-c C-r r m
Rename record field	Def	C-c C-r r r f
Rename record	Def	C-c C-r r r d
Rename variable	Def, use	C-c C-r r v
Move function	Pop-up	C-c C-r m f
Move macro	Pop-up	C-c C-r m m
Move record	Pop-up	C-c C-r m r
Eliminate function call	Function call	C-c C-r e f
Eliminate fun expression	Fun expression	C-c C-r e u
Eliminate variable	Occurrence	C-c C-r e v
Eliminate macro substitution	Substitution	C-c C-r e m
Introduce function	Expression, body	C-c C-r i f
Introduce import	Qualifier	C-c C-r i i
Introduce function argument	Expression	C-c C-r i a
Introduce record	Tuple	C-c C-r i r
Introduce tuple	Def, call	C-c C-r i t
Introduce variable	Expression	C-c C-r i v
Transform list comprehension	Expression	C-c C-r t l
Reorder function parameters	Def, call	C-c C-r o f
Upgrade interface: regexp	Anywhere	C-c C-r u i r