Debra Cameron - Learning GNU Emacs, 3rd Edition

The final statement in the function uses the built-in function messageto print a message in the minibuffer saying how many words the buffer contains. The form of the messagefunction will be familiar to C programmers. The first argument to messageis a format string, which contains text and special formatting instructions of the form % x , where x is one of a few possible letters. For each of these instructions, in the order in which they appear in the format string, messagereads the next argument and tries to interpret it according to the letter after the percent sign. Table 11-1lists meanings for the letters in the format string.

Table 11-1. Message format strings

For example:

(message "\"%s\" is a string, %d is a number, and %c is a character"

"hi there" 142 ?q)

causes the message:

"hi there" is a string, 142 is a number, and q is a character

to appear in the minibuffer. This is analogous to the C code:

printf ("\"%s\" is a string, %d is a number, and %c is a character\n",

"hi there", 142, 'q');

The floating-point-format characters are a bit more complicated. They assume a certain number of significant digits unless you tell them otherwise. For example, the following:

(message "This book was printed in %f, also known as %e." 2004 2004)

yields this:

This book was printed in 2004.000000, also known as 2.004000e+03.

But you can control the number of digits after the decimal point by inserting a period and the number of digits desired between the %and the e, f, or g. For example, this:

(message "This book was printed in %.3e, also known as %.0f." 2004 2004)

prints in the minibuffer:

This book was printed in 2.004e+03, also known as 2004.

The count-words-bufferfunction that we've just finished works, but it still isn't as convenient to use as the Emacs commands you work with daily. If you have typed it in, try it yourself. First you need to get Emacs to evaluate the lines you typed in, thereby actually defining the function. To do this, move your cursor to just after the last closing parenthesis in the function and type C-j(or Linefeed)—the "evaluate" key in Lisp interaction mode—to tell Emacs to perform the function definition. You should see the name of the function appear again in the buffer; the return value of the defunfunction is the symbol that has been defined. (If instead you get an error message, double check that your function looks exactly like the example and that you haven't typed in the line numbers, and try again.)

Once the function is defined, you can execute it by typing (count-words-buffer)on its own line in your Lisp interaction window, and once again typing C-jafter the closing parenthesis.

Now that you can execute the function correctly from a Lisp interaction window, try executing the function with M-x, as with any other Emacs command. Try typing M-x count-words-buffer Enter: you will get the error message [No match]. (You can type C-gto cancel this failed attempt.) You get this error message because you need to "register" a function with Emacs to make it available for interactive use. The function to do this is interactive, which has the form:

(interactive "prompt-string")

This statement should be the first in a function, that is, right after the line containing the defunand the documentation string (which we will cover shortly). Using interactivecauses Emacs to register the function as a command and to prompt the user for the arguments declared in the defunstatement. The prompt string is optional.

The prompt string has a special format: for each argument you want to prompt the user for, you provide a section of prompt string. The sections are separated by newlines ( \n). The first letter of each section is a code for the type of argument you want. There are many choices; the most commonly used are listed in Table 11-2.

Table 11-2. Argument codes for interactive functions

With the band foptions, Emacs signals an error if the buffer or file given does not already exist. Another useful option to interactiveis r, which we will see later. There are many other option letters; consult the documentation for function interactivefor the details. The rest of each section is the actual prompt that appears in the minibuffer.

The way interactiveis used to fill in function arguments is somewhat complicated and best explained through an example. A simple example is in the function goto-percent, which we will see shortly. It contains the statement

(interactive "nPercent: ")

The nin the prompt string tells Emacs to prompt for an integer; the string Percent:appears in the minibuffer.

As a slightly more complicated example, let's say we want to write our own version of the replace-stringcommand. Here's how we would do the prompting:

(defun replace-string (from to)

(interactive "sReplace string: \nsReplace string %s with: ")

...)

The prompt string consists of two sections, sReplace string:and sReplace string %s with:, separated by a Newline. The initial sin each means that a string is expected; the %sis a formatting operator (as in the previous messagefunction) that Emacs replaces with the user's response to the first prompt. When applying formatting operators in a prompt, it is as if messagehas been called with a list of all responses read so far, so the first formatting operator is applied to the first response, and so on.

When this command is invoked, first the prompt Replace string:appears in the minibuffer. Assume the user types fred in response. After the user presses Enter, the prompt Replace fred with:appears. The user types the replacement string and presses Enteragain.