Rails Shell View

The Rails Shell view is a good example of why I prefer RadRails over other existing
IDEs. Someone asked in the Aptana forums if RadRails could incorporate a nice
feature he saw in a different IDE. Chris Williams, the lead developer of RadRails,
asked him to enter the desired features into the Aptana Issues Tracker, where you
can report any bugs or ask for any functionalities you would like to see in RadRails.
Some months later, in RadRails 1.0, the Rails Shell view was already available.

From the Rails Shell view, you can have the best of two worlds: the power of the
command line and the ease of use of a development IDE. You can basically run railsrelated
commands from a command shell with content-assist.

The commands you can execute from this view are: rails, gem, rake, script/about,
script/console, script/destroy, script/generate, script/plugin, script/
runner, and script/server.

If you are not familiar with using these tools from the command line, maybe you will
not use the Rails Shell view very often. But if you are familiar with these commands,
you might find yourself more comfortable with the Rails Shell than with the GUI
views. As an additional advantage, from the Rails Shell view you can pass any extra
parameters to these commands. You could, for example, manually install a plugin or
a gem not listed in the Plugins or RubyGems views.

This view doesn’t have a tab of its own, but it’s accessed as a part of the Console
view. Go to the Console view and open the drop-down list by the Open Console
icon. From the list, select the Open a Rails Shell option.

By default, the Shell will be active for the currently selected project in the Ruby
Explorer. As usual you will see the current project in a label at the top of the
view, and you can use the Change Active Project icon to select a new project.
Alternatively, you can directly type switch or cd in the Rails Shell view and a list of
the available projects will appear for you to select one. Note that only the open Rails
projects will be available.

If you click Ctrl + Space (or Command + Space in Mac), the list of available commands
will appear.

Now you can either select the command directly from the list or start typing so the
list will filter the matching commands. Every time you type a command, a new
content-assist window will display with the suggested options for that command.
For example, if you type rake and then Space, you will see a list of the available tasks
for your project. Be careful not to hit Enter after typing rake without any arguments.
By default, the rake command without any arguments will try to run the tests for
your project.

It’s worth noting that some commands accept more options or fl ags than the ones
appearing as suggestions. Even if they don’t display in the list, if you pass those extra
fl ags they will have the expected effect. You could for example execute a Rake task
with trace (debug) information by typing:

	rake –trace stats

You can use this view also for starting a rails server via the script/server
command. If you want to start the server in debug mode, you can use the command:

	debug script/server

In the professional version of RadRails, there is also a profile option for starting your
server under profile mode. If you try to run the profile mode in the Community
edition you will get an error message.

Finally, in the Rails Shell view it’s possible to use the keyboard arrows to move
through the command history.

RegExp View

It’s not in every project that you need to write complex Regular Expressions, but
when you have to do it, it’s always nice to have a way for testing and refining them.
In Ruby you can always open a console and evaluate your expression against a given
string, but with complex expressions it can take a while to see why the string is not
matching properly.

RadRails incorporates the RegExp view, which will help us test regular expressions
and execute them step by step to see where the pattern is not matching your data.

The Regular Expression box is for entering the regular expression, and the Text to
match against box below is for entering the data to match it against. Once you write
your expression, you can use the icons on this view’s toolbar to evaluate it.

The icon most to the right is labeled Validate RegExp. When you select this icon, the
circle at the top of the view will change colour to Green or Red. Red means either
your expression was wrong, or it was right but no matches were found. Green means
the expression was matched correctly against the text and there were some results.

To actually see the matches of the expression, you can use the forward, backward,
and reset icons. When you click on forward, RadRails will break down your regular
expression into its subpatterns and will display how every part is matching with
your text. Every time you click on forward you will see the matches for the next
part of your expression. This is a very interesting way of testing your patterns, since
often a part of the expression is right but it doesn’t match your text because of a
subpattern. With this tool you can see how the different parts are being evaluated.

For example, in the preceding screenshot I wrote a simplistic expression for finding
email addresses in a text. The expression is not complete, but for this example’s
purposes it will do. Basically I’m telling RadRails to find strings composed of several
characters that are not spaces or ‘@’, then the ‘@’ symbol, then again some characters
except blanks, dots or the at symbol, and finally a dot and again some characters. The
pattern for this could be:

[^\s@]*?@[^\s\.@]*?\.[^\s@]*

And as the Match Text I’m using a combination of both valid email address and
non-matching text:

javier.ramirez.gomara@gmail.com wwww.radrails.com test@testmail.com

wrong@test wrong@wrong test@testmail.com

If you execute the expression by using the forward icon, you will see how the first
part of the expression will match the first part of the three legal email addresses in
that text, then the next part will match the three at symbols, and so on.

If you prefer to see the whole matches instead of the partial results, you can use a
trick. Surround the whole expression with parentheses and then you can use either
the Validate RegExp or the forward icon. In any case you will get the full matches
for your expression. In our example, it would look like this:

