[[PageOutline]]

= Positioning Modes

== What are positioning modes?

The term "Positioning Mode" means an algorithm which is used for calculating token positions in source code files by the RefactorErl tool.
There are two different positioning modes in RefactorErl. These are the so-called absolute and relative modes. It is available to choose which one to be used.


== Why to choose positioning mode and how to do it?

It is a very useful feature that we can choose which positioning mode we want to use because it allows us to fine-tune RefactorErl so we can boost performance. Before we start the tool, we have to decide for what we would like to use it. There are some very easy principles:

* If we do not want to use refactoring functions we should use absolute positioning (for example we only want to use queries)
* If we refactor a lot we should consider using relative positioning
* If we know that we will only change some words in our files or only modify the beginning of the files (eg. comments) we should use relative positioning

If none of the above is true then we can use the default (absolute) positioning.

To start the tool with absolute positioning we should simply type ''bin/referl'' (this is the default) or type ''bin/referl -pos abs''. To start the tool with relative positioning we should type ''bin/referl -pos rel''.
The chosen positioning mode belongs to the database and its content that we load so we have to reset the database and restart the tool with another pos option to change positioning mode or we can also use ''ri:reset/1'' with the following parameters: rel, abs. 
To make it clear, lets see an easy example: if we start the tool with -pos rel and load up some directories we will have a database content with relative positioning. If we restart the tool without resetting it and using -pos abs nothing will happen, we will also have to use our relatively positioned database. If we want to setup positioning again, we have to use ri:reset/1 or ri:reset/0 and restart it.

{{{#!comment
To start the tool with absolute positioning we should simply type ''bin/referl'' (this is the default) or type ''bin/referl -pos abs''. To start the tool with relative positioning we should type ''bin/referl -pos rel''. The chosen positioning mode belongs to the database and its content that we load, but we can convert the database to change positioning mode using [[ErlangShellInterface#Manipulatingthegraph| ri:db_convert/1]] with the following parameters: rel, abs. To make it clear, lets see an easy example: if we start the tool with ''-pos rel'' and load up some directories we will have a database content with relative positioning. If we restart the tool without resetting it and using ''-pos abs'' nothing will happen, we will also have to use our relatively positioned database. If we want to change positioning to absolute mode, we will have to use ''ri:db_convert(abs)''.
}}}

== How do positioning modes work?

=== Absolute mode

In this mode, we store an absolute position for every token which means a little bit bigger database size but a very fast position calculation. If we refactor or change in a file some token positions have to be recalculated. "Some tokens" means many times hundreds of tokens. This recalculation makes RefactorErl slower.

=== Relative mode
In this mode, we store an absolute position for every form and a relative one for every token in it. This grants us a relatively fast recalculation and an average position calculation.