5 Advanced Features

defcommand

Macro

Summary

Defines new editor commands.

Package

editor

Signature

defcommand name lambda-list command-doc function-doc &body forms => command-name

Arguments

name: The name of the new editor command. See Description for more details.
lambda-list: The lambda list of the new command, which must have at least one argument.
command-doc: A string which gives a long-form command description.
function-doc: A string which gives a short-form function description.
forms: The Lisp code for the command.

Values

command-name: The symbol name of the new command.

Description

This macro defines a new Editor command name that can be invoked in the editor by means ofExtended Command. . Any Editor command has a Lisp function associated with it. The macro takes the specification of the command as supplied, and creates a new Lisp function from it.

Existing editor commands can be used within the body ofdefcommand. To make use of an existing command, the command name should be hyphenated with acommand suffix added. For example, the editor commandForward Character is referred to byforward-character-command. The syntax of a call to an existing command is the same as a call to a standard Lisp function. The first argument of all command definitions is the prefix argument, and this must therefore be included in any calls made to commands fromdefcommand, even when prefix arguments are ignored by the command. Some commands have additional optional arguments and details of these are provided in the command descriptions throughout this manual.

The name of the command must be a string, while the name of the associated function must be a symbol. There are two ways in which name can be supplied. Most simply, name is given as a string, and the string is taken to be the name of the editor command. The symbol the function needs as a name is computed from that string. Any spaces in the string are replaced with hyphens, and the quotes are discarded, but otherwise the symbol contains the same characters as the string.

If a specific function name, different to the onedefcommand derives itself, is required, then this can be supplied explicitly, by passing a list as name. The first element of the list is the string used as the name of the command, while the last element is the symbol used to name the Lisp function.

The command-doc and function-doc variables may be empty strings if no documentation is available for them.

Example

The following code defines an editor command,Move Five, which moves the cursor forward in an editor buffer by five characters.

(defcommand "Move Five" (p)
   "Moves the current point forward five characters.
    Any prefix argument is ignored."      
   "Moves five characters forward."
   (forward-character-command 5))

: The first string gives the command's name. This is the simple form of definition, where no explicit name for the Lisp function is given.
: p is not used, and is there simply because the lambda-list must have at least one element.
: The second string is the command documentation, while the third is the function documentation. After these, the Lisp code defines what the command actually does.