Thomas Becker's Free Software Utilities

## Emacros: A Package for Organizing and Handling Keyboard Macros in GNU Emacs

### Contents

1. Overview
3. Feedback and Bug Reports
4. Emacros Manual

### Overview

The purpose of keyboard macros in an editor is to expedite the entering of key sequences that occur frequently and are lengthy or inconvenient to type. GNU Emacs provides keyboard macros. Beginning with Version 22, GNU Emacs contains the kmacro package, which provides support for dealing with keyboard macros that have been defined and named during the current Emacs session. Support for saving, organizing, and reloading keyboard macros remains weak. The Emacros package facilitates these tasks.

Emacros' way of saving macro definitions to files is based on the idea that macro definitions should be separated by major modes to which they pertain. The macros used when editing a TeX file, for example, will not be needed when working on a C++ program. Moreover, within each mode, there will be macros that should be available whenever Emacs is in that mode, and others that are relevant for specific projects only. Consequently, each mode should allow one global macro file and several local ones in different directories as needed. This arrangement makes it easy to keep track of existing macro definitions.

Emacros works with GNU Emacs Versions 21 and 22. Earlier versions are no longer supported.

Click here to download the Emacros package. To install Emacros, place the file `emacros.elc` in some directory DIR. Add the line
```

```
to your Emacs initialization file, where you have replaced the string "DIR" in the `load-file` call with the actual directory where `emacros.elc` resides. "DIR" may of course be omitted if `emacros.elc` is in a directory where Emacs looks for lisp files. Be sure to load `emacros.elc` and not `emacros.el`. It is customary but not necessary to put the `.el` file in the same directory as the `.elc` file.

The directory where your global macro files will be kept defaults to your home directory. You may wish to choose a different directory. In that case, you must also place the line

```
(setq emacros-global-dir "DIR")

```
in your Emacs initialization file. DIR can be specified in unexpanded form, e.g., as `"~/emacs"`, and it may be given with or without trailing slash.

### Feedback and Bug Reports

Click to send feedback and bug reports concerning Emacros.

### Emacros Manual

#### Naming, Saving, and Executing Keyboard Macros

A keyboard macro really consists of two components: the (complicated) key sequence which is to be entered, and the (short) command which invokes the entering of the sequence. Here, we will refer to the key sequence as the macro, and to the command as its name.

When you use Emacros, defining a keyboard macro is done as usual with `C-x (` and `C-x )`, or with `F3` and `F4`, whichever you prefer. Emacros comes in when you name the macro: instead of giving the macro a name with Emacs' `name-last-kbd-macro` or with kmacro's `kmacro-name-last-macro`, you use the Emacros function `emacros-name-last-kbd-macro-add`.

This function first prompts the user for a name to be given to the most recently defined keyboard macro. The name must neither be the empty string nor an integer, and it must only use letters, digits, and the characters `_` and `-`. The name of an existing Emacs Lisp function which is not a keyboard macro will not be accepted as input.

Next, the function saves the macro definition to a file named `MODE-mac.el`, where `MODE` is the name of the current major mode. (See Section Slashes in Mode Names for a qualification of this statement.) This file can be in the directory for global macros, in which case the macro will be available whenever `MODE` is the major mode, or it can be in the current directory, in which case the macro will be locally available whenever `MODE` is the major mode and the file that is being visited is from this directory. The function will ask you to choose between `l` for local and `g` for global.

When `emacros-name-last-kbd-macro-add` is called with prefix argument, as in

```C-u M-x emacros-name-last-kbd-macro-add RET
```
then you will be prompted to explicitly enter the name of a file for saving the macro.

If a macro with the same name already exists in the file that you are saving to, you will be prompted for overwriting the existing definition.

Note that the function `emacros-name-last-kbd-macro-add` does not add the newly defined macro to the keyboard macro ring that is maintained by the kmacro package. See Section Emacros vs. Kmacro below for a more detailed explanation.

