define-macro(2)

NAME

define-macro - Define a new macro

SYNOPSIS

n define-macro macro-name

Macro body

!emacro

DESCRIPTION

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 macro language.

Once the macro has been defined, it becomes indistinguishable from a standard MicroEmacs 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. We usually like start-up to be rapid and macros are loaded as and when requested by the user, or by the buffer major-modes as new files are loaded (see major-mode(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.

EXAMPLE

The following are two standard macros provided with MicroEmacs. 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 &not &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 &not $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 

SEE ALSO

Refer to !return(4) and !abort(4) for details macro termination.

!emacro(4), major-mode(2), define-macro-file(2), define-help(2), describe-bindings(2), execute-file(2), execute-named-command(2), global-bind-key(2), insert-macro(2), start-kbd-macro(2).

Ref: define-macro(2) File: m2cmd029.2 Date: 2026/01/17

(c) Copyright JASSPA 2026