# define-macro(2)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

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

Once the macro has been defined, it becomes indistinguishable from a standard MicroEmacs 2009 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 2009. 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.

## EXAMPLE

The following are two standard macros provided with MicroEmacs 2009. 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), add-file-hook(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).

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12

</HMTL>