You may or may not want to bind the function `emacros-name-last-kbd-macro-add` to a key. You could, for example, bind it to `Ctrl-a` by placing the line

```(global-set-key "\C-ca" 'emacros-name-last-kbd-macro-add)
```
##### Function emacros-execute-named-macro
Once a macro MACRO has a name MACRONAME, this name is in fact a command which causes the macro to be inserted before the cursor: typing
```M-x MACRONAME RET
```
inserts MACRO. This has the disadvantage that completion and history take into account all command names rather than just macro names. The problem is resolved by the function `emacros-execute-named-macro`.This function should probably be bound to a key sequence such as `Ctrl-c e`. The line
```
(global-set-key "\C-ce" 'emacros-execute-named-macro)
```
in your Emacs initialization file does the job. Typing `Ctrl-c e` is then similar to `M-x`, but for macros only.
##### Function emacros-auto-execute-named-macro
This function is provided as a further convenience for the impatient. `emacros-auto-execute-named-macro` should definitely be bound to a key if you intend to use it at all. For example, `Ctrl-c x` would be a good choice. Typing `Ctrl-c x` will then prompt for the name of a macro. The cursor will stay at its position in the current buffer. As soon as the sequence entered matches the name of a macro, the macro is inserted and regular editing is resumed without the need to type a `return`.

When entering the name of a macro for auto-execution, the `return` key provides a rudimentary completion: the input is completed as far as possible, and execution occurs automatically as soon as a match has been found, even if it is "complete but not unique" in the sense of Emacs.

It is clear that you can not in this way insert a macro whose name contains the name of another macro as an initial substring. You may want to simply avoid this situation; however, if it occurs, you can always use `emacros-execute-named-macro` to insert such problem macros.

One of the most important features of Emacros is that macro definitions are loaded automatically when a file is visited. There are also ways to load and unload macros manually.
Everytime you read a file into Emacs with `Ctrl-x Ctrl-f`, `Ctrl-x Ctrl-v`, or `Ctrl-x 4 f`, the function
```emacros-load-macros
```
will be invoked automatically. It will load those macros that have been saved to files named `MODE-mac.el` in the current directory and in the directory for global macros. Here, `MODE` is name of the major mode that Emacs has chosen for the visited file. (See Section Slashes in Mode Names for a qualification of this statement.) The function can also be used interactively; the next section describes a situation where you may want to do this.
If you have been editing a file and then visit another one with a different mode and/or from a different directory, then the macros pertaining to the new file will be loaded, and all others that were loaded previously will remain active as well. If there are not too many macros around, this is probably what you want. In the long run, however, especially when you are one of those users that never leave Emacs, you would end up with all macros being loaded, thus rendering the separation by modes pointless. The function
```emacros-refresh-macros
```
takes care of this problem. Typing
```M-x emacros-refresh-macros RET
```
will unload all previously loaded macros and load the ones pertaining to the current buffer, thus creating the same situation as if you had just started Emacs and found the file that the current buffer is visiting. Another situation that necessitates similar action arises when you do not work "mode-consciously." If, for example, you edit a file named `test` and then turn it into a `.tex` file by typing
```C-x C-w test.tex RET
```
then Emacros will not automatically load the macros for TeX mode. To get things right, you must explicitly refresh your loaded macros:
```M-x emacros-refresh-macros RET
```
If you want to keep previously loaded macros active rather than refreshing, then you want to replace `emacros-refresh-macros` with `emacros-load-macros` in the above. Since the macro files `MODE-mac.el` contain ordinary Emacs Lisp code, you may also make macros available by loading macro files explicitly. This is done using the GNU Emacs function for loading Lisp code, as in
```M-x load-file RET
```
This is also the way to load macros when you have used the function `emacros-name-last-kbd-macro-add` with a prefix argument, thus choosing your own file for saving your macros.

