3.1 Writing Commands

StumpWM commands are written much like any Lisp function. The main difference is in the way command arguments are specified. The defcommand macro takes a list of arguments as its first form (similar to the defun macro), and a corresponding list of types as its second form. All arguments must belong to a “type”. Each type specification has two parts: a keyword specifying the argument type, and a string prompt that will be displayed when asking the user to enter the argument value. A typical defcommand might look like this:

(defcommand now-we-are-six (name age)
    ((:string "Enter your name: ")
     (:number "Enter your age: "))
  (message "~a, in six years you will be ~a" name (+ 6 age)))

If now-we-are-six is called interactively via the colon command, the user will be prompted for a string and a number, which will then be bound to “name” and “age”, respectively, in the body of the command.

When invoking the command via a key-binding, it is possible to provide some or all of the arguments directly:

(define-key *root-map* (kbd "L") "now-we-are-six John")

In this case, hitting C-t L will only prompt for an age (the first string argument is already bound to “John”). Argument values provided this way always bind to the earliest arguments defined: ie, it is not possible to specify an age, but prompt the user for a name.

If the type declaration does not include a prompt (ie, it looks like “(:type nil)”, or “(:type)” or just “:type”), the argument is considered optional. It can be provided via a key-binding invocation, as above, but if it isn’t, the user will not be prompted, and the argument will be bound to nil.

Lastly, it is possible to limit the scope under which the command will be usable: a command can be defined to work only in tile groups, or only in floating groups (the only two types of groups that currently exist). This is done by replacing the name of the command with a two-element list: the name of the command as a symbol, and either the symbol tile-group or floating-group. For instance, the next command, which only functions in tile groups, is defined this way:

(defcommand (next tile-group) …)

This document was generated on January 28, 2024 using texi2html 1.82.