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 detailed description of the command.

function-doc

A string which gives a brief description of the command

forms

The Lisp code for the command.

Values

command-name

The symbol naming the new command. This symbol is interned in the current package.

Description

This macro defines a new editor command name that can be invoked in the editor by means of Extended Command. The macro takes the specification of the command as supplied, and creates a new Lisp function command-name from it.

Note: Every editor command has an associated Lisp function named command -command. For example:

editor:self-insert-command p &optional char

For every editor command documented in this manual, the associated command -command symbol is exported from the editor package; and for every editor command created by user code, the associated command -command symbol is interned in the current package.

Existing editor commands can be used within the body of defcommand . To make use of an existing command, the command name should be hyphenated with a command suffix added. For example, the editor command Forward Character is referred to by forward-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 from defcommand , 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 one defcommand 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.

(editor:defcommand "Move Five" (p)

   "Moves the current point forward five characters.

    Any prefix argument is ignored."      

   "Moves five characters forward."

   (editor:forward-character-command 5))

=>

MOVE-FIVE-COMMAND

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.

Use Alt+X Move Five to invoke the command.

This command changes all the text in a writable buffer to be uppercase:

(editor:defcommand "Uppercase Buffer" (p) 

     "Uppercase the buffer contents"""

  (declare (ignore p))

  (let* ((buffer (editor:current-buffer))

         (point (editor:buffer-point buffer))

         (start (editor:buffers-start buffer))

         (end (editor:buffers-end buffer)))

    (editor:set-current-mark start)

    (editor:move-point point end)

    (editor:uppercase-region-command nil)))