([^\s@]*?@[^\s\.@]*?\.[^\s@]*)

When I’m writing regular expressions, I like to go step by step until I have it
right and then use the parentheses to make sure the whole strings are being
matched properly.

Finally, the two checkboxes you can see in this view are used for telling your
expression to be case-insensitive or to match expressions even if the strings are
divided by a line break.

Problems View

When writing your code, if you have a syntax error you quickly fix it because Eclipse
will warn you, and because if you don’t, then your script will not run. If we are not
talking about errors but warnings, even if Eclipse warns us, we usually are much
more tolerant and we tend not to pay enough attention, thinking we can always fix
that later. By the time, and if, we want to clean up our code, we will most probably
have lost track of where the warnings were happening.

By using Eclipse Problems view, we can see a list of all the places in our code where
we have unresolved warnings. The list of warnings is configurable, as we will see
in the next chapter, and can include warnings about deprecations, empty blocks,
variable names, common possible errors, unused variables, and so on.

If you open the Problems view, you will see a list of the current warnings for your
project. If you cannot see any warnings, open one of your controllers and just define
an empty method that receives some variable you will never use. A definition like
this would do the trick:

	def empty_method(a)

	end

After you save the file, you will see two warnings in your Problems view, one about
having an empty method definition, and another one about an unused variable. If
you double-click on a line of this view, the corresponding file will be opened in the
editor and the cursor will be placed at the line containing the warning.

As you can see, the list gives you information about in which file the problem is
happening, the name of the container file, the relative path in the workspace, and the
line number. You can sort the list on any of these columns by clicking on the column
name. Thus, you can group together errors with the same description, in the same
project, or starting with the same path.

There are some extra options in this view. If you click on the view’s menu icon (as
shown in the above screenshot) you will see these additional options. If you want to
sort the lines by more than one column, by description and then by path, for example
you can use the sorting option. The Group By option of this menu will not have any
effect here as it makes sense only for developing Java projects with Eclipse. Use the
Preferences option if you want to limit the total number of warnings rendered.

Finall y, the Configure Filters option, also available as an icon on this view’s toolbar,
will allow you to filter warnings only for the current project, the current selection, or
the whole workspace (the Window Working Set). By default you will be presented
with warnings for all the opened projects in your workspace.

Tasks View

When y ou are working on a project, you sometimes leave incomplete methods or
things to fix later. As you know, it’s a very good practice to write a comment in
the code so you will not forget you have to finish or fix that code in the future. A
common coding convention is writing a comment with the word TODO (or XXX)
for incomplete functionality and with the word FIXME to mark a piece of code that
must be fixed.

RadRails supports the use of these coding conventions, and offers the Tasks view in
which you can see the list of annotations in your code and in which you can also set
to-do items manually.

The menu of this view is very similar to that of the Problems view, the main
difference being that in this case you can filter out results by using the priority
column too.

First of all, we are going to set some annotations in our code, so we will see some
entries in this view. Open the file books_controller.rb and at any place in the code
write the following comments:

	#XXX needs to iterate over the results. finish later

	#TODO automatically generated method

	#FIXME breaks on nil

After saving the controller, you should see three entries in the Problems view. Each
line displays the type of annotation as well as the associated comment. You will
notice that at the left of the FIXME annotation there is a red exclamation mark. This
is because the priority is automatically set to High on FIXME and normal on TODO
and XXX annotations.

Just a quick note here. Since Rails 2.0, there are some Rake tasks available for
searching for annotations in your code. The recognized annotations in these tasks
are FIXME, TODO, and OPTIMIZE (also supported by RadRails). Annotations with
XXX syntax are a common convention amongst software developers, but since they
are not supported by the Rails tasks it could be advisable not to use them. Of course
nothing will break if you do, but by using only the annotations Rails understands,
you can be sure people using a different IDE (or even no IDE at all) can take
advantage of your code annotations.

You can add your own annotations or change the priority of the existing ones from
the Window | Preferences dialog. We will see how to do this in the next chapter.

Apart from using this view for code annotations, you can manually add to-do items.
You can right-click on the content area of this view and select Add Task or you
can use the Add Task icon of the toolbar. A dialog will appear for you to enter the
description of the task, the priority you want to assign, and a checkbox indicating
whether it is completed or not. If you create a task with High priority, it will display
the red exclamation icon, and if you assign low priority, it will display a blue
down-arrow.

Once a task is set manually, you can click on the task description or in its priority in
the Tasks view and edit the information directly on the list. You can also check the
task as completed at any time you want.

When you add a task manually it is not associated to any resource. If for any
reason you want to add a task and you want to assign it to a source code file, you can
open the file you want in the editor and then select the Edit menu and then the Add
Task option. You will see the same dialog as before, but the Resource, Folder, and
Line fields will be filled. You can also add an associated task to a resource by
right-clicking on the left margin of the editor and selecting Add Task from the
context menu.

Test::Unit View

