<?xml version="1.0" encoding="UTF-8"?>
<appendix id="macro-index">
    <title>Macros Included With jEdit</title>
    <!-- jEdit 4.0 Macro Guide, (C) 2001 John Gellene      -->
    <!-- jEdit 4.4 Macro Guide, (C) 2010 jedit-devs        -->
    <!-- jEdit buffer-local properties:                    -->
    <!-- :indentSize=2:noTabs=yes:maxLineLen=90:tabSize=2: -->
    <!-- :xml.root=users-guide.xml:                        -->
    <!-- covers index to installed macro set               -->

    <para>jEdit comes with a large number of sample macros that perform a
    variety of tasks. The following index provides short descriptions of each
    macro, in some cases accompanied by usage notes.</para>

    <para>In addition to the macros included with jEdit, a very large collection
    of user-contributed macros is available in the <quote>Downloads</quote>
    section of the <ulink
    url="http://community.jedit.org">community.jedit.org</ulink> web site. There
    are detailed descriptions for each macro as well as a search
    facility.</para>

    <section id="macros-c" >
        <title>C/C++ macros </title>
         <para> These macros are useful for C/C++ programming. </para>
         <itemizedlist>
         <listitem><para> <filename>Include_Guard.bsh</filename> </para>
         <para> Inserts conditional preprocessor directives around a header
         file, to prevent it from being included multiple times. </para>
         <para>The name of the generated preprocessor macro is based on the
          buffer's name. </para>
        </listitem>

         <listitem><para><filename> Toggle_Header_Source</filename></para>
         <para> Toggles between the header and the implementation file. Works for .c, .cxx, and .cpp extensions. </para>
         </listitem>
         </itemizedlist>
    </section>


    <section id="macros-clipboard">
        <title>Clipboard Macros</title>

        <para>These macros copy or cut text to the clipboard.</para>

        <itemizedlist>
            <listitem>
                <para><filename>Copy_Lines_Containing.bsh</filename></para>

                <para>Copies all lines from the current buffer, containing a
                user-supplied string, to the clipboard.</para>
            </listitem>

            <listitem>
                <para><filename>Cut_Lines_Containing.bsh</filename></para>

                <para>Cuts all lines from the current buffer, containing a
                user-supplied string, to the clipboard.</para>
            </listitem>

            <listitem>
                <para><filename>Copy_Selection_or_Line.bsh</filename></para>

                <para>If no text is selected, the current line is copied to the
                clipboard, otherwise the selected text is copied to the
                clipboard. Some editors have this has the default copy behavior.
                To achieve the same effect in jEdit, bind this macro to
                <keycap>C+c</keycap> in the <guibutton>Shortcuts</guibutton>
                pane of the <guimenu>Utilities</guimenu>&gt;
                <guimenuitem>Options</guimenuitem> dialog box.</para>
            </listitem>

            <listitem>
                <para><filename>Cut_Selection_or_Line.bsh</filename></para>

                <para>If no text is selected, the current line is cut to the
                clipboard, otherwise the selected text is cut to the clipboard.
                Some editors have this has the default cut behavior. To achieve
                the same effect in jEdit, bind this macro to
                <keycap>C+x</keycap> in the <guibutton>Shortcuts</guibutton>
                pane of the <guimenu>Utilities</guimenu>&gt;
                <guimenuitem>Options</guimenuitem> dialog box.</para>
            </listitem>

            <listitem>
                <para><filename>Copy_Visible_Lines.bsh</filename></para>

                <para>Copies the visible lines from the current buffer to the
                Clipboard. Lines that are not visible becuase they are folded
                are not copied.</para>
            </listitem>

            <listitem>
                <para><filename>Paste_Indent.bsh</filename></para>

                <para>Pastes the content of the clipboard and indents it.</para>
            </listitem>
        </itemizedlist>
    </section>

    <section id="macros-editing">
        <title>Editing Macros</title>

        <para>These macros automate various text editing tasks.</para>

        <itemizedlist>
            <listitem>
                <para><filename>Duplicate_Lines_Above.bsh</filename></para>

                <para>Duplicates current/selected line(s) upward.</para>
            </listitem>

            <listitem>
                <para><filename>Duplicate_Lines_Below.bsh</filename></para>

                <para>Duplicates current/selected line(s) downward.</para>
            </listitem>

            <listitem>
                <para><filename>Emacs_Ctrl-K.bsh</filename></para>

                <para>Cuts and appends text, from the cursor to the end of the
                line, into the copy buffer.</para>
            </listitem>

            <listitem>
                <para><filename>Emacs_Next_Line.bsh</filename></para>

                <para>Moves the cursor to the next line, centering the current
                line in the middle of the text area if the cursor is at the
                bottom of the text area.</para>
            </listitem>

            <listitem>
                <para><filename>Emacs_Previous_Line.bsh</filename></para>

                <para>Moves the cursor to the previous line, centering the
                current line in the middle of the text area if the cursor is at
                the top of the text area.</para>
            </listitem>

            <listitem>
                <para><filename>Go_to_Column.bsh</filename></para>

                <para>Prompts the user for a column position on the current
                line, then moves the caret there.</para>
            </listitem>

            <listitem>
                <para><filename>Greedy_Backspace.bsh</filename></para>

                <para>If buffer is using soft tabs, this macro will backspace to
                the previous tab stop, if all characters between the caret and
                the tab stop are spaces. In all other cases a single character
                is removed.</para>
            </listitem>

            <listitem>
                <para><filename>Greedy_Delete.bsh</filename></para>

                <para>If a buffer is using soft tabs, this macro will delete
                tabSize number of spaces, if all the characters between the
                caret and the next tab stop are spaces. In all other cases a
                single character is deleted.</para>
            </listitem>

            <listitem>
                <para><filename>Greedy_Left.bsh</filename></para>

                <para>If a buffer is using soft tabs, this macro will move the
                caret tabSize spaces to the left, if all the characters between
                the caret and the previous tab stop are all spaces. In all other
                cases, the caret is moved a single character to the left.</para>
            </listitem>

            <listitem>
                <para><filename>Greedy_Right.bsh</filename></para>

                <para>If a buffer is using soft tabs, this macro will move the
                caret tabSize spaces to the right, if all the characters between
                the caret and the next tab stop are all spaces. In all other
                cases, the caret is moved a single character to the
                right.</para>
            </listitem>

            <listitem>
                <para><filename>Keywords_to_Upper_Case.bsh</filename></para>

                <para>Converts all keywords in the current buffer to upper
                case.</para>
            </listitem>

            <listitem>
                <para><filename>Mode_Switcher.bsh</filename></para>

                <para>Displays a modal dialog with the current buffer's mode in
                a text field, allowing one to change the mode by typing in its
                name.</para>

                <para><keycap>ENTER</keycap> selects the current mode; if the
                text is not a valid mode, the dialog still dismisses, but a
                warning is logged to the activity log. <keycap>ESACPE</keycap>
                closes the dialog with no further action. <keycap>TAB</keycap>
                attempts to auto-complete the mode name. Pressing
                <keycap>TAB</keycap> repeatedly cycles through the possible
                completions. <keycap>SHIFT-TAB</keycap> cycles through the
                completions in reverse.</para>
            </listitem>

            <listitem>
                <para><filename>Move_Line_Down.bsh</filename></para>

                <para>Moves the current line down one, with automatic
                indentation.</para>
            </listitem>

            <listitem>
                <para><filename>Move_Line_Up.bsh</filename></para>

                <para>Moves the current line up one, with automatic
                indentation.</para>
            </listitem>

            <listitem>
                <para><filename>Open_Line_Above.bsh</filename></para>

                <para>Adds a new blank line before the current/selected line(s).</para>
            </listitem>

            <listitem>
                <para><filename>Open_Line_Below.bsh</filename></para>

                <para>Adds a new blank line after the current/selected line(s).</para>
            </listitem>

            <listitem>
                <para><filename>Toggle_Fold.bsh</filename></para>

                <para>Toggles visibility of current fold.</para>

                <para>This is especially useful for fold toggling via keyboard.</para>
            </listitem>
        </itemizedlist>
    </section>

    <section id="macros-files">
        <title>File Management Macros</title>

        <para>These macros automate the opening and closing of files.</para>

        <itemizedlist>
            <listitem>
                <para><filename>Browse_Buffer_Directory.bsh</filename></para>

                <para>Opens a the current buffer's directory in the file system
                browser.</para>
            </listitem>

            <listitem>
                <para><filename>Browse_Directory.bsh</filename></para>

                <para>Opens a directory supplied by the user in the file system
                browser.</para>
            </listitem>

            <listitem>
                <para><filename>Buffer_Switcher.bsh</filename></para>

                <para>Displays a modal dialog listing all open buffers, allowing
                one to switch to and/or close buffers. <keycap>ENTER</keycap>
                switches to a buffer and closes the dialog,
                <keycap>DELETE</keycap> closes a buffer, <keycap>SPACE</keycap>
                switches to a buffer but does not close the dialog.</para>
            </listitem>

            <listitem>
                <para><filename>Close_All_Except_Active.bsh</filename></para>

                <para>Closes all files except the current buffer.</para>

                <para>Prompts the user to save any buffer containing unsaved
                changes.</para>
            </listitem>

            <listitem>
                <para><filename>Copy_Path_to_Clipboad.bsh</filename></para>

                <para>Copies the current buffer's path to the clipboard.</para>
            </listitem>

            <listitem>
                <para><filename>Copy_Name_to_Clipboad.bsh</filename></para>

                <para>Copies the current buffer's filename to the
                clipboard.</para>
            </listitem>

            <listitem>
                <para><filename>Duplicate_Buffer.bsh</filename></para>

                <para>Duplicates the current buffer into a new one.</para>
            </listitem>

            <listitem>
                <para><filename>Delete_Current.bsh</filename></para>

                <para>Deletes the current buffer's file on disk, but doesn't
                close the buffer.</para>
            </listitem>

            <listitem>
                <para><filename>Glob_Close.bsh</filename></para>

                <para>Closes all open buffers matching a given glob
                pattern.</para>
            </listitem>

            <listitem>
                <para><filename>Insert_Selection.bsh</filename></para>

                <para>Assumes the current selection is file path and tries
                replaces the selection with the contents of the file. Does
                nothing if no text is selected or the selection spans multiple
                lines.</para>
            </listitem>

            <listitem>
                <para><filename>Next_Dirty_Buffer.bsh</filename></para>

                <para>Switches to the next dirty buffer, if there is one.</para>
            </listitem>

            <listitem>
                <para><filename>Open_Path.bsh</filename></para>

                <para>Opens the file supplied by the user in an input
                dialog.</para>
            </listitem>

            <listitem>
                <para><filename>Open_Selection.bsh</filename></para>

                <para>Opens the file named by the current buffer's selected
                text. Current VFS browser directory is also tried as
                a parent of the filename, but only as a local path.</para>
            </listitem>

            <listitem>
                <para><filename>Open_Selection_In_Desktop.bsh</filename></para>

                <para>Opens the file named by the current buffer's selected
                text using <code>Desktop</code>. That is opens the file
                using operating system's default application.
                If a link is selected, it is browsed instead, using default
                web browser. If no selection is active, the path
                under caret is used.</para>
            </listitem>

            <listitem>
                <para><filename>Send_Buffer_To_Next_Split.bsh</filename></para>

                <para>If bufferset scope is set to EditPane, the current buffer
                is added to the next Editpane's bufferset.</para>
            </listitem>

            <listitem>
                <para><filename>Toggle_ReadOnly.bsh</filename></para>

                <para>Toggles a local file's read-only flag. Uses
                platform-specific commands, so it only works on Windows, Unix
                and MacOS X.</para>
            </listitem>
        </itemizedlist>
    </section>

    <section id="macros-interface">
        <title>User Interface Macros</title>

        <para>Description.</para>

        <itemizedlist>
            <listitem>
                <para><filename>Decrease_Font_Size.bsh</filename></para>

                <para>Decreases the font size in the gutter and text area by 1
                point.</para>
            </listitem>

            <listitem>
                <para><filename>Increase_Font_Size.bsh</filename></para>

                <para>Increases the font size in the gutter and text area by 1
                point.</para>
            </listitem>

            <listitem>
                <para><filename>Open_Context_Menu.bsh</filename></para>

                <para>Opens the text area context menu just below and to the
                right of the caret.</para>
            </listitem>

            <listitem>
               <para><filename>Reset_TextArea.bsh</filename> </para>
               <para>Performs a split and an unsplit of the current TextArea.
	             Useful for those occasions when your textarea is corrupt
	             (painting the incorrect characters on the screen).</para>
             </listitem>

            <listitem>
               <para><filename>Splitpane_Grow.bsh</filename> </para>
               <para>When inside a split EditPane, this macro moves the
               splitter away from the cursor, effectively increasing the size of
               the currently active split pane.</para>
             </listitem>


            <listitem>
                <para><filename>Toggle_Bottom_Docking_Area.bsh</filename></para>

                <para>Expands or collapses the bottom docking area, depending on
                it's current state.</para>
            </listitem>

            <listitem>
                <para><filename>Toggle_Left_Docking_Area.bsh</filename></para>

                <para>Expands or collapses the left docking area, depending on
                it's current state.</para>
            </listitem>

            <listitem>
                <para><filename>Toggle_Right_Docking_Area.bsh</filename></para>

                <para>Expands or collapses the right docking area, depending on
                it's current state.</para>
            </listitem>

            <listitem>
                <para><filename>Toggle_Top_Docking_Area.bsh</filename></para>

                <para>Expands or collapses the top docking area, depending on
                it's current state.</para>
            </listitem>
        </itemizedlist>
    </section>

    <section id="macros-java">
        <title>Java Code Macros</title>

        <para>These macros handle text formatting and generation tasks that are
        particularly useful in writing Java code.</para>

        <itemizedlist>
            <listitem>
                <para><filename>Create_Constructor.bsh</filename></para>

                <para>Inserts constructor for the class at the current caret
                position.</para>
            </listitem>

            <listitem>
                <para><filename>Get_Class_Name.bsh</filename></para>

                <para>Inserts a Java class name based upon the buffer's file
                name.</para>
            </listitem>

            <listitem>
                <para><filename>Get_Package_Name.bsh</filename></para>

                <para>Inserts a plausible Java package name for the current
                buffer.</para>

                <para>The macro compares the buffer's path name with the
                elements of the classpath being used by the jEdit session. An
                error message will be displayed if no suitable package name is
                found. This macro will not work if jEdit is being run as a JAR
                file without specifying a classpath; in that case the classpath
                seen by the macro consists solely of the JAR file.</para>
            </listitem>

            <listitem>
                <para><filename>Java_File_Save.bsh</filename></para>

                <abstract>
                    <para>Acts as a wrapper script to the Save As action. If the
                    buffer is a new file, it scans the first 250 lines for a
                    Java class or interface declaration. On finding one, it
                    extracts the appropriate filename to be used in the Save As
                    dialog.</para>
                </abstract>
            </listitem>

            <listitem>
                <para><filename>Make_Get_and_Set_Methods.bsh</filename></para>

                <para>Creates <function>getXXX()</function> or
                <function>setXXX()</function> methods that can be pasted into
                the buffer text.</para>

                <para>This macro presents a dialog that will <quote>grab</quote>
                the names of instance variables from the caret line of the
                current buffer and paste a corresponding
                <function>getXXX()</function> or <function>setXXX()</function>
                method to one of two text areas in the dialog. The text can be
                edited in the dialog and then pasted into the current buffer
                using the <guilabel>Insert...</guilabel> buttons. If the caret
                is set to a line containing something other than an instance
                variable, the text grabbing routine is likely to generate
                nonsense.</para>

                <para>As explained in the notes accompanying the source code,
                the macro uses a global variable which can be set to configure
                the macro to work with either Java or C++ code. When set for use
                with C++ code, the macro will also write (in commented text)
                definitions of <function>getXXX()</function> or
                <function>setXXX()</function> suitable for inclusion in a header
                file.</para>
            </listitem>

            <listitem>
                <para><filename>Preview_Javadoc_of_Buffer.bsh</filename></para>

                <para>Create and display API documentation for the current
                buffer.</para>

                <para>The macro includes various configuration variables you can
                change; see the comment at the beginning of the macro source for
                details.</para>
            </listitem>
        </itemizedlist>
    </section>

    <section id="macros-misc">
        <title>Miscellaneous Macros</title>

        <para>While these macros do not fit easily into the other categories,
        they all provide interesting and useful functions.</para>

        <itemizedlist>
            <listitem>
                <para><filename>Buffer_to_HyperSearch_Results.bsh</filename></para>

                <para>Reads HyperSearch results from a buffer that was
                previously created by the HyperSearch_Results_to_Buffer macro and possibly
                filtered manually, and imports them into the HyperSearch Results dockable.</para>
            </listitem>

            <listitem>
                <para><filename>Debug_BufferSets.bsh</filename></para>

                <para>Display int and hex values for the character at the caret,
                in the status bar.</para>
            </listitem>

            <listitem>
                <para><filename>Display_Abbreviations.bsh</filename></para>

                <para>Displays the abbreviations registered for each of jEdit's
                editing modes.</para>

                <para>The macro provides a read-only view of the abbreviations
                contained in the <quote>Abbreviations</quote> option pane.
                Pressing a letter key will scroll the table to the first entry
                beginning with that letter. A further option is provided to
                write a selected mode's abbreviations or all abbreviations in a
                text buffer for printing as a reference. Notes in the source
                code listing point out some display options that are configured
                by modifying global variables.</para>
            </listitem>

            <listitem>
                <para><filename>Display_Actions.bsh</filename></para>

                <para>Displays a list of all the actions known to jEdit
                categorised by their action set.</para>

                <para>This macro can be a useful reference if you want to use
                the jEdit 4.2 action bar.</para>
            </listitem>

            <listitem>
                <para><filename>Display_Character_Code.bsh</filename></para>

                <para>Display int and hex values for the character at the caret,
                in the status bar.</para>
            </listitem>

            <listitem>
                <para><filename>Display_Shortcuts.bsh</filename></para>

                <para>Displays a sorted list of the keyboard shortcuts currently
                in effect.</para>

                <para>The macro provides a combined read-only view of command,
                macro and plugin shortcuts. Pressing a letter key will scroll
                the table to the first entry beginning with that letter. A
                further option is provided to write the shortcut assignments in
                a text buffer for printing as a reference. Notes in the source
                code listing point out some display options that are configured
                by modifying global variables.</para>
            </listitem>

            <listitem>
                <para><filename>Evaluate_Buffer_in_BeanShell.bsh</filename></para>

                <para>Evaluates contents of current buffer as a BeanShell
                script, and opens a new buffer to receive any text
                output.</para>

                <para>This is a quick way to test a macro script even before its
                text is saved to a file. Opening a new buffer for output is a
                precaution to prevent the macro from inadvertently erasing or
                overwriting itself. BeanShell scripts that operate on the
                contents of the current buffer will not work meaningfully when
                tested using this macro.</para>
            </listitem>

            <listitem>
                <para><filename>Hex_Convert.bsh</filename></para>

                <para>Converts byte characters to their hex equivalent, and vice
                versa.</para>
            </listitem>

            <listitem>
                <para><filename>HyperSearch_Results_to_Buffer.bsh</filename></para>

                <para>Writes HyperSeach results to a new buffer.</para>

                <para>This buffer can be re-imported to the HyperSearch Results dockable
                by the Buffer_to_HyperSearch_Results macro.</para>
            </listitem>


            <listitem>
                <para><filename>Make_Bug_Report.bsh</filename></para>

                <para>Creates a new buffer with installation and error
                information extracted from the activity log.</para>

                <para>The macro extracts initial messages written to the
                activity log describing the user's operating system, JDK, jEdit
                version and installed plugins. It then appends the last set of
                error messages written to the activity log. The new text buffer
                can be saved and attached to an email message or a bug report
                made on SourceForge.</para>
            </listitem>

            <listitem>
                <para><filename>Run_Script.bsh</filename></para>

                <para>Runs script using interpreter based upon buffer's editing
                mode (by default, determined using file extension). You must
                have the appropriate interpreter (such as Perl, Python, or
                Windows Script Host) installed on your system.</para>
            </listitem>

            <listitem>
                <para><filename>Show_Threads.bsh</filename></para>

                <para>Displays in a tree format all running Java threads of the
                current Java Virtual Machine.</para>
            </listitem>
        </itemizedlist>
    </section>

    <section id="macros-properties">
        <title>Property Macros</title>

        <para>These macros produce lists or tables containing properties used by
        the Java platform or jEdit itself.</para>

        <itemizedlist>
            <listitem>
                <para><filename>Create_Plugin_Announcement.bsh</filename></para>

                <para>Creates an announcement for the Plugin Central Submission Tracker
                based on the plugins *.props and description.html files.</para>
            </listitem>

            <listitem>
                <para><filename>Insert_Buffer_Properties.bsh</filename></para>

                <para>Inserts buffer-local properties into the current
                buffer.</para>

                <para>If the buffer's mode has a line comment defined, or
                comment start and end defined, the inserted properties will be
                commented out.</para>
            </listitem>

            <listitem>
                <para><filename>jEdit_Properties.bsh</filename></para>

                <para>Writes an unsorted list of jEdit properties in a new
                buffer.</para>
            </listitem>

            <listitem>
                <para><filename>Look_and_Feel_Properties.bsh</filename></para>

                <para>Writes an unsorted list of the names of Java Look and Feel
                properties in a new buffer.</para>
            </listitem>

            <listitem>
                <para><filename>System_Properties.bsh</filename></para>

                <para>Writes an unsorted list of all Java system properties in a
                new buffer.</para>
            </listitem>
        </itemizedlist>
    </section>

    <section id="macros-text">
        <title>Text Macros</title>

        <para>These macros generate various forms of formatted text.</para>

        <itemizedlist>
            <listitem>
                <para><filename>Add_Prefix_and_Suffix.bsh</filename></para>

                <para>Adds user-supplied <quote>prefix</quote> and
                <quote>suffix</quote> text to each line in a group of selected
                lines.</para>

                <para>Text is added after leading whitespace and before trailing
                whitespace. A dialog window receives input and
                <quote>remembers</quote> past entries.</para>
            </listitem>

            <listitem>
                <para><filename>Color_Picker.bsh</filename></para>

                <para>Displays a color picker and inserts the selected color in
                hexadecimal format, prefixed with a <quote>#</quote>.</para>
            </listitem>

            <listitem>
                <para><filename>Compose_Tag.bsh</filename></para>

                <para>The selection is taken as tag name and replaced with a full xml tag.</para>
            </listitem>

            <listitem>
                <para><filename>Duplicate_Line.bsh</filename></para>

                <para>Duplicates the line on which the caret lies immediately
                beneath it and moves the caret to the new line.</para>
            </listitem>

            <listitem>
                <para><filename>Insert_Date.bsh</filename></para>

                <para>Inserts the current date and time in the current
                buffer.</para>

                <para>The inserted text includes a representation of the time in
                the <quote>Internet Time</quote> format.</para>
            </listitem>

            <listitem>
                <para><filename>Insert_Tag.bsh</filename></para>

                <para>Inserts a balanced pair of HTML/SGML/XML markup tags as
                supplied in an input dialog. The tags will surround any selected
                text.</para>
            </listitem>

            <listitem>
                <para><filename>Line_Filter.bsh</filename></para>

                <para>Filters lines of the current buffer due to a provided regular expression.
                The resulting set of lines can be either removed from the buffer or written to a new buffer.</para>

                <para>The filter works on a multiline selection (if there is one) otherwise on the whole buffer.
                The resulting set of lines includes those lines that either match or not match the regular expression.
                </para>
            </listitem>

            <listitem>
                <para><filename>Next_Char.bsh</filename></para>

                <para>Finds next occurrence of character on current line.</para>

                <para>The macro takes the next character typed after macro
                execution as the character being searched. That character is not
                displayed. If the character does not appear in the balance of
                the current line, no action occurs.</para>

                <para>This macro illustrates the use of
                <function>InputHandler.readNextChar()</function> as a means of
                obtaining user input. See <xref
                linkend="macro-tips-single-char" />.</para>
            </listitem>

            <listitem>
                <para><filename>Reverse_Lines.bsh</filename></para>

                <para>Reverses the selected lines or the entire buffer if no
                lines are selected. Does not support Rectangular
                Selections.</para>
            </listitem>

            <listitem>
                <para><filename>Single_Space_Buffer.bsh</filename></para>

                <para>Removes every second line, if they are all blank.</para>
            </listitem>
        </itemizedlist>
    </section>
</appendix>
