Eclipse Monkey scripting with Ruby

This page gives an introduction to how to write Eclipse Monkey scripts using the Ruby scripting language.

1 Introduction
2 Reference
3 Related Topics

Introduction

If you are new to scripting with Eclipse Monkey, writing an Eclipse Monkey script in Ruby is very similar to writing an Eclipse Monkey script in JavaScript. You might want to familiarize yourself with Eclipse Monkey first by reading through some of the links in the Scripting with Eclipse Monkey Help topic.

The reference below lists the information that you will need to know when writing an Eclipse Monkey script in Ruby.

Reference

Location for your Eclipse Monkey scripts

The Scripts menu and Scripts View will recognize any *.rb files placed in a top-level "monkey" or "script" folder in any project. Simply create a top-level "monkey" or "script" folder in any of your projects, and copy or move your Eclipse Monkey scripts there.

You can uninstall your scripts by removing them from this folder.

The complete set of scripts is the cumulation of the scripts in all the top-level monkey and script folders in your workspace.

Example Script

The example Eclipse Monkey script below converts a string to a symbol:

=begin
 Menu: Ruby > String to Symbol
 Kudos: Christopher Williams
 Key: M1+Shift+;
 License: EPL 1.0
 DOM: http://download.eclipse.org/technology/dash/update/org.eclipse.eclipsemonkey.lang.ruby
=end
 
# If the current token is a string containing alnums, change it to
# a symbol
editor = $editors.get_active_editor
selection = editor.selection_range
selected_src = editor.source[selection]

# if entire selection is a string with no dynamic content, then convert the string to a symbol
match = selected_src.match(/(['"])([_a-zA-Z][_\w]*)\1/)
return if match.nil? || match.size != 3
symbol = ":" + match[2]
editor.apply_edit(selection.first, selection.length - 1, symbol)

Adding metadata to your script

Script metadata, which consists of keyword value pairs, specifies both how a script is to be run and additional resource requirements. Place your metadata in the first comment block of your script. Your metadata block must be a mult-line (=begin … =end) comment. Only recognized keywords are processed. See the sample script (above) to see an example of a script with metadata.

Running your script

You can easily set up a menu or keybindings to run your script. Use the metadata to configure your menu and keybinding settings.

Menu metadata

Use the Menu: metadata tag to specify that this script is to be included in the Scripts menu. If more than one script specifies the same menu item, the menu item will appear more than once. You can create Submenus using the Eclipse standard notation "Menu > SubMenu" or "Menu > SubMenu > SubSubMenu" (etc.) in the metadata string.

Keybinding metadata

Use the Key: metadata tag to specify any single keystroke hotkeys to be assigned to the script.

The format of keystrokes is described in the org.eclipse.ui.bindings extension point documentation for the sequence attribute which is reproduced below.

The recognized modifiers keys are M1, M2, M3, M4, ALT, COMMAND, CTRL, and SHIFT. The "M" modifier keys are a platform-independent way of representing keys, and these are generally preferred. M1 is the COMMAND key on MacOS X, and the CTRL key on most other platforms. M2 is the SHIFT key. M3 is the Option key on MacOS X, and the ALT key on most other platforms. M4 is the CTRL key on MacOS X, and is undefined on other platforms.

The actual key is generally specified simply as the ASCII character, in uppercase. So, for example F or , are examples of such keys. However, there are some special keys; keys that have no printable ASCII representation. The following is a list of the current special keys: ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, BREAK, BS, CAPS_LOCK, CR, DEL, END, ESC, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, FF, HOME, INSERT, LF, NUL, NUM_LOCK, NUMPAD_0, NUMPAD_1, NUMPAD_2, NUMPAD_3, NUMPAD_4, NUMPAD_5, NUMPAD_6, NUMPAD_7, NUMPAD_8, NUMPAD_9, NUMPAD_ADD, NUMPAD_DECIMAL, NUMPAD_DIVIDE, NUMPAD_ENTER, NUMPAD_EQUAL, NUMPAD_MULTIPLY, NUMPAD_SUBTRACT, PAGE_UP, PAGE_DOWN, PAUSE, PRINT_SCREEN, SCROLL_LOCK, SPACE, TAB and VT.

We also understand some alternative names for some common special keys. For example, we accept both ESC and ESCAPE, and CR, ENTER and RETURN are all the same.

DOM Objects

DOM objects appear as globals in the script namespace. Some DOMs are primitively supported, others are supplied by DOM plug-ins (standard Eclipse plug-ins that contribute an org.eclipse.eclipsemonkey.dom extensions).

The Ruby extension provides an Editors DOM. This DOM provides access to editors within Eclipse. To access the DOM, simply call the $editors global:

editor = $editors.get_active_editor

The Editors DOM Object provides two methods:

get_active_editor - Returns an Editor object referring to the active editor in the workspace.
all - Returns an array of Editor objects.

The Editor DOM Object provides:

currentOffset (aliased as current_offset) - Returns a Fixnum with the current offset of the cursor in the editor
source - Returns a String with the contents of the editor
sourceLength (aliased as source_length) - Returns a Fixnum with the length of the editor's contents
id - Returns a String with the unique identifier
close(boolean save)- Closes the editor, and optionally saves the contents first (depending upon boolean value)
save - Saves the editor's contents
selectionRange (aliased as selection_range) - Returns a Range of Fixnums with the offsets of the currently selected text in the editor.
lineDelimeter (aliased as line_delimeter) - Returns a String with the line deleimeter (e.g. \n, \r\n)
applyEdit(Fixnum offset, Fixnum deleteLength, String insertion) (aliased as apply_edit) - Inserts the string at the offset specified, and removes deleteLength characters first from the source.
selectAndReveal(Fixnum offset, Fixnum length) (aliased as select_and_reveal) - Highlights/selects the text at offset to offset + length in the source, and repositions editor to show the selection.