Writing a script

Script file locations

Scripts are installed in the Monkey menu by placing them in "*.em" files in a top-level "monkey" folder of any project (obviously, scripts are un-installed by renaming or moving them). The complete set of scripts is the union of the scripts in all the top-level monkey folders in the workspace.

Script metadata

Scripts include metadata that specifiy how a script is to be run and additional resources required for successful operation. Metadata consists of keyword values pairs. These are placed in the first comment block of the script. This must be a /* ... */ style comment. Currently only the Menu: and DOM: keywords are processed.

Script menus

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

Script key bindings

The Key: metadata tag specifies the single keystroke 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.

Objects of all Kinds

Scripts manipulate script objects such as strings and arrays, native Java objects including native Eclipse objects, and special DOM objects made specifically to simplify scripting.

Native Java objects can be accessed through their fully qualified class names. Eclipse objects require that the fully qualified name be prepended with the additional name "Packages". Here are some valid scripting expressions that show how this works

One of the challenges in scripting for Eclipse is dealing with the restricted namespaces of the various plug-ins. The classes and packages that are directly referencable are those in the plug-in pre-requisites of the org.eclipse.eclipsemonkey plug-in such as org.eclipse.ui and org.eclipse.jface.text. To use other packages and classes, you must use a DOM (see below).

Built-In 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 built-in DOMs available with this release are:

Plug-In DOM Objects

Plugin-DOMs are specified in the metadata with the "DOM:" tag who's value is a URI of the form:
http://<update-site>/<dom-plugin-ID>
The <update-site> refers to a normal Eclipse Update Manager update site. The <dom-plugin-ID> is the unique ID of the plug-in that supplies the DOM (via the org.eclipse.eclipsemonkey.dom extension point). Eclipse Monkey checks to be sure that all specified DOMs are loaded and notifies you if they aren't.

If you ask, Eclipse Monkey will open an approximately configured update dialog to load missing DOMs:

Standard DOM Objects

The following DOMs are contributed by the org.eclipse.dash.doms plug-in

Learn about these DOM through the examples or by reading the source code of the Eclipse Monkey Standard DOMs plug-in (org.eclipse.dash.doms).