# Using Macros

Macros in jEdit are short scripts written in a scripting language called BeanShell. They provide an easy way to automate repetitive keyboard and menu procedures, as well as access to the objects and methods created by jEdit. Macros also provide a powerful facility for customizing jEdit and automating complex text processing and programming tasks. This section describes how to record and run macros. A detailed guide on writing macros appears later; see writing-macros-part.

## Other scripting languages

A number of jEdit plugins provide support for writing scripts in alternative programming languages, like Python and Prolog. Consult the documentation for the appropriate plugins for more information.

## Recording Macros

The simplest use of macros is to record a series of key strokes and menu commands as a BeanShell script, and play them back later. While this doesn't let you take advantage of the full power of BeanShell, it is still a great time saver and can even be used to prototype more complicated macros.

Macros>Record Macro (shortcut: C+m C+r) prompts for a macro name and begins recording.

While recording is in progress, the string Macro recording is displayed in the status bar. jEdit records the following:

- Key strokes

- Menu item commands

- Tool bar clicks

- All search and replace operations, except incremental search

Mouse clicks in the text area are not recorded; use text selection commands or arrow keys instead.

Macros>Stop Recording (shortcut: C+m C+s) stops recording. It also switches to the buffer containing the recorded macro, giving you a chance to check over the recorded commands and make any necessary changes. When you are happy with the macro, save the buffer and it will appear in the Macros menu. To discard the macro, close the buffer without saving it.

The file name extension `.bsh` is automatically appended to the macro name, and all spaces are converted to underscore characters, in order to make the macro name a valid file name. These two operations are reversed when macros are displayed in the Macros menu; see organizing-macros for details.

If a complicated operation only needs to be repeated a few times, using the temporary macro feature is quicker than saving a new macro file.

Macros>Record Temporary Macro (shortcut: C+m C+m) begins recording to a buffer named `Temporary_Macro.bsh`. Once recording of a temporary macro is complete, jEdit does not display the buffer containing the recorded commands, but the name `Temporary_Macro.bsh` will be visible on any list of open buffers. By switching to that buffer, you can view the commands, edit them, and save them if you wish to a permanent macro file. Whether or not you look at or save the temporary macro contents, it is immediately available for playback.

Macros>Run Temporary Macro (shortcut: C+m C+p) plays the macro recorded to the `Temporary_Macro.bsh` buffer.

Only one temporary macro is available at a time. If you begin recording a second temporary macro, the first is erased and cannot be recovered unless you have saved the contents to a file with a name other than `Temporary_Macro.bsh`. If you do not save the temporary macro, you must keep the buffer containing the macro script open during your jEdit session. To have the macro available for your next jEdit session, save the buffer `Temporary_Macro.bsh` as an ordinary macro with a descriptive name of your choice. The new name will then be displayed in the Macros menu.

## Running Macros

Macros supplied with jEdit, as well as macros that you record or write, are displayed under the Macros menu in a hierarchical structure. The jEdit installation includes about 30 macros divided into several major categories. Each category corresponds to a nested submenu under the Macros menu. An index of these macros containing short descriptions and usage notes is found in macro-index.

To run a macro, choose the Macros menu, navigate through the hierarchy of submenus, and select the name of the macro to execute. You can also assign execution of a particular macro to a keyboard shortcut, toolbar button or context menu using the Macro Shortcuts, Tool Bar or Context Menu panes of the Utilities>Options dialog; see global-opts.

## How jEdit Organizes Macros

Every macro, whether or not you originally recorded it, is stored on disk and can be edited as a text file. The file name of a macro must have a `.bsh` extension in order for jEdit to be aware of it. By default, jEdit associates a `.bsh` file with the BeanShell edit mode for purposes of syntax highlighting, indentation and other formatting. However, BeanShell syntax does not impose any indentation or line break requirements.

The Macros menu lists all macros stored in two places: the `macros` subdirectory of the jEdit home directory, and the `macros` subdirectory of the user-specific settings directory (see settings-directory for information about the settings directory). Any macros you record will be stored in the user-specific directory.

Macros stored elsewhere can be run using the Macros>Run Other Macro command, which displays a file chooser dialog box, and runs the specified file.

The listing of individual macros in the Macros menu can be organized in a hierarchy using subdirectories in the general or user-specific macro directories; each subdirectory appears as a submenu. You will find such a hierarchy in the default macro set included with jEdit.

When jEdit first loads, it scans the designated macro directories and assembles a listing of individual macros in the Macros menu. When scanning the names, jEdit will delete underscore characters and the `.bsh` extension for menu labels, so that `List_Useful_Information.bsh`, for example, will be displayed in the Macros menu as List Useful Information.

You can browse the user and system macro directories by opening the `macros` directory from the Utilities>jEdit Home Directory and Utilities>Settings Directory menus.

Macros can be opened and edited much like ordinary files from the file system browser. Editing macros from within jEdit will automatically update the macros menu; however, if you modify macros from another program or add macro files to the macro directories, you should run the Macros>Rescan Macros command to update the macro list.