There is always an excuse not to write your tests: the deadline is close and you
don’t have the time, the requirements are not clear so it’s difficult to write the test
code, generating data for testing is not always easy. When working with Rails,
some of those excuses lose strength, since the framework facilitates the preparation
of the test database, the generation of the testing suites, and the execution of the
tests themselves.

Because of that, the proportion of developers writing applications in Rails who
systematically write tests is larger than in other development environments. Actually
there are many developers who write the tests even before than the code itself. Of
course this practice is not particular to Rails, but the framework makes easy to
adopt it.

Since testing is such a relevant part of the Rails philosophy, it’s only natural that
RadRails provides a specialized view to help us test our application. This view is
called Test::Unit view and it appears as a tab by the Ruby Navigator in the default
Rails perspective. Whenever a test suite is run from within RadRails, the Test::Unit
view will display the results of the execution, allowing you to examine the details.

There are several ways of running your tests from RadRails. The easiest way is to
navigate to a unit test file (under the test/unit directory of your project), right-click
on the name of the unit test file you want to execute, select Run As, and then
Test::Unit Test. Before running your test, make sure your test environment is
configured properly (database configuration, fixtures, and unit test code).

After the test is run, the Test::Unit view will present the results. Near the top of the
view you will see a bar either in green or red color. Green means all the tests passed
correctly, and red means there were failures or errors. A failure is reported when one
of the tests didn’t pass, and an error is reported if an exception was launched when
trying to run a test.

Above the bar, you can see how many tests were run, how many errors you got, and
how many failures. Below the bar there are two tabs. In the first one you will find
only the list of tests with errors or failures, and the second tab labeled Hierarchy
will display the list of all the executed tests, both successful and not. If you doubleclick
on any of the items, the corresponding file with the definition of the test will be
opened in the editor area.

When you select an item with errors or failures, the Failure Trace pane of the
Test::Unit view will display the details of the failure, or the Stack Trace in the case of
an exception.

In the toolbar of this view there is an icon for relaunching the last performed test,
another one for locking the scroll (in case launching big test suites producing a large
output), and the menu for this view, in which you can change the layout.

So far we have launched a single unit test suite, but as you know in Rails you can
also use functional and integration tests. For running all the unit tests in your project,
or for running the integration or functional tests, you have to use an icon located on
the toolbar of the Workbench.

If you hit the icon labeled Run All Tests all the Unit, Functional, and Integration
tests for your project will be run. If you want to launch only one test type, click on
the small arrow by that icon so you will get a submenu allowing you to run the
different test suites. No matter in which way you launch your tests, the output will
be displayed at the Test::Unit view in the same way as we saw before.

You can also choose to execute your tests automatically. In this case, the tests will
be run either every time you save a file or at a given interval of time defined by
you. If you want to run your tests automatically you have to configure RadRails
for that. Go to the Window menu, select Preferences… and then navigate to the
Rails | Autotest dialog.

The first thing you have to tell Autotest is how it will be launched: after saving a file
in the editor or at a regular interval. The two options are mutually compatible, so
you could mark both of them if you want.

After choosing when the Autotest will be run, you have to instruct RadRails about
which tests to launch. By default it will try to launch only the associated unit tests for
the model, controller, or plugin file you are saving. Modifying any other files will not
launch Autotest, which is one of the reasons why you could possibly want to launch
the test suite at regular intervals.

You can tell Autotest to run not only the associated unit tests, but also all the unit
tests for your project, all your integration tests, or all your functional ones. Once you
set the options as you think is better for you, just click on Apply and then on OK to
close the preferences dialog.

If you chose to Autotest after saving the editor’s contents, you can try opening a
model or controller, making a small change (maybe a blank character or a comment)
and saving. At the bottom of your eclipse workbench you should see the status line
informing you about the Autotest progress. When the test finishes, you can see the
results as usual in the Test::Unit view.

There is an additional feature of Autotest. The icon on the toolbar workbench close
to the Run All Tests one labeled Manually Run Autotest Suite will remain in green
if all the tests were passed, or will change to a white cross over a gray background in
the case of errors or failures.

In order to get your attention, for some seconds this icon will display an animation
of a small yellow blinking cross. In the figure below you can see the four possible
images for this icon.

When editing the contents of a model, controller, or plugin you can use this icon no
matter whether it’s displaying in green or gray and force running of the associated
tests (as configured at the Autotest preferences) even without saving the file or
waiting for the established interval.

Summary

This chapter explained how you can use RadRails for dealing with many of the
development tasks you would otherwise have to run from the command line in a
much more convenient way.

Except for exceptional occasions when you need to pass uncommon arguments to
the command-line tools, you can manage all your Rails development processes from
within the IDE by using the built-in views. If you find yourself going frequently
to the command line to launch some processes, we also learned how you can call
external tools from Eclipse, so you can have everything just a click away.

By using RadRails views, you can manage documentation, servers, the Rails console,
plugins and gems, Rake tasks, code generators, code annotations, warnings, to-do
tasks, regular expressions, and test suites.