[[PageOutline]]
= Disclaimer
The currently available !RefactorErl plugin for Eclipse is an operational first prototype of the proposed tool. Most features are to be improved in future versions, the [#planned corresponding section] lists some of these improvements. Questions, suggestions, bug reports, feature requests and any other kind of well-intentioned feedback [https://plc.inf.elte.hu/erlang/refactorerl-contact.html sent to our team] are all welcome.

= Introduction
Most services provided by !RefactorErl are accessible from the Eclipse IDE after installing the !RefactorErl plugin in Eclipse. In this guide, we also refer to this plugin as the //Eclipse interface//. 
The following functionalities are available from the Eclipse interface:
* [#db Database management]
* [#sq Semantic queries]
* [#ref Refactoring]
* [#dep Dependency graph drawing]
* [#dup Duplicated code analysis]
* [#inv Code investigations]

A short description for each functionality can be found at the beginning of the relevant sections. 

While not required, it's recommended to install [http://www.erlide.org the Erlide plugin] in Eclipse. Erlide enhances features of the !RefactorErl plugin and transforms Eclipse into a complete Erlang IDE.

A short list of frequently experienced problems relating to the installation can be found in the [#troubleshooting troubleshooting] section.

[=#install]
= Installation
== Quick summary
1. Install the [#instdep dependencies].
1. To [#pluginst install the RefactorErl plugin in Eclipse], click on the **Help > Install new software** buttons in the Eclipse menu, click **Add...** in the appearing window, and paste the following link in the **Location** text field of the window named **Add Repository**: http://plc.inf.elte.hu/erlang/dl/update/
1. [#firsttime After the installation], navigate to the preference pages by clicking **Window > Preferences > !RefactorErl**, and fill in the **!RefactorErl Base Directory** field with the path to the base directory of a locally installed !RefactorErl application. In case you would like to connect to a remotely located !RefactorErl node instead, fill in the node address of this node in the **Server address** field.

[=#instdep]
== Dependencies
* GNU/Linux, or Windows (with MinGW-W64) operating system. (Mac OSX was not tested.)
* Java 7 JRE/JDK or newer. (Tested with Oracle and OpenJDK).
* Eclipse 4.4.0 Luna or newer.
* !RefactorErl 0.9.14.09 or newer. (Not needed in case a remote !RefactorErl node is available.)
* //GraphViz (Optional. Needed for displaying dependency graphs in SVG.)//
* //Igraph (Optional. Decreases runtime of duplicated code analysis.)//
{{{#!comment
* //GEF4/Zest 2.0 Eclipse plugin (Optional. Needed for drawing Zest graphical representations of dependency graphs.)//
}}}
* //Erlide 0.29 or newer (Optional. Enhances features of the !RefactorErl plugin.)//

=== Operating systems
Any operating system running Eclipse and !RefactorErl should also be able to run the !RefactorErl plugin for Eclipse, but slight differences in systems can cause unpleasant surprises. The !RefactorErl Eclipse plugin was tested and run successfully on the following configurations:
* GNU/Linux Ubuntu 14.04, 32-bit.
* GNU/Linux Ubuntu 14.04, 64-bit.
* Windows 7 SP1, 64-bit. Tested with MinGW-W64 (native, 4.9.2, x86_64, posix, seh, revision 2) found at http://mingw-w64.yaxm.org/doku.php/download#mingw-builds

Other operating systems may be able to run the !RefactorErl plugin, but were not tested.

=== Java 7 & Eclipse 4.4.0
Please see the developers' site for instructions concerning the obtainment and installation of [https://www.oracle.com/java/ Java] and [https://www.eclipse.org/ Eclipse].

=== !RefactorErl
{{{#!comment
On Debian based systems, the most straightforward way to install !RefactorErl and its dependencies is to use the [wiki:DebInstall RefactorErl Debian Package]. 
}}}
Detailed instructions for installing !RefactorErl can be found on the [wiki:Install related wiki page]. Of the various dependencies listed in the guide, the !RefactorErl plugin depends only on the !RefactorErl base system. This means that if you do not intend to use other interfaces besides the Eclipse interface, you don't need to install any other dependencies (Yaws, Wx, ...) listed on the referenced wiki page apart from the base system. 

As a remainder, here are the steps you need to follow in order to install !RefactorErl:
1. Install Erlang from your system package manager, or from an installer provided by [https://www.erlang-solutions.com/downloads/download-erlang-otp Erlang Solutions], or you can build [http://www.erlang.org/download.html Erlang from source]. Prior to installation make sure that the version of the Erlang package to be installed is supported by !RefactorErl.
1. Download [https://plc.inf.elte.hu/erlang/ RefactorErl]. 
1. Uncompress the archive to the directory where you want !RefactorErl to reside. 
1. Enter the `refactorerl-x.y.z.v` directory you just uncompressed (here `x.y.z.v` denotes a version number). 
   Type the command `bin\referl -build tool` in a terminal window. 
   Wait for the build process to finish. If the build ends with an error, please refer to the wiki page mentioned before.
1. Test the tool by typing `bin\referl` in your terminal. If the build was succesful, an Erlang shell should appear. 

You will have to supply the location of the refactorerl-x.y.z.v directory (where we typed in the commands) to the !RefactorErl plugin after the plugin is installed into Eclipse.

=== !GraphViz
Optional. !GraphViz is used to draw SVG representations of dependency graphs. You will have to supply the location of the `dot` executable of an installed !GraphViz application the first time you use the SVG drawing feature.

Hint: On UNIX-like systems, you can use the `type -a dot` command to locate the `dot` executable on your system. 

!GraphViz can be obtained from the [http://www.graphviz.org developers' website] or presumably from the package manager of your local system.

=== Igraph
Optional. !RefactorErl can use Igraph to decrease the runtime of duplicated code analysis. For installation instructions, see [http://pnyf.inf.elte.hu/trac/refactorerl/wiki/CloneIdentifiErl#Optionalsoftwaredependencies the related section] of the wiki page on duplicated code analysis.

{{{#!comment
=== GEF4/Zest 2.0
Optional. Zest 2.0 is used to draw dynamically adjustable Zest representations of dependency graphs. 

The up-to-date version of the Zest 2.0 Eclipse plugin can be obtained from the [https://wiki.eclipse.org/GEF/GEF4 developers' website].

You can also download Zest 2.0 from the !RefactorErl update site. Just select the **GEF4/Zest 2.0** entry besides the !RefactorErl plugin entry in the list after you added the update site in Eclipse. See the [#pluginst relevant section] for more information.
Please note, that the version hosted on the !RefactorErl update site might not be up-to-date.
}}}

=== Erlide
Optional.

The up-to-date version of the Erlide Eclipse plugin can be obtained from the [http://www.erlide.org developers' website]. 

You can also download Erlide from the !RefactorErl update site. Just select the **Erlang language tools IDE** entry besides the !RefactorErl plugin entry in the list after you added the update site in Eclipse. See the [#pluginst relevant section] for more information. 
Please note, that the version hosted on the !RefactorErl update site might not be up-to-date.

[=#pluginst]
== Installing the !RefactorErl plugin in Eclipse

The !RefactorErl plugin can be installed in Eclipse via our update site. 

First copy the following link on the clipboard (eg. Right click > Copy Link Location): http://plc.inf.elte.hu/erlang/dl/update/

Open Eclipse and click on the **Help > Install new software** buttons in the Eclipse menu. 

[[Image(install-menu.png, align=center)]]

Click **Add...** in the appearing window, and paste the link we just copied to the clipboard in the **Location** text field of the window named **Add Repository**. Click OK.

[[Image(install.png, align=center)]]

In the original **Install** window select the !RefactorErl group and a list should appear, containing the plugins available from the update site we specified in the last step. 

To install the !RefactorErl plugin, select the **!RefactorErl Eclipse UI** entry. 
The list might contain additional entries for optional dependencies (Erlang language tools IDE). Installing these plugins is not required, but it will enhance some features of the !RefactorErl plugin. Please note, that the version of these dependencies hosted on the !RefactorErl update site might not be up-to-date. 
{{{
#!comment 
GEF4/Zest 2.0
}}}

After clicking **Next** on this window, Eclipse will lead you through a series of simple steps before the installation. After the installation is finished, you will need to restart Eclipse. 

To start using !RefactorErl, open the **!RefactorErl Perspective** by clicking **Window > Open Perspective > Other > !RefactorErl** in the top menu.

[=#firsttime]
== First time launch
If the plugin installation was successful in the last step, an error message will appear the first time the **!RefactorErl Perspective** is opened. This happens because we didn't set the path to !RefactorErl yet. 
{{{
#!comment 
KÉP
}}}

The !RefactorErl plugin can automatically start a local !RefactorErl application and connect to it. Please, see the corresponding section of this guide, if !RefactorErl is not yet installed on your system.
It is also possible to connect to a !RefactorErl application running on a remote server. You do not need to install !RefactorErl on your local system to do this.

Navigate to the preference pages by clicking **Window > Preferences > !RefactorErl**. 

[[Image(prefs.png, align=center)]]


In case you would like to connect to a local !RefactorErl application, fill in the **!RefactorErl Base Directory** field with the path to the base directory of a locally installed !RefactorErl application. 

In case you would like to connect to a remotely located !RefactorErl node instead, fill in the node address of this node in the **Server address** field. 

The arbitrary directory specified in the **Logs directory** field will contain the error logs. The arbitrary directory specified in **Data directory** field will contain the files (eg. graph drawings) you create with the plugin. (There is also a **!Refactorerl data directory** which will contain the files created by the !RefactorErl process. You can leave this field blank.)

Click **OK**. Click **Yes** on the dialog inquiring whether you want to reconnect to !RefactorErl. If the connection was successful, a `Connected to RefactorErl` message will appear in the left side of the status bar at the bottom of the Eclipse window. 

Congratulations, now you can start using !RefactorErl with the Eclipse interface!

= Using the !RefactorErl Eclipse interface
This section will guide you through the most important interface features. While we include a basic description for each feature group, it may be neccessary for you to read the corresponding wiki pages for an in-depth understanding of the feature group in question. 

If you open the !RefactorErl perspective or the Erlang perspective (if Erlide is installed) inside Eclipse, a new menu button, with the text **!RefactorErl** on it, will appear in the Eclipse top menu. Much of the features are accessible through the **!RefactorErl** menu, and some features can be accessed in more than one way.

For the rest of this guide we will assume that you have the !RefactorErl or the Erlang perspective opened and one of these is the active perspective. As a reminder, perspectives can be opened via the **Window > Open Perspective > Other** button in the Eclipse top menu. 

== Uninstalling the !RefactorErl plugin
The !RefactorErl plugin can be uninstalled from Eclipse like most other Eclipse plugins. 
1. Open Eclipse
1. Click on **Help > Installation Details** 
1. In the appearing window select the **!RefactorErl Eclipse UI** entry. Click on the **Uninstall** button.

[=#db]
== Database management
The !RefactorErl server uses an internal database to store syntactic and semantic information on the source code. !RefactorErl provides most of its services with the use of this information. In order for !RefactorErl to be able to analyse a source file, that source file must be added to the database. 

See the [wiki:ManagingFiles wiki page about database management] for a more detailed description of database management in !RefactorErl.

Database management features available in the Eclipse interface include: 
* Listing the source files in the database
* Showing the contents of a source file 
* Adding new source files or directories of source files 
* Dropping source files or directories
* Synchronizing the database with the (possibly modified) source files on the disk
* Synchronizing the GUI and the database in case of connection errors or other irregularities
* Appending values to the `appdata` and `include` environment variables 
* Removing previously added values from the environment variables 
* Resetting the database

You can open a view containing the list of files, called the //Database// view, by clicking **!RefactorErl > Database > Show Database** in the top menu. 

[[Image(filelist.png, width=800, align=center)]]

When you click in the //Database// view with the right mouse button, a context menu will appear, containing all database management features. Some of them, like the //drop// and //show// features, are dependent on the files or directories selected in the view.
Most database management features (the ones not depending on file selection) are also available in the **!RefactorErl > Database** menu.

Source files can also be opened by double clicking on their name in the //Database// view.

[=#sq]
== Semantic queries
!RefactorErl provides a semantic query language as a straightforward way to query the information residing in the database. See the [wiki:SemanticQuery wiki page on semantic queries] for a detailed description of this feature.

The !RefactorErl plugin for Eclipse provides an interface to
* write and execute semantic queries with autocompletion support,
* show the results of the previously executed query,
* show a history of preceding queries and their results.

Before we examine the interface, we have to note the following distinction: A semantic query can be //global// or it can be //position based//. Position based queries start with the `@` character. 
As an example `mod.funs` is a global query, because it returns all functions of all modules in the database. On the other hand `@fun.references` is a position based query, because it returns all references to the function specified by a position on the source file.

You can execute a global query by writing your query in the textfield initially with the text `Semantic query` in the Eclipse toolbar and pressing the return key. 
You can also execute global queries by clicking on **!RefactorErl > Queries > Start query**. A dialog will appear, where you can type the global query.

[[Image(autocomplete.png, align=center)]]

To execute a position based query, open the source file where you want to start the query from, and click on the desired position in the text of the file with the right mouse button. In the appearing context menu, select **Run query from position**. A dialog will appear, where you can type a position based query (or even a global query).

After a successful query execution a view, called //Query result// view will appear with the results of your query. You can double click on a line of the result, and if it's possible, an editor tab will open with the file containing the content of that line, highlighting the content in question.

[[Image(q.png, width=800, align=center)]]

The **!RefactorErl > Queries > Show query history** button will open the //Query history// view. Double clicking on a query in the //Query history// view will show a results of this query in a //Query result// view. Please note, that these are historical results, it may or may not be consistent with the current content of the database.


[=#ref]
== Refactoring
Beyond source analysis, !RefactorErl is also capable of performing code transformations, commonly known as code refactorings. 

See the [wiki:RefactoringSteps wiki page about the available refactorings] for a detailed description of this feature and a complete list of available refactorings.

Refactoring code with the Eclipse interface is easy. Just right click in an Erlang source code editor on the element you want to refactor, click on the **!Refactoring** menu and select the desired refactoring.

{{{
#!comment 
KÉP
}}}

Entries on top of the **Refactoring** menu are specific to the element you clicked. For example, **Rename function** appears (among others) when you right click on a function name, and **Rename variable** appears, when you right click on a variable. 
Entries on the bottom of the menu are always visible irrespectively of the element you clicked. They are not always valid refactorings however.

Note that while refactoring can affect more than one files (e.g. renaming a function will also change the references to this function in all files), !RefactorErl can only work on files added to the database. For this reason it's always recommended to upload the whole codebase you work with to the database, before you do any refactoring operation. 

[=#dep]
== Dependency graph drawing
!RefactorErl can create graphical graph representations of dependencies between modules, functions or groups of modules (called module blocks or function blocks). This feature is also called dependency analysis. The Eclipse interface provides means of supplying initial parameters to the analysis and also capable of showing the results inside Eclipse in various formats.

See the [wiki:Dependency wiki page about dependency analysis] for a detailed description of the available initial parameters and result formats.

To draw a dependency graph, select the **!RefactorErl > Draw dependency graph** button in the menu to open the //Dependency analysis// view tab. 

In this view, you can provide the parameters for the analysis, select output format and choose a directory to store the results for future use. Hit the **Draw dependency graph** button on top of the view tab to start the analysis. Note that this may take for a while, depending on how much data is stored in the database.

[[Image(dep_smart.jpg, width=240, align=center)]] 

[[Image(dep_svg.png, width=240, align=center)]] 

[[Image(dep_erl.png, width=240, align=center)]]
{{{
#!comment
[[Image(dep_zest.png, align=center, width=400, align=center)]]
}}}

[=#dup]
== Duplicated code analysis
!RefactorErl provides a feature to search for code duplicates, i.e. sections of code whose syntactic and semantic structure are similar in some way or another.  
This search can be conducted using different algorithms and parameterizations. See the [wiki:CloneIdentifiErl wiki page about duplicated code analysis] for the complete list of these algorithms and parameterizations.

To use this feature, click **!RefactorErl > Clone !IdentifiErl** in the top menu to open the //Clone !IdentifiErl //view. You can select an algorithm from the box on the top part of the view, and fill in the parameters in the bottom part. To start the search, click on the **Run analysis** button. Note that this may take a long time, depending on how much data is stored in the database.

[[Image(dupcode.png, width=800, align=center)]]

The results will be presented as a list of records of file positions in a view called //Duplicated code analysis results//. Double clicking on an item of that list will show the duplicated code sections side by side in a multi-pane editor.

=== Duplicate code elimination
This feature only works with duplicate searches launched with `Suffix tree (providing only relevant results)` algorithm. 

By right clicking on a record in the results view and selecting **Eliminate Group** in the context menu, you can introduce a new function in place of the duplicate group represented by the selected record. Since duplicate code elimination (and more generally, any refactoring or other kind of modifying operation) invalidates the results of former duplicate searches, all views and editors related to previous searches will be closed after a successful operation.

[=#inv]
== Code investigations
This section assumes basic understanding of writing and running semantic queries. The Eclipse !RefactorErl plugin provides an interface, called code investigations interface, to work with semantic queries in a graphical, traceable and persistable manner.   

A short and dense description of the feature:
* When you use the investigations interface, all of your queries are stored in a tree-like data structure. 
* Every node of that tree stores one query result out of all the results of some query. This result is displayed as a small code section (e.g. a body of a function), and you can start a new query, based on a position in this code section. (Of course the query will be run against the whole database, the displayed code section is just a graphical aid.) 
* For every results of this new query you selected, a new node will be created and these nodes, in turn, will be the child nodes of the original node.
* This way you build, starting from the root node, a tree, where every node corresponds to a result of a query, which was based on the result of that node's parent.
* Investigation trees can be stored and restored later. Investigations built on other !RefactorErl interfaces can also be restored in the Eclipse !RefactorErl investigations interface and vica versa. //(Current implementation of the !RefactorErl plugin has no 2D layout data, so investigations built with the plugin and restored in other !RefactorErl interfaces will have to be layed out manually.)//

To create a new investigations tree, click **!RefactorErl > Investigations > New investigation** in the top menu. In the appearing window, you can specify, with the aid of autocompletion, a name and a starting function. The root node is special in the sense, that it simply holds the code for the body of the supplied function, and not a result of a query.
Only those functions will be accepted, whose containing modules were previously added to the database.
After pressing OK, an investigation editor tab will appear.

You can list all previously created investigations by clicking **!RefactorErl > Investigations > Investigations list**. By right clicking on an item, you can load or delete the selected investigation. Double click also be used to load investigations. 

[[Image(inv.png, width=800, align=center)]]

The investions editor has two parts. On the left side you can see and select nodes of the whole investigations tree. On the right side are the details of the selected node, and also buttons for the actions that can be performed on this node.

The investigations editor is similar to most Eclipse editors in that modifications are not saved on disk until you indicate your intent by pressing one of the **Save** buttons or hit the appropriate keyboard shortcut (**Ctrl-S** by default).

Undo/redo features are not yet present in the current implementation.

To start a query from a node, just left click in the code text on the right side. You can specify your (position based) semantic query in the appearing query dialog. This query will be based on the position you clicked in the code text beforehand. 
After the query was completed, a dialog window will appear, where you can select which results would you like to include as nodes in the tree. All of these new nodes will be the child nodes of the original query.

Here, we describe the additional elements in the details side of the investigations editor:
* **Name** - You can give an arbitrary name to the selected node.
* **Show** - //(Not used.)// This will set wheter the node will be shown in the 2D tree representation of other !RefactorErl interfaces.
* **Add memo** - Memo nodes are special text-only nodes to hold comments and notes about the parent of the memo node.
* **Delete node** - Removes the selected node. If the selected node had child nodes, those will be recursively removed as well.
* **New investigation with node** - Creates a new investigation tree with the selected node as its only element (and root).
* **New investigation with subtree** - Copies the whole subtree, rooted in the selected node, to a new investigation.

[=#planned]
= Planned features and improvements

* Distinct file handling for local and remote !RefactorErl instances. In the current version, only the local filesystem can be accessed.
* Undo/redo features for modifying operations like refactorings.
* Preview window for refactorings and other modifying operations.
* Interruptable operations.
* Wider interoperability with the Erlide plugin.
* Graphical investigations interface, matching in appearance to those in other !RefactorErl interfaces.
* Dependency graph drawings with Eclipse GEF4 plugin

[=#troubleshooting]
= Troubleshooting
This section describes some of the most frequently experienced problems relating to the installation and starting of the plugin. If the proposed solutions aren't working or you have a problem not in this list, feel free to [https://plc.inf.elte.hu/erlang/refactorerl-contact.html contact us.]
* **The installation won't finish and shows an error message** - Make sure you have the correct Eclipse version listed in the [#instdep dependencies section].
* **There is no !RefactorErl menu after the installation** - You need to open the !RefactorErl perspective or the Erlide perspective to access the !RefactorErl menu. 
* **There is no !RefactorErl perspective nor is there a !RefactorErl entry in the Preferences window.** - You either did not have installed the plugin, or you have installed it, but the Eclipse platform could not run the plugin. This is commonly caused by unsuitable Java versions. Check if the version of your JRE/JDK environment on your system matches the one listed in the [#instdep dependencies section].
* **The plugin runs, but I'm unable to connect to the !RefactorErl tool** - This can happen for various reasons, you can try taking the following steps:
  1. Make sure the tool is installed properly and can be run from the command line. (Take care, because Mnesia can only be start with one name per data directory, and this also stands for the default values!)
  1. Try ticking the **Debug mode** button in the **Preferences** window. When you attempt to connect, a console view will appear, where you can check the output of the process. If there is no output, you're likely not supplied the correct path to the !RefactorErl process.
  1. If the process starts, but the connection doesn't, you can try checking the logs. These files are containing the Erlang-formatted communication between the plugin and the !RefactorErl process.