<?xml version="1.0" encoding="UTF-8"?>
<chapter id="using-macros">
    <title>Using Macros</title>
    <!-- jEdit buffer-local properties:                               -->
    <!-- :tabSize=1:indentSize=1:noTabs=true:wrap=soft:maxLineLen=80: -->
    <!-- :xml.root=users-guide.xml: -->

    <para>Macros in jEdit are short scripts written in a scripting language
    called <firstterm>BeanShell</firstterm>. 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 <xref
    linkend="writing-macros-part" />.</para>

    <sidebar>
        <title>Other scripting languages</title>

        <para>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.</para>
    </sidebar>

    <sect1 id="recording-macros">
        <title>Recording Macros</title>

        <para>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
        <quote>prototype</quote> more complicated macros.</para>

        <para><guimenu>Macros</guimenu>&gt;<guimenuitem>Record
        Macro</guimenuitem> (shortcut: <keycap>C+m C+r</keycap>) prompts for a
        macro name and begins recording.</para>

        <para>While recording is in progress, the string <quote>Macro
        recording</quote> is displayed in the status bar. jEdit records the
        following:</para>

        <itemizedlist>
            <listitem>
                <para>Key strokes</para>
            </listitem>

            <listitem>
                <para>Menu item commands</para>
            </listitem>

            <listitem>
                <para>Tool bar clicks</para>
            </listitem>

            <listitem>
                <para>All search and replace operations, except incremental
                search</para>
            </listitem>
        </itemizedlist>

        <para>Mouse clicks in the text area are <emphasis>not</emphasis>
        recorded; use text selection commands or arrow keys instead.</para>

        <para><guimenu>Macros</guimenu>&gt;<guimenuitem>Stop
        Recording</guimenuitem> (shortcut: <keycap>C+m C+s</keycap>) 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 <guimenu>Macros</guimenu> menu. To discard the
        macro, close the buffer without saving it.</para>

        <para>The file name extension <filename>.bsh</filename> 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
        <guimenu>Macros</guimenu> menu; see <xref linkend="organizing-macros" />
        for details.</para>

        <para>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.</para>

        <para><guimenu>Macros</guimenu>&gt;<guimenuitem>Record Temporary
        Macro</guimenuitem> (shortcut: <keycap>C+m C+m</keycap>) begins
        recording to a buffer named <filename>Temporary_Macro.bsh</filename>.
        Once recording of a temporary macro is complete, jEdit does not display
        the buffer containing the recorded commands, but the name
        <filename>Temporary_Macro.bsh</filename> 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.</para>

        <para><guimenu>Macros</guimenu>&gt;<guimenuitem>Run Temporary
        Macro</guimenuitem> (shortcut: <keycap>C+m C+p</keycap>) plays the macro
        recorded to the <filename>Temporary_Macro.bsh</filename> buffer.</para>

        <para>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 <filename>Temporary_Macro.bsh</filename>. 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
        <filename>Temporary_Macro.bsh</filename> as an ordinary macro with a
        descriptive name of your choice. The new name will then be displayed in
        the <guimenu>Macros</guimenu> menu.</para>
    </sect1>

    <sect1 id="running-macros">
        <title>Running Macros</title>

        <para>Macros supplied with jEdit, as well as macros that you record or
        write, are displayed under the <guimenu>Macros</guimenu> 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 <guimenu>Macros</guimenu> menu. An index of
        these macros containing short descriptions and usage notes is found in
        <xref linkend="macro-index" />.</para>

        <para>To run a macro, choose the <guimenu>Macros</guimenu> 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
        <guimenuitem>Macro Shortcuts</guimenuitem>, <guimenuitem>Tool
        Bar</guimenuitem> or <guimenuitem>Context Menu</guimenuitem> panes of
        the <guimenu>Utilities</guimenu>&gt;<guimenuitem>Global
        Options</guimenuitem> dialog; see <xref linkend="global-opts" />.</para>
    </sect1>

    <sect1 id="organizing-macros">
        <title>How jEdit Organizes Macros</title>

        <para>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 <filename>.bsh</filename> extension in order for jEdit to be
        aware of it. By default, jEdit associates a <filename>.bsh</filename>
        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.</para>

        <para>The <guimenu>Macros</guimenu> menu lists all macros stored in two
        places: the <filename>macros</filename> subdirectory of the jEdit home
        directory, and the <filename>macros</filename> subdirectory of the
        user-specific settings directory (see <xref
        linkend="settings-directory" /> for information about the settings
        directory). Any macros you record will be stored in the user-specific
        directory.</para>

        <para>Macros stored elsewhere can be run using the
        <guimenu>Macros</guimenu>&gt;<guimenuitem>Run Other Macro</guimenuitem>
        command, which displays a file chooser dialog box, and runs the
        specified file.</para>

        <para>The listing of individual macros in the <guimenu>Macros</guimenu>
        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.</para>

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

        <para>You can browse the user and system macro directories by opening
        the <filename>macros</filename> directory from the
        <guimenu>Utilities</guimenu>&gt;<guimenuitem>jEdit Home
        Directory</guimenuitem> and
        <guimenu>Utilities</guimenu>&gt;<guimenuitem>Settings
        Directory</guimenuitem> menus.</para>

        <para>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
        <guimenu>Macros</guimenu>&gt;<guimenuitem>Rescan Macros</guimenuitem>
        command to update the macro list.</para>
    </sect1>
</chapter>