#### Manipulating Macro Files

There are three functions that allow you to manipulate macro definitions that have already been saved. You can rename macros, move them betweeen local and global macro files, and remove them entirely.
##### Function emacros-rename-macro
This function assigns a new name to a previously named macro, making the change effective in the current session and in the local or global macro file pertaining to the current buffer, as appropriate. The old name is cleared of its meaning and may be used for a later macro. Typing
```M-x emacros-rename-macro RET
```
will prompt for the old name that is to be changed and then for the new name, subject to the same restrictions that apply when naming with `emacros-name-last-kbd-macro-add`. Completion and history are available when entering the old name. If a macro with the new name already exists in the file where the change takes place, you will be prompted for overwriting the existing defintion.

Note: The function `emacros-rename-macro` can access for renaming all those macros that pertain to the current buffer. You cannot access just every macro that happens to have been loaded during the current session. For example, if you have been working on a TeX file, then change to a buffer visiting a `.c` file, and then try to rename a macro named `NAME` that is kept in `TeX-mac.el`, you will get the message

```Macro named `NAME` not found in current file(s) C-mac.el: no action
taken.
```
You must change back to the buffer visiting the TeX file before you can access your macro for renaming. All this applies to moving and removing macros as well.
##### Function emacros-move-macro
This function moves macro definitions between the local and global macro file pertaining to the current buffer. Typing
```M-x emacros-move-macro RET
```
will prompt for the name of a macro to be moved and for a choice between "from local" and "from global" before performing the desired task.
##### Function emacros-remove-macro
This function deletes macros from current macro files and disables them in the current session. Typing
```M-x emacros-remove-macro RET
```
will prompt for the name of the macro to be deleted. A macro that has been deleted is irretrievably lost. As with `emacros-rename-macro`, the macro's name is made available for use with a different macro.

#### Getting Help with Macros

One way in which Emacros assists you with recalling macro names is by offering completion and command line history whenever the name of a macro is to be entered. Beyond that, there are two functions that provide help with keyboard macros. You can list the names of all currently defined macros, and you can obtain a list of the names of the macros together with a textual representation of each macro's definition. There is also the possibility to help yourself by inspecting and editing the files where the macros are stored.
##### Function emacros-show-macro-names
The function `emacros-show-macro-names` displays a list of the names of all currently defined macros in the Emacs `*Help*` buffer, much like completion lists are displayed in the `*Completion*` buffer. With prefix argument, as in
```C-u M-x emacros-show-macro-names RET
```
the function displays the macro names in a single column rather than in the two column format that Emacs uses for completion lists.
##### Function emacros-show-macros
The function `emacros-show-macros` displays a list of the names of all currently defined macros together with a textual representation of each macro's definition in the Emacs `*Help*` buffer.

Those parts of a macro definition that are plain character insertions are shown as strings in the textual representation. Function keys are shown using Emacs' standard textual representation. Control and alt keys are currently shown as "funny characters" in strings. For example, if you were to define a macro named `bm` with definition

```M-x buffer-menu RET
```
then the output of the function `emacros-show-macros` would display the following line for this macro:
```bm  "øbuffer-menu" <return>
```
This is certainly less than perfect. It wouldn't be hard to fix, if someone has the patience to do it.

#### Subtleties

