Friday, 8 August 2008

jEdit for Ruby on Rails

jEdit is a mature programmer's (the editor, not necessarily the programmer) text editor with hundreds (counting the time developing plugins) of person-years of development behind it.

Caveat: I wrote this article about one and a half years ago (before i even had this blog) and then lost the file. I just dug it up almost accidentally, and so am posting it now because jEdit development moves along fairly slowly, and the information is probably still useful. please tell me in the comments, if something wrong or no longer current. i'll try to update the blog post, but can't test anything out as i'm no longer on jEdit.

What's nice about jEdit




  • Written in Java, so it runs on Mac OS X, OS/2, Unix, VMS and Windows.


  • Built-in macro language; extensible plugin architecture. Dozens of macros
    and plugins available.

  • Auto indent, and syntax highlighting for more than 130 languages.

  • Supports a large number of character encodings including UTF8 and Unicode.

  • Folding for selectively hiding regions of text.

  • Highly configurable and customizable.

  • Every other feature, both basic and advanced, you would expect to find in
    a text editor. See a full list of features.

  • Scriptable in Ruby!!

  • Lighter weight than most other Java based editors.


Installation



I am was running Ubuntu Edgy so this section details my experiences installing jEdit on that platform. This is the only platform specific section in this tutorial (and is also probably hopelessly out of date). If you are running some other system check out the jEdit download page for details. Disclaimer: I am by no means an Ubuntu expert so this information may be completely off.

First you need Java. You need to have sun-java5-jre installed, which is in ubuntu multiverse. You also want to make sure that you have java in your path. Edgy has a symbolic link chain which goes /usr/bin/java -> /etc/alternatives/java -> /usr/lib/jvm/java-1.5.0-sun/jre/bin/java which you should make sure is intact. Mine got screwed up (i think) when I was experimenting with sun-java6-jre. Incidentally sun-java6-jre causes an invalid pointer exception when you try to load a project in jEdit's project viewer plugin, so avoid it.

Then download the 'Java-based installer' (jedit42install.jar) file from the jEdit download page. Make sure it is version 4.2 final, because some ruby support is broken in the latest development releases.

Install it:

$ sudo java -jar jedit42install.jar

And run it:

$ jedit

The Plugins



jEdit should now be running. Go to Plugins->Plugin Manager, click on the Install tab, and now click Download Options. Update the mirror list and then choose a mirror, the default one never seems to work. Now check and install the following plugins:

Console

Allows you to interact with your rails app in a shell right in jEdit

IRC

Talk to other railers on IRC without leaving jEdit

Project Viwer

Gives you a view of your project filesytem. Required by the RubyPlugin but for some reason is not included in that plugin's dependencies so you have to manually select it

Ruby Plugin

Does a whole lot of good ruby stuff.

SideKick

Gives you a birds eye view of your file structure (classes methds etc), which also works for many other languages including html. It is also involved in parsing your ruby code, catching error, autocompletion, etc.

SuperAbbrevs

Allows TextMate like snippets

XML

XML, HTML, CSS and Javascript tools

SuperScript

Allows you to script jEdit in Ruby amongst other languages

Macro Manager

An easy way to download and manage macros


