define-macro - Define a new macro
n define-macro macro-name
define-macro starts the definition of an macro named macro-name, only used within macro files or buffers. After the above header line, the body of the macro is added, one command or expression on a line. The macro definition is completed by the !emacro directive.
The numeric argument n, specified as zero, defines the macro as private such that it does not appear on a command completion list. A zero argument is generally used on helper macro's that form part of a larger macro. If the argument is omitted, or non-zero, then the macro appears in the command completion list.
See execute-file(2) for a complete definition and examples of the MicroEmacs '06 macro language.
Once the macro has been defined, it becomes indistinguishable from a standard MicroEmacs '06 command, i.e. execute-named-command(2) (esc x) can be used to execute the macro and global-bind-key(2) can be used to globally bind the command to a key combination.
There are no restrictions on the number of macros that may be defined, provided that the name space is managed properly. Consideration must be given as to when any additional macros that are created are loaded into MicroEmacs '06. We usually like start-up to be rapid and macros are loaded as and when requested by the user, or by the buffer hooks as new files are loaded (see add-file-hook(2) and define-macro-file(2)).
User defined macros may be documented with on-line help by including a define-help(2) construct within the macro file.
The following are two standard macros provided with MicroEmacs '06. The first is a macro called clean, this strips trailing white space from the ends of lines in a file and removes blank lines from the end of the file.
define-macro clean ; ; Prepare to clean up file. ; Remember line & magic mode set-variable #l0 $window-line set-variable #l1 ¬ &bmod magic !if #l1 1 buffer-mode "magic" !endif ; ; Get rid of trailing white space on EOL beginning-of-buffer replace-string "[\t ]+$" "\\0" beginning-of-buffer replace-string "[ ]+\t" "\t" ; ; Strip trailing blank lines. end-of-buffer backward-line !while &and &gre $window-line 1 &sequal @wc "\n" kill-line backward-line !done ; ; Clean up - restore buffer modes etc. ; Move back to starting line & restore original magic mode !force goto-line #l0 !if #l1 -1 buffer-mode "magic" !endif screen-update ml-write "Cleaned up file." !emacro
The second example converts all of the <tab> characters in the file to their <SPACE> character equivalent.
; ; tabs-to-spaces. ; Convert all of the tabs to spaces. define-macro tabs-to-spaces ; Remember line set-variable #l0 $window-line beginning-of-buffer !force search-forward "\t" !while $status set-variable #l1 $window-acol backward-delete-char &sub #l1 $window-acol insert-space !force search-forward "\t" !done goto-line #l0 screen-update ml-write "[Converted tabs]" !emacro
Both of these commands are available from the command line, they are indistinguishable from the built in commands.
Macros may also be nested, as shown in the next example, this macro contains a define-macro within itself, when executed the macro creates another macro dynamically - dynamic macros are generally given a prefix of % and are highlighted differently in describe-bindings(2).
The following example is taken from the alarm(3) macro, executing alarm the user is prompted for a message, and the time interval before the alarm expires in hours and minutes. It then creates a new macro with a callback so that the new macro will be called at the correct time.
!if &seq %alarm-numb "ERROR" set-variable %alarm-numb 0 set-variable %osd-alarm &pinc %osd 1 !endif define-macro alarm set-variable %alarm-numb &add %alarm-numb 1 set-variable #l0 &cat "%alarm-" %alarm-numb !force set-variable #l2 @3 !if ¬ $status set-variable &ind #l0 @ml "Message" set-variable #l1 @ml "Hours" set-variable #l2 @ml "Minutes" !else set-variable &ind #l0 @1 set-variable #l1 @2 !endif set-variable #l1 &mul 60000 &add &mul 60 #l1 #l2 define-macro #l0 !bell set-variable #l0 &add &len &ind @0 10 osd %osd-alarm 0 "bat" 9 3 osd %osd-alarm 1 "" osd %osd-alarm 2 "c" "ALARM" osd %osd-alarm 3 "" osd %osd-alarm 4 "" &ind @0 osd %osd-alarm 5 "" osd %osd-alarm 6 "Bcf" " OK " f void %osd-alarm osd !emacro #l1 create-callback #l0 !emacro
Copyright (c) 1998-2006 JASSPA
Last Modified: 2002/01/11
Generated On: 2006/10/07