This chapter discusses a few subtleties about Emacros. Except perhaps for the first section, these are things that the user should not really have to worry about.
##### Getting the Right Major Mode
There is a subtlety about Emacs' way of determining the major mode for a visited file that needs attention when using Emacros. The problem occurs when Emacs uses not only the file extension to determine the mode, but actually looks into the file. An example for this is LaTeX mode. The proper extension for LaTeX files is `.tex`. If you visit a non-empty file with extension `tex`, and there is nothing LaTeX-specific in it, then Emacs will put you in TeX mode. If you then add the line
```\documentstyle[...]{...}
```
to the top of the file and visit the file again later, you will find yourself in LaTeX mode. The fact that the major mode is different depending on what's in the file can of course cause a problem when using Emacros. However, this can be fixed by choosing your mode explicitly and loading macros manually: to be in LaTeX mode and have your LaTex macros loaded regardless of what's in the file, you must say
```M-x latex-mode RET
M-x emacros-refresh-macros RET
```
or
```M-x latex-mode RET
```
The first version will unload all currently defined macros and load the ones for the LaTex buffer only. The second one loads the macros for the LaTeX buffer on top of what may already be loaded.
##### Slashes in Mode Names
There are major modes for GNU Emacs whose name is not a constant string. The name of C++ mode, for example, is "`C++`". However, when you turn on `auto-newline` mode and `electric-mode`, the mode name changes to "`C++/la`". The slash in the mode name is of course a problem for Emacros, since it wants to use the mode name as part of a file name. Fortunately, however, it is also reasonable to ignore the qualifiations following the slash when it comes to saving macros. Therefore, Emacros uses only the part of the major mode name up to and not including the first forward slash when it builds its macro file names.
##### Compatibility with Emacs' Macro Saving
Suppose you have been saving kbd-macros using the Emacs function `insert-kbd-macro`, and you have loaded them by loading the file in which they were saved. The Emacros functions for executing and displaying macros will work for these macros.

To be able to rename, move, and remove your old macros by means of Emacros functions, you must edit your macro files. First, replace `fset` with `emacros-new-macro` in each macro definition. Then move the macro definitions to the appropriate files `MODE-mac.el`, placing each macro definition on a single line.

##### Visiting Macro Files
The functions for saving, renaming, moving, or removing macro definitions make changes to one or more of the files `MODE-mac.el`. If you are visiting such a file when using one of these functions and the respective buffer is modified, you will be notified and asked if it is ok to continue and possibly save. Answer `y` only if you are sure that the changes that you have made are meaningful. If your answer is `n`, then no action is taken at all.
##### Completing Macro Names
When a function requires the input of an existing macro name, completion works just as it normally does in GNU Emacs. The only exception is the function `emacros-auto-execute-named-macro`. Here, no completion lists are provided. The reason is that such a list would necessarily be misleading: suppose you have three macros named `abc`, `abd`, and `abcdefg`, and you have enetered `ab`. Listing all three as completions would be wrong because you cannot get to `abcdefg` with auto-execution. On the other hand, listing just `abc` and `abd` would be misleading as well because these are not the only macro names that start with `ab`. Auto-execution is really meant for frequently used macros whose names you just don't have trouble with.
##### Emacros vs. Kmacro
Beginnig with GNU Emacs Version 22, the kmacro package is part of the GNU Emacs distribution. The kmacro package provides support for dealing with macros that have been defined and named in the current Emacs session. For example, it places all keyboard macros that have been defined and named with the function `kmacro-name-last-macro` on the keyboard macro ring for easy retrieval.

The Emacros package, by contrast, provides support for saving keyboard macros to files and reloading them in future Emacs sessions. Keyboard macros that have been named and saved with the Emacros function `emacros-name-last-kbd-macro-add` are completely separate from the kmacro world. In particular, they are not placed on kmacro's macro ring. The main reason for this design decision is that in the Emacros world, where keyboard macros are saved and reloaded, there will often be a large number of macros. Holding them in a ring is not a very good way to keep track of them. The functions `emacros-execute-named-macro` and `emacros-auto-execute-named-macro` with their completion features and the help functions `emacros-show-macros` and `emacros-show-macro-names` are better suited for this purpose.

Emacros is an extension to GNU Emacs. Everyone is granted permission to copy, modify and redistribute Emacros, but only under the conditions described in the GNU Emacs General Public License. A copy of this license is supposed to have been given to you along with GNU Emacs so you can know your rights and responsibilities. It should be in a file named `COPYING`.