So lets put some of these plugins to good use. Go to Plugins->Project Viewer->Show Project Viewer. Now in the window that pops up there is a triangle at the top left. Click that to dock it in jEdit's main window. Once you've docked it, click the hard drive looking thingy (or right click the 'All Projects' folder to add a new rails project.

Now go to Plugins->Plugin Options and under Sideckick->Parsers make sure that mode ruby also has parser set to ruby. Now go to Plugins->Ruby Plugin->Structure Browser and doc the window that pops up in the main window. I usually doc it on the opposite side of the project viewer so i can see both at once. Note that the structure browser is the Sidekick structure browser and will work for other languages as well. Open a ruby file from your rails project and you can see the structure browser at work.

Have a goof around later with the plugins we just downloaded. And also with the many we haven't yet because there are some real gems in there.

Setting Key Bindings



For the sections that follow you'll need to know how to set key bindings. jEdit calls them 'shortcuts'.

To set a shortcut go to Utilities->Global Options, and then under Shortcuts set Edit Shorcuts to Built-in Commands, Macros, or your choice of Plugin. Once you have chosen one, you will see a list of the possible commands to bind for that category. Just click on one of the primary or alternative shortcut fields to enter key for a command. If you are over-writing another command you will be warned before it is saved.

Editing Modes



The ruby editing mode that comes default with jEdit aint that great so let's upgrade it. Go pick up the latest greatest (v0.6) jEdit ruby editing mode. There is a small download link, right click it and save file as ruby.xml. Don't just left click on it, it'll confuse you, it did me.

Once you have it put it in ~/.jedit/modes and then edit the ~/.jedit/modes/catalog file and add the following mode entry:
<MODE NAME="ruby" FILE="ruby.xml" FILE_NAME_GLOB="*.{rb,rbw}"
FIRST_LINE_GLOB="#!*/*ruby*" />

Your ruby editing should now be a whole lot prettier. You should see the effects immediately by the way, just close and reopen the ruby file you've been toying with.

Some other modes of interest and their catalog entries:

yaml

<MODE NAME="yaml" FILE="yaml.xml" 
FILE_NAME_GLOB="*.{yml,yaml}" />

haml

<MODE NAME="haml" FILE="haml.xml" 
FILE_NAME_GLOB="*.haml" />

rdoc

<MODE NAME="ruby" FILE="ruby.xml" 
FILE_NAME_GLOB="*.{rb,rbw}" FIRST_LINE_GLOB="#!*/*ruby*" />


Macros



Open related file

This macro lets you easily jump between models, controllers, etc. of the same base name. I don't think it's possible to install this one via. MacroManager so you'll need to get it off the web.

Download the open related file macro and place the decompressed folder under ~/.jedit/macros. Then do Macros->Rescan Macros and there should now be a Rails entry.

I like to set this binding to CS+o (Control Shift o)

Go To Ruby Method

Brings up a popup menu of Ruby methods that are in the current buffer grouped by class and ordered alphabeticaly. Selecting a class or method from the menu places the caret at that member's location in the file. I like to set this binding to CS+m (Control Shift m)

Redundant Macros

A few macros have been added to the RubyPlugin and so are now redundant, namely: 'Search Ruby Documentation using ri', and 'Auto indent and insert end'



SuperAbbrevs, Snippets for jEedit



You've probably seen the DHH screencasts where he is hardly typing anything and code is just appearing magically all over the place. The SuperAbbrevs plugin allows you to do just that using abbreviations.

You can get a nice set of 'Snippets' here. There is also a reference to the same here. There is a great tutorial on what they are and how to use them here.
I personally like just using Tab to expand so I didn't follow his advice on C+Enter.

Tips on writing abbrevs for ruby



Try to keep your abbrevs generic and rubyish. For instance the default 'for' abbrev for ruby is of this form (from memory because i changed it, so it may not be exactly this):

for ${1:i} in 0..${2:to} do
$end
end

Which is a fairly C way of thinking of a for loop. A more generic or polymorphic way of writing this while also keeping in mind that tab is also good for moving out of the body of a block, might be written thusly:

for $1 in $2
$end
end

Simpler, and more flexible.

Polishing Up



You are never going to have to type another 'end' again. Set a key binding to the RubyPlugin command 'Auto indent and insert end'. You should set the primary shortcut to 'Enter'. Don't worry about the fact that you are overriding the built in command, it won't break anything. Now try typing up a quick class and a few method defs, and while you're at it a couple control structures too.

In ruby we don't like big tabs. Go to Utilities->Global Options and in the left pane choose Editing. Here you can set your tab width and indent width, and set soft tabbing which means when you hit tab it will insert space characters instead. I usually set tab width and indent width to 2, and check soft tabbing as well. Haml likes two space 'tabs' as well.

It would be nice if we could collapse methods classes etc in order to make the file easier to look at in certain circumstances. jEdit does indeed implement code folding, let's enable it for ruby. Go to Utilities->Global Options and then under Editing set 'change settings for mode' to ruby, make sure that 'Use default settings' is unchecked and then set 'Folding mode' to Sidekick. You should now have collapsable ruby code in your edit buffer.

RubyPlugin and SideKick work together to give you code completion features. If you go to Plugins->Plugin Options and then SideKick you can tweek these settings. If you are like me and you hate stuff popping up all over the place without your asking for it then uncheck 'Show completion popups where possible'. If you want to still be able to request completions on demand set a key binding for the 'Complete code' command of the RubyPlugin. You should leave 'Immediately complete if possible' checked as it generally doesn't get in the way and is quite useful in some modes.

One last very useful couple keybings to set are the XML plugin's 'Characters to Entities' and 'Entities to Characters' commands. I like to set these to CS+x CS+c and CS+x CS+e respectively.

Conclusion



As you can see with all the bells and whistles installed Jedit is a powerful Ruby and Rails editor. Jedit, it should be noted, is also a great editor for many other languages including the usual web lineup. I hope that this guide has eased your entry into the Ruby on Jedit world. Thanks to the very many authors, both of software, docs, and blogs who have made this document possible.

2 comments:

Mario said...

Hello. I am the author of the Open Related File macro for JEdit. Today I figured out how to post the macro to the JEdit community site. However because I have to bundle the macro in a zip file (to include both the .bsh file and a .rb file needed by the macro) I am not able to publish the macro in a place where the Macro Manager can grab it. It is downloadable, though, from the community site:

http://community.jedit.org/?q=node/view/3984

Thanks for mentioning this plugin. I have a github repo for maintaining it.

http://github.com/marioaquino/railsmacro/tree/master

--Mario Aquino

Andy said...

Incredibly useful!

Thank you very much for this.