= 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}}}.[[BR]]

 
=== 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.

==== Starting and stopping metric mode ====

The RefactorErl supports querying bad smells in the code. 

The metric analyser mode has to be manually enabled  by selecting Start metrics from the Server item in the RefactorErl menu in the Emacs interface of RefactorErl. Clicking Start metrics from the same menu turns the mode off. When Metrics mode is on, the status indicator displays Erlang Refact Metrics or a similar message. 

When in metric analyser mode, the Emacs interface of RefactorErl displays the values of changed metrics after a transformation is invoked. The analyser opens up the Metrics Result buffer, and shows the expected and the current values of the measured metrics for all modules that have at least one metric that is out of bounds.
Values of metrics outside the user defined limits (”bad code smells”) can also be queried manually using Show bad smells in the Semantic query menu. 

==== 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 ===

For details about the undo function see page EmacsInterface/Undo.

=== 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 [wiki:SemanticQuery].

You can ask for a list of running queries (with their name and Query Id) using 
"Running queries" menu item (shortcut: {{{C-c C-r s r}}}).It is also possible to 
kill/stop a query with a specific Query ID using "Kill running query" (shortcut: {{{C-c C-r s k}}}). 

You can also run metric queries (Run metric query, shortcut: {{{C-c C-r m q}}}) 
from "Semantic Query" menu or ask for the list of bad smalls found in the code 
(Show bad smells, shortcut: {{{C-c C-r s b}}}). See the following page for 
further information: [wiki:MetricQuery].

Other menu items available from "Semantic Query": Go to definition (jump to the
definition of the function, shortcut: {{{M-.}}}) and Find function references
(shortcut: {{{C-c C-r q r}}}).

=== Dependency analysis ===

There are three available types of dependency analysis in RefactorErl: module, function and
function block dependency analysis. For details check the following page: wiki:Dependency.

If you would like to get information about dependencies between modules or functions, use
the menu "Module and function dependencies". The parameters are similar to the ones described
here: wiki:Dependency.

To gather information about module group and function block dependencies, you should use menu
group titled  "Function block dependency analysis". It contains a submenu named "Default FB
analysis" where you can start the analysis itself and set its options (see wiki:Dependency),
and another submenu called "Define FBs with regexps" where it is possible to define module
groups using regular expressions.

=== Duplicated code analysis ===

After starting the Emacs with refactorerl-mode on, the duplicate code analysis is available under the Refactor / Duplicated code analysis menu. (You can learn more about this topic and about the usage on CloneIdentifiErl page, whilst the services provided by this interface are detailed below.)

To fine-tune the algorithm select the advanced search option. At first, an algorithm should be chosen.

[[Image(emacs_alg_choose.png)]]

After the algorithm has been chosen the parameters of the algorithm can be set (it is not necessary to set every parameter). The analysis can be started by clicking on the Run button.

[[Image(emacs_alg_param.png)]]

After the analysis have finished, a clone group belonging to the result can be selected. 

[[Image(emacs_results.png)]]

In this case the first two instances belonging to this group will be shown in separate two columns. The mechanism is similar to the behaviour of diff applications.  You can switch between instances from this group by using dropdown lists that are placed above the columns.

[[Image(1result.png)]]

==== Load previously saved result ==== 

After the show duplicates menu item has been chosen, a previously saved result can browsed by entering the name of the previously saved duplicated code result.

==== Search duplicate code by selection ==== 

It is possible to make a selection in the source code and start the duplicate code analysis by choosing the search in selected area in the Duplicated code analysis menu. This will start the {{{matrix}}} algorithm which will search for duplicates of the selection.


=== Refactorings ===

You can use the menu or shortcuts to call a refactoring. For details aboutthe 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}}} ||