Learning GNU Emacs, 3rd Edition

You may have heard of Lisp as a language for artificial intelligence (AI). If you aren't into AI, don't worry. Lisp may have an unusual syntax, but many of its basic features are just like those of more conventional languages you may have seen, such as Java or Perl. We emphasize such features in this chapter. After introducing the basic Lisp concepts, we proceed by building up various example functions that you can actually use in Emacs. In order to try out the examples, you should be familiar with Emacs Lisp mode and Lisp interaction mode, which were discussed in Chapter 9.

11.1.1 Basic Lisp Entities

The basic elements in Lisp you need to be familiar with are functions, variables, and atoms. Functions are the only program units in Lisp; they cover the notions of procedures, subroutines, programs, and even operators in other languages.

Functions are defined as lists of the above entities, usually as lists of calls to other, existing functions. All functions have return values (as with Perl functions and non-void Java methods); a function's return value is simply the value of the last item in the list, usually the value returned by the last function called. A function call within another function is equivalent to a statement in other languages, and we use statement interchangeably with function call in this chapter. Here is the syntax for function:

(function-name argument1 argument2 ...)

which is equivalent to this:

method_name (argument1, argument2, ...);

in Java. This syntax is used for all functions, including those equivalent to arithmetic or comparison operators in other languages. For example, in order to add 2 and 4 in Java or Perl, you would use the expression 2 + 4, whereas in Lisp you would use the following:

(+ 2 4)

Similarly, where you would use 4 >= 2 (greater than or equal to), the Lisp equivalent is:

(>= 4 2)

Variables in Lisp are similar to those in any other language, except that they do not have types. A Lisp variable can assume any type of value (values themselves do have types, but variables don't impose restrictions on what they can hold).

Atoms are values of any type, including integers, floating point (real) numbers, characters, strings, Boolean truth values, symbols, and special Emacs types such as buffers, windows, and processes. The syntax for various kinds of atoms is:

• Integers are what you would expect: signed whole numbers in the range -2²⁷ to 2²⁷- 1.

• Floating point numbers are real numbers that you can represent with decimal points and scientific notation (with lowercase "e" for the power of 10). For example, the number 5489 can be written 5489, 5.489e3, 548.9e1, and so on.

• Characters are preceded by a question mark, for example,

?a

\e

\n

\t

\C-

?\C-a

• Strings are surrounded by double quotes; quote marks and backslashes within strings need to be preceded by a backslash. For example, "

Jane said, \"See Dick run.\"

• Booleans use

t

nil

nil

nil

• Symbols are names of things in Lisp, for example, names of variables or functions. Sometimes it is important to refer to the name of something instead of its value, and this is done by preceding the name with a single quote ('). For example, the define-key function, described in Chapter 10, uses the name of the command (as a symbol) rather than the command itself.

A simple example that ties many of these basic Lisp concepts together is the function setq.[76] As you may have figured out from previous chapters, setq is a way of assigning values to variables, as in

(setq auto-save-interval 800)

Notice that setq is a function, unlike in other languages in which special syntax such as

=

:=

800

setq can actually be used to assign values to multiple variables, as in

(setq thisvar thisvalue

   thatvar thatvalue

   theothervar theothervalue)

The return value of setq is simply the last value assigned, in this case

theothervalue

11.1.2 Defining Functions

Now it's time for an example of a simple function definition. Start Emacs without any arguments; this puts you into the

*scratch*

Before we get to the example, however, some more comments on Lisp syntax are necessary. First, you will notice that the dash (

-

_

The main problem a programmer faces is how to keep all the parentheses balanced properly. Compounding this problem is the usual programming convention of putting multiple right parentheses at the end of a line, rather than the more readable technique of placing each right parenthesis directly below its matching left parenthesis. Your best defense against this is the support the Emacs Lisp modes give you, particularly the Tab key for proper indentation and the flash-matching-parenthesis feature.

Now we're ready for our example function. Suppose you are a student or journalist who needs to keep track of the number of words in a paper or story you are writing. Emacs has no built-in way of counting the number of words in a buffer, so we'll write a Lisp function that does the job:

1 (defun count-words-buffer ( )

2  (let ((count 0))

3   (save-excursion

4    (goto-char (point-min))

5    (while (< (point) (point-max))

6     (forward-word 1)

7     (setq count (1+ count)))

8    (message "buffer contains %d words." count))))

Let's go through this function line by line and see what it does. (Of course, if you are trying this in Emacs, don't type the line numbers in.)

The defun on line 1 defines the function by its name and arguments. Notice that defun is itself a function—one that, when called, defines a new function. (defun returns the name of the function defined, as a symbol.) The function's arguments appear as a list of names inside parentheses; in this case, the function has no arguments. Arguments can be made optional by preceding them with the keyword &optional. If an argument is optional and not supplied when the function is called, its value is assumed to be nil.

Line 2 contains a let construct, whose general form is:

(let ((var1 value1) (var2 value2) ... )

 statement-block)

The first thing let does is define the variables

var1

var2

value1

value2

It is useful to think of let as doing three things:

• Defining (or declaring) a list of variables

• Setting the variables to initial values, as if with setq

• Creating a block in which the variables are known; the let block is known as the scope of the variables

If a let is used to define a variable, its value can be reset later within the let block with setq. Furthermore, a variable defined with let can have the same name as a global variable; all setqs on that variable within the let block act on the local variable, leaving the global variable undisturbed. However, a setq on a variable that is not defined with a let affects the global environment. It is advisable to avoid using global variables as much as possible because their names might conflict with those of existing global variables and therefore your changes might have unexpected and inexplicable side effects later on.

So, in our example function, we use let to define the local variable count and initialize it to 0. As we will see, this variable is used as a loop counter.

Lines 3 through 8 are the statements within the let block. The first of these calls the built-in Emacs function save-excursion, which is a way of being polite. The function is going to move the cursor around the buffer, so we don't want to disorient the user by jumping them to a strange place in their file just because they asked for a word count. Calling save-excursion tells Emacs to remember the location of cursor at the beginning of the function, and go back there after executing any statements in its body. Notice how save-excursion is providing us with capability similar to let; you can think of it as a way of making the cursor location itself a local variable.

Line 4 calls goto-char. The argument to goto-char is a (nested) function call to the built-in function point-min. As we have mentioned before, point is Emacs's internal name for the position of the cursor, and we'll refer to the cursor as point throughout the remainder of this chapter. point-min returns the value of the first character position in the current buffer, which is almost always 1; then, goto-char is called with the value 1, which has the effect of moving point to the beginning of the buffer.

The next line sets up a while loop; Java and Perl have a similar construct. The while construct has the general form

(while condition  statement-block)

Like let and save-excursion, while sets up another statement block. condition is a value (an atom, a variable, or a function returning a value). This value is tested; if it is

nil

nil

Of course, it is possible to write an infinite loop. If you write a Lisp function with a while loop and try running it, and your Emacs session hangs, chances are that you have made this all-too-common mistake; just type C-g to abort it.

In our sample function, the condition is the function

<

<

t

nil

The loop's statement block consists of two statements. Line 6 moves point forward one word (i.e., as if you had typed M-f). Line 7 increments the loop counter by 1; the function

1+

(+ 1 variable-name)

The final statement in the function uses the built-in function message to print a message in the minibuffer saying how many words the buffer contains. The form of the message function will be familiar to C programmers. The first argument to message is a format string, which contains text and special formatting instructions of the form

%x

x

message

Table 11-1. Message format strings

%s

%c

%d

%e

%f

%g

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

%

e

f

g

(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.

11.1.3 Turning Lisp Functions into Emacs Commands

The count-words-buffer function 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 defun function 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-j after 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]

(interactive "prompt-string")

This statement should be the first in a function, that is, right after the line containing the defun and the documentation string (which we will cover shortly). Using interactive causes Emacs to register the function as a command and to prompt the user for the arguments declared in the defun statement. 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

Table 11-2. Argument codes for interactive functions

b

e

f

n

s

B

F

N

S

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

The way interactive is 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

n

Percent:

As a slightly more complicated example, let's say we want to write our own version of the replace-string command. 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:

sReplace string %s with:

s

%s

When this command is invoked, first the prompt

Replace string:

fred

Replace fred with:

The two strings the user types are used as values of the function arguments from and to (in that order), and the command runs to completion. Thus, interactive supplies values to the function's arguments in the order of the sections of the prompt string.

The use of interactive does not preclude calling the function from other Lisp code; in this case, the calling function needs to supply values for all arguments. For example, if we were interested in calling our version of replace-string from another Lisp function that needs to replace all occurrences of "Bill" with "Deb" in a file, we would use

(replace-string "Bill" "Deb")

The function is not being called interactively in this case, so the interactive statement has no effect; the argument from is set to "Bill," and to is set to "Deb."

Getting back to our count-words-buffer command: it has no arguments, so its interactive command does not need a prompt string. The final modification we want to make to our command is to add a documentation string (or doc string for short), which is shown by online help facilities such as describe-function (C-h f). Doc strings are normal Lisp strings; they are optional and can be arbitrarily many lines long, although, by convention, the first line is a terse, complete sentence summarizing the command's functionality. Remember that any double quotes inside a string need to be preceded by backslashes.

With all of the fixes taken into account, the complete function looks like this:

(defun count-words-buffer ( )

 "Count the number of words in the current buffer;

print a message in the minibuffer with the result."

 (interactive)

 (save-excursion

  (let ((count 0))

   (goto-char (point-min))

   (while (< (point) (point-max))

    (forward-word 1)

    (setq count (1+ count)))

   (message "buffer contains %d words." count))))

Now that you've seen how to write a working command, we'll discuss Lisp's primitive functions. These are the building blocks from which you'll build your functions. As mentioned above, Lisp uses functions where other languages would use operators, that is, for arithmetic, comparison, and logic. Table 11-3 shows some Lisp primitive functions that are equivalent to these operators.

Table 11-3. Lisp primitive functions

+

-

*

/

%

1+

1-

max

min

>

<

>=

<=

/=

=

equal

and

or

not

All the arithmetic functions except

1+

1-

%

and

or

(/ 7.0 4)

(/ 7 4)

It may seem inefficient or syntactically ugly to use functions for everything. However, one of the main merits of Lisp is that the core of the language is small and easy to interpret efficiently. In addition, the syntax is not as much of a problem if you have support tools such as Emacs's Lisp modes to help you.

11.2.1 Statement Blocks

We have seen that a statement block can be defined using the let function. We also saw that while and save-excursion include statement blocks. Other important constructs also define statement blocks: progn and other forms of let.

progn, the most basic, has the form:

(progn

 statement-block)

progn is a simple way of making a block of statements look like a single one, somewhat like the curly braces of Java or the

begin

end

The let function has other forms as well. The simplest is:

(let (var1 var2 ...)

 statement-block)

In this case, instead of a list of

(var value)

nil

(let (var1 (var2 value2) var3 ...)

 statement-block)

In the form of let we saw first, the initial values for the local variables can be function calls (remember that all functions return values). All such functions are evaluated before any values are assigned to variables. However, there may be cases in which you want the values of some local variables to be available for computing the values of others. This is where let*, the final version of let, comes in. let* steps through its assignments in order, assigning each local variable a value before moving on to the next.

For example, let's say we want to write a function goto-percent that allows you to go to a place in the current buffer expressed as a percentage of the text in the buffer. Here is one way to write this function:

(defun goto-percent (pct)

 (interactive "nGoto percent: ")

 (let* ((size (point-max))

    (charpos (/ (* size pct) 100)))

  (goto-char charpos)))

As we saw earlier, the interactive function is used to prompt users for values of arguments. In this case, it prompts for the integer value of the argument pct. Then the let* function initializes size to the size of the buffer in characters, then uses that value to compute the character position charpos that is pct (percent) of the buffer's size. Finally, the call of goto-char causes point to be moved to that character position in the current window.

The important thing to notice is that if we had used let instead of let*, the value of size would not be available when computing the value of charpos. let* can also be used in the

(var1 var2 ...)

We should also note that a more efficient way to write goto-percent is this:

(defun goto-percent (pct)

 (interactive "nPercent: ")

 (goto-char (/ (* pct (point-max)) 100)))

11.2.2 Control Structures

We already saw that the while function acts as a control structure like similar statements in other languages. There are two other important control structures in Lisp: if and cond.

The if function has the form:

(if condition true-case false-block)

Here, the condition is evaluated; if it is non-nil,

true-case

false-block

true-case

false-block

false-block

As an example, let's suppose we're writing a function that performs some complicated series of edits to a buffer and then reports how many changes it made. We're perfectionists, so we want the status report to be properly pluralized, that is to say "made 53 changes" or "made 1 change." This is a common enough programming need that we decide to write a general-purpose function to do it so that we can use it in other projects too.

The function takes two arguments: the word to be pluralized (if necessary) and the count to be displayed (which determines whether it's necessary).

(defun pluralize (word count)

 (if (= count 1)

   word

  (concat word "s")))

The condition in the if clause tests to see if count is equal to 1. If so, the first statement gets executed. Remember that the "true" part of the if function is only one statement, so progn would be necessary to make a statement block if we wanted to do more than one thing. In this case, we have the opposite extreme; our "true" part is a single variable, word. Although this looks strange, it is actually a very common Lisp idiom and worth getting used to. When the condition block is true, the value of word is evaluated, and this value becomes the value of the entire if statement. Because that's the last statement in our function, it is the value returned by pluralize. Note that this is exactly the result we want when count is 1: the value of word is returned unchanged.

The remaining portion of the if statement is evaluated when the condition is false, which is to say, when count has a value other than 1. This results in a call to the built-in concat function, which concatenates all its arguments into a single string. In this case it adds an "s" at the end of the word we've passed in. Again, the result of this concatenation becomes the result of the if statement and the result of our pluralize function.

If you type it in and try it out, you'll see results like this:

(pluralize "goat" 5)

"goats"

(pluralize "change" 1)

"change"

Of course, this function can be tripped up easily enough. You may have tried something like this already:

(pluralize "mouse" 5)

"mouses"

To fix this, we'd need to be able to tell the function to use an alternate plural form for tricky words. But it would be nice if the simple cases could remain as simple as they are now. This is a good opportunity to use an optional parameter. If necessary, we supply the plural form to use; if we don't supply one, the function acts as it did in its first incarnation. Here's how we'd achieve that:

(defun pluralize (word count &optional plural)

 (if (= count 1)

   word

  (if (null plural)

    (concat word "s")

   plural)))

The "else" part of our code has become another if statement. It uses the null function to check whether we were given the plural parameter or not. If plural was omitted, it has the value nil and the null function returns t if its argument is nil. So this logic reads "if b was missing, just add an s to word; otherwise return the special plural value we were given."

This gives us results like this:

(pluralize "mouse" 5)

"mouses"

(pluralize "mouse" 5 "mice")

"mice"

(pluralize "mouse" 1 "mice")

"mouse"

A more general conditional control structure is the cond function, which has the following form:

(cond

 (condition1   statement-block1)

 (condition2   statement-block2)

 ...)

Java and Perl programmers can think of this as a sequence of if then else if then else if . . . , or as a kind of generalized switch statement. The conditions are evaluated in order, and when one of them evaluates to non-

nil

We can use cond to give a more folksy feel to our hypothetical status reporter now that it's pluralizing nicely. Instead of reporting an actual numeric value for the number of changes, we could have it say no, one, two, or many as appropriate. Again we'll write a general function to do this:

(

defun how-many (count)

 (cond ((zerop count) "no")

    ((= count 1) "one")

    ((= count 2) "two")

    (t "many")))

The first conditional expression introduces a new primitive Lisp function, zerop. It checks whether its argument is zero, and returns

t

The next two conditional expressions in the cond statement check if count is 1 or 2 and cause it to return "one" or "two" as appropriate. We could have written the first one using the same structure, but then we'd have missed out on an opportunity for a digression into Lisp trivia!

The last conditional expression is simply the atom t (true), which means its body is executed whenever all the preceding expressions failed. It returns the value many. Executing this function gives us results like these:

(how-many 1)

"one"

(how-many 0)

"no"

(how-many 3)

"many"

Combining these two helper functions into a mechanism to report the change count for our fancy command is easy.

(defun report-change-count (count)

 (message "Made %s %s." (how-many count) (pluralize "change" count)))

We get results like these:

(report-change-count 0)

"Made no changes."

(report-change-count 1)

"Made one change."

(report-change-count 1329)

"Made many changes."

Many of the Emacs functions that exist and that you may write involve searching and manipulating the text in a buffer. Such functions are particularly useful in specialized modes, like the programming language modes described in Chapter 9. Many built-in Emacs functions relate to text in strings and buffers; the most interesting ones take advantage of Emacs's regular expression facility, which we introduced in Chapter 3.

We first describe the basic functions relating to buffers and strings that don't use regular expressions. Afterwards, we discuss regular expressions in more depth than was the case in Chapter 3, concentrating on the features that are most useful to Lisp programmers, and we describe the functions that Emacs makes available for dealing with regular expressions.

11.3.1 Buffers, Text, and Regions

Table 11-4 shows some basic Emacs functions relating to buffers, text, and strings that are only useful to Lisp programmers and thus aren't bound to keystrokes. We already saw a couple of them in the count-words-buffer example. Notice that some of these are predicates, and their names reflect this.

Table 11-4. Buffer and text functions

t

nil

(substring "appropriate" 2 5)

pro

(aref "appropriate" 3)

r

Many functions not included in the previous table deal with buffers and text, including some that you should be familiar with as user commands. Several commonly used Emacs functions use regions, which are areas of text within a buffer. When you are using Emacs, you delineate regions by setting the mark and moving the cursor. However, region-oriented functions (such as kill-region, indent-region, and shell-command-on-region—really, any function with region in its name) are actually more flexible when used within Emacs Lisp code. They typically take two integer arguments that are used as the character positions of the boundaries for the region on which they operate. These arguments default to the values of point and mark when the functions are called interactively.

Obviously, allowing point and mark as interactive defaults is a more general (and thus more desirable) approach than one in which only point and mark can be used to delineate regions. The r option to the interactive function makes it possible. For example, if we wanted to write the function translate-region-into-German, here is how we would start:

(defun translate-region-into-German (start end)

 (interactive "r")

 ...

The r option to interactive fills in the two arguments start and end when the function is called interactively, but if it is called from other Lisp code, both arguments must be supplied. The usual way to do this is like this:

(translate-region-into-German (point) (mark))

But you need not call it in this way. If you wanted to use this function to write another function called translate-buffer-into-German, you would only need to write the following as a "wrapper":

(defun translate-buffer-into-German ( )

 (translate-region-into-German (point-min) (point-max)))

In fact, it is best to avoid using point and mark within Lisp code unless doing so is really necessary; use local variables instead. Try not to write Lisp functions as lists of commands a user would invoke; that sort of behavior is better suited to macros (see Chapter 6).

11.3.2 Regular Expressions

read

readfile

get

.

?

.*

*

[abc]

[abc]

a

b

c

[a-z]

[a-z]

program*

program.*

[a-e]*

[abcde]*

[a-e].*

[abcde].*

\\*

(replace-regexp "fred\\*" "bob*")

fred\\*

fred\*

fred\*

fred

bob*

*

*

*

.*

*

read*

file[0-9]*

*

+

read+

file[0-9]+

?

html?

file[0-9]?

[A-Za-z]

[A-z]

[A-Za-z_]

^

^

[^A-Za-z]

^

-

]

^

*

+

?

\\(

\\)

\\)

\\(

\\)

\\(read\\)*

read\\(file\\)?

(replace-regexp "read\\(file\\)?" "get")

\\|

\\|

\\(

\\)

\\|

read\\|get

readfile\\|read\\|get

\\(read\\|get\\)file

\\|

\\|

\\|

^

$

^

$

(defun remove-outline-marks ( )

 "Remove section header marks created in outline-mode."

 (interactive)

 (replace-regexp "^\\*+" ""))

\\*

+

^

$

\n

\t

^

$

"[.?!][]\"')}]*\\($\\|\t\\| \\)[ \t\n]*"

[.?!]

[]\"')}]*

*

\\($\\|\t\\| \\)

$

Tab

[ \t\n]*

^

$

\\<

\\>

\\

\\

s

's

module\\1

(replace-regexp "\\" "module\\1")

\\1

\\(

\\)

's

s

(replace-regexp "\\([a-zA-Z0-9_]+\\)\\.c" "\\1.java")

\\.

\\(

\\)

\\1

\\1

\\(

\\)

\\n

n

\\n

\\(

(defvar compilation-error-regexp-alist

 '(

  ;; NOTE! See also grep-regexp-alist, below.

  ;; 4.3BSD grep, cc, lint pass 1:

  ;; /usr/src/foo/foo.c(8): warning: w may be used before set

  ;; or GNU utilities:

  ;; foo.c:8: error message

  ;; or HP-UX 7.0 fc:

  ;; foo.f :16 some horrible error message

  ;; or GNU utilities with column (GNAT 1.82):

  ;; foo.adb:2:1: Unit name does not match file name

  ;; or with column and program name:

  ;; jade:dbcommon.dsl:133:17:E: missing argument for function call

  ;;

  ;; We'll insist that the number be followed by a colon or closing

  ;; paren, because otherwise this matches just about anything

  ;; containing a number with spaces around it.

  ;; We insist on a non-digit in the file name

  ;; so that we don't mistake the file name for a command name

  ;; and take the line number as the file name.

  ("\\([a-zA-Z][-a-zA-Z._0-9]+: ?\\)?\

\\([a-zA-Z]?:?[^:( \t\n]*[^:( \t\n0-9][^:( \t\n]*\\)[:(][ \t]*\\([0-9]+\\)\

\\([) \t]\\|:\\(\\([0-9]+:\\)\\|[0-9]*[^:0-9]\\)\\)" 2 3 6)

;; Microsoft C/C++:

  ;; keyboard.c(537) : warning C4005: 'min' : macro redefinition

  ;; d:\tmp\test.c(23) : error C2143: syntax error : missing ';' before 'if'

  ;; This used to be less selective and allow characters other than

  ;; parens around the line number, but that caused confusion for

  ;; GNU-style error messages.

  ;; This used to reject spaces and dashes in file names,

  ;; but they are valid now; so I made it more strict about the error

  ;; message that follows.

  ("\\(\\([a-zA-Z]:\\)?[^:(\t\n]+\\)(\\([0-9]+\\)) \

: \\(error\\|warning\\) C[0-9]+:" 1 3)

;; Caml compiler:

  ;; File "foobar.ml", lines 5-8, characters 20-155: blah blah

  ("^File \"\\([^,\" \n\t]+\\)\", lines? \\([0-9]+\\)[-0-9]*, characters? \

\\([0-9]+\\)" 1 2 3)

;; Cray C compiler error messages

  ("\\(cc\\| cft\\)-[0-9]+ c\\(c\\|f77\\): ERROR \\([^,\n]+, \\)* File = \

\\([^,\n]+\\), Line = \\([0-9]+\\)" 4 5)

;; Perl -w:

  ;; syntax error at automake line 922, near "':'"

  ;; Perl debugging traces

  ;; store::odrecall('File_A', 'x2') called at store.pm line 90

  (".* at \\([^ \n]+\\) line \\([0-9]+\\)[,.\n]" 1 2)

  ;; See http://ant.apache.org/faq.html

  ;; Ant Java: works for jikes

  ("^\\s-*\\[[^]]*\\]\\s-*\\(.+\\):\\([0-9]+\\):\\([0-9]+\\):[0-9]+:[0-9]\

+:" 1 2 3)

  ;; Ant Java: works for javac

  ("^\\s-*\\[[^]]*\\]\\s-*\\(.+\\):\\([0-9]+\\):" 1 2)

)

".* at \\([^ \n]+\\) line \\([0-9]+\\)[,.\n]"

syntax error at monthly_orders.pl line 1822, near "$"

[^ \n]+

[0-9]+

Fehler auf Zeile linenum in filename: text of error message

("Fehler auf Zeile \\([0-9]+\\) in \\([^: \t]+\\):" 2 1)

(setq compilation-error-regexp-alist

 (cons '("Fehler auf Zeile \\([0-9]+\\) in \\([^: \t]+\\):" 2 1)

  compilation-error-regexp-alist))

.

*

+

?

[...]

\\(

\\)

\\|

^

$

\n

\t

\\<

\\>

^

-

\\n

n

\\(

\\)

\\(

b

B

c

C

w

W

s

S

=

_

'

`

11.3.3 A Treasure Trove of Examples

As mentioned above, the full auto-mode-alist has a lot more entries and documentation than fit in this book. The compile.el module in which it is defined also contains functions that use it. One of the best ways to learn how to use Emacs Lisp (as well as discovering things you might not have even realized you can do) is to browse through the implementations of standard modules that are similar to what you're trying to achieve, or that are simply interesting. But how do you find them?

The manual way is to look at the value of the variable load-path. This is the variable Emacs consults when it needs to load a library file itself, so any library you're looking for must be in one of these directories. (This variable is discussed further in the final section of this chapter.) The problem, as you will see if you look at the current value of the variable, is that it contains a large number of directories for you to wade through, which would be pretty tedious each time you're curious about a library. (An easy way to see the variable's value is through Help's "Describe variable" feature, C-h v.)

One of the authors wrote the command listed in Example 11-1 to address this problem and uses it regularly to easily snoop on the source files that make much of Emacs run. If you don't want to type this entire function into your .emacs by hand, you can download it from this book's web site, http://www.oreilly.com/catalog/gnu3.

Example 11-1. find-library-file

(defun find-library-file (library)

 "Takes a single argument LIBRARY, being a library file to search for.

Searches for LIBRARY directly (in case relative to current directory,

or absolute) and then searches directories in load-path in order. It

will test LIBRARY with no added extension, then with .el, and finally

with .elc. If a file is found in the search, it is visited. If none

is found, an error is signaled. Note that order of extension searching

is reversed from that of the load function."

 (interactive "sFind library file: ")

 (let ((path (cons "" load-path)) exact match elc test found)

  (while (and (not match) path)

   (setq test (concat (car path) "/" library)

      match (if (condition-case nil

             (file-readable-p test)

            (error nil))

           test)

      path (cdr path)))

 (setq path (cons "" load-path))

 (or match

   (while (and (not elc) path)

    (setq test (concat (car path) "/" library ".elc")

       elc (if (condition-case nil

             (file-readable-p test)

            (error nil))

           test)

       path (cdr path))))

 (setq path (cons "" load-path))

 (while (and (not match) path)

  (setq test (concat (car path) "/" library ".el")

     match (if (condition-case nil

            (file-readable-p test)

           (error nil))

          test)

     path (cdr path)))

 (setq found (or match elc))

 (if found

   (progn

    (find-file found)

    (and match elc

       (message "(library file %s exists)" elc)

       (sit-for 1))

    (message "Found library file %s" found))

  (error "Library file \"%s\" not found." library))))

Once this command is defined, you can visit any library's implementation by typing M-x find-library file Enter

libraryname

If you find that most of the time when you ask for a library, you end up with a file containing a lot of cryptic numeric codes and no comments, check if the filename ends in .elc. If that is usually what you end up with, it means that only the byte-compiled versions of the libraries (see the discussion at the end of this chapter) have been installed on your system. Ask your system administrator if you can get the source installed; that's an important part of being able to learn and tweak the Emacs Lisp environment.

11.3.4 Functions That Use Regular Expressions

The functions re-search-forward, re-search-backward, replace-regexp, query-replace-regexp, highlight-regexp, isearch-forward-regexp, and isearch-backward-regexp are all user commands that use regular expressions, and they can all be used within Lisp code (though it is hard to imagine incremental search being used within Lisp code). The section on customizing major modes later in this chapter contains an example function that uses re-search-forward. To find other commands that use regexps you can use the "apropos" help feature (C-h a regexp Enter).

Other such functions aren't available as user commands. Perhaps the most widely used one is looking-at. This function takes a regular expression argument and does the following: it returns

t

nil

\\(

\\)

nil

The functions match-beginning and match-end can be used to retrieve the saved portions of the matched string. Each takes as an argument the number of the matched expression (as in

\\n

0

Two more functions are needed to make the above useful: we need to know how to convert the text in a buffer to a string. No problem: buffer-string returns the entire buffer as a string; buffer-substring takes two integer arguments, marking the beginning and end positions of the substring desired, and returns the substring.

With these functions, we can write a bit of Lisp code that returns a string containing the portion of the buffer that matches the

n

(buffer-substring (match-beginning n (match-end n)))

In fact, this construct is used so often that Emacs has a built-in function, match-string, that acts as a shorthand;

(match-string n)

An example should show how this capability works. Assume you are writing the Lisp code that parses compiler error messages, as in our previous example. Your code goes through each element in compilation-error-regexp-alist, checking if the text in a buffer matches the regular expression. If it matches, your code needs to extract the filename and the line number, visit the file, and go to the line number.

Although the code for going down each element in the list is beyond what we have learned so far, the routine basically looks like this:

for each element in compilation-error-regexp-alist

 (let ((regexp the regexp in the element)

    (file-subexp the number of the filename subexpression)

    (line-subexp the number of the line number subexpression))

  (if (looking-at regexp)

    (let ((filename (match-string file-subexp))

       (linenum (match-string line-subexp)))

     (find-file-other-window filename)

     (goto-line linenum))

   (otherwise, try the next element in the list)))

The second let extracts the filename from the buffer from the beginning to the end of the match to the

file-subexp

line-subexp

The code for the calculator mode later in this chapter contains a few other examples of looking-at, match-beginning, and match-end.

11.3.5 Finding Other Built-in Functions

Emacs contains hundreds of built-in functions that may be of use to you in writing Lisp code. Yet finding which one to use for a given purpose is not so hard.

The first thing to realize is that you will often need to use functions that are already accessible as keyboard commands. You can use these by finding out what their function names are via the C-h k (for describe-key) command (see Chapter 14). This gives the command's full documentation, as opposed to C-h c (for describe-key-briefly), which gives only the command's name. Be careful: in a few cases, some common keyboard commands require an argument when used as Lisp functions. An example is forward-word; to get the equivalent of typing M-f, you have to use

(forward-word 1)

Another powerful tool for getting the right function for the job is the command-apropos (C-h a) help function. Given a regular expression, this help function searches for all commands that match it and display their key bindings (if any) and documentation in a

*Help*

a

word

The limitation with command-apropos is that it gives information only on functions that can be used as keyboard commands. Even more powerful is apropos, which is not accessible via any of the help keys (you must type M-x apropos Enter). Given a regular expression, apropos displays all functions, variables, and other symbols that match it. Be warned, though: apropos can take a long time to run and can generate very long lists if you use it with a general enough concept (such as buffer).

You should be able to use the apropos commands on a small number of well-chosen keywords and find the function(s) you need. Because, if a function seems general and basic enough, the chances are excellent that Emacs has it built-in.

After you find the function you are interested in, you may find that the documentation that apropos prints does not give you enough information about what the function does, its arguments, how to use it, or whatever. The best thing to do at this point is to search Emacs's Lisp source code for examples of the function's use. "A Treasure Trove of Examples" earlier in this chapter provides ways of finding out the names of directories Emacs loads libraries from and an easy way of looking at a library once you know its name. To search the contents of the library files you'll need to use grep or some other search facility to find examples, then edit the files found to look at the surrounding context. If you're ambitious you could put together the examples and concepts we've discussed so far to write an extension of the find-library-file command that searches the contents of the library files in each directory on the load path! Although most of Emacs's built-in Lisp code is not profusely documented, the examples of function use that it provides should be helpful—and may even give you ideas for your own functions.

By now, you should have a framework of Emacs Lisp that should be sufficient for writing many useful Emacs commands. We have covered examples of various kinds of functions, both Lisp primitives and built-in Emacs functions. You should be able to extrapolate many others from the ones given in this chapter along with help techniques such as those just provided. In other words, you are well on your way to becoming a fluent Emacs Lisp programmer. To test yourself, start with the code for count-words-buffer and try writing the following functions:

count-lines-buffer

Print the number of lines in the buffer.

count-words-region

Print the number of words in a region.

what-line

Print the number of the line point is currently on.

After you get comfortable with Emacs Lisp programming, you may find that that "little extra something" you want Emacs to do takes the form of a major mode. In previous chapters, we covered major modes for text entry, word processor input, and programming languages. Many of these modes are quite complicated to program, so we'll provide a simple example of a major mode, from which you can learn the concepts needed to program your own. Then, in the following section, you will learn how you can customize existing major modes without changing any of the Lisp code that implements them.

We'll develop Calculator mode, a major mode for a calculator whose functionality will be familiar to you if you have used the Unix dc (desk calculator) command. It is a Reverse Polish (stack-based) calculator of the type made popular by Hewlett-Packard. After explaining some of the principal components of major modes and some interesting features of the calculator mode, we will give the mode's complete Lisp code.

11.5.1 Components of a Major Mode

A major mode has various components that integrate it into Emacs. Some are:

• The symbol that is the name of the function that implements the mode

• The name of the mode that appears in the mode line in parentheses

• The local keymap that defines key bindings for commands in the mode

• Variables and constants known only within the Lisp code for the mode

• The special buffer the mode may use

Let's deal with these in order. The mode symbol is set by assigning the name of the function that implements the mode to the global variable major-mode, as in:

(setq major-mode 'calc-mode)

Similarly, the mode name is set by assigning an appropriate string to the global variable

mode-name

(setq mode-name "Calculator")

The local keymap is defined using functions discussed in Chapter 10. In the case of the calculator mode, there is only one key sequence to bind (C-j), so we use a special form of the make-keymap command called make-sparse-keymap that is more efficient with a small number of key bindings. To use a keymap as the local map of a mode, we call the function use-local-map, as in:

(use-local-map calc-mode-map)

As we just saw, variables can be defined by using

setq

(defvar varname initial-value "description of the variable")

A variation on this is

defconst

(defconst calc-operator-regexp "[-+*/%]"

 "Regular expression for recognizing operators.")

defines the regular expression to be used in searching for arithmetic operators. As you will see, we use the calc- as a prefix for the names of all functions, variables, and constants that we define for the calculator mode. Other modes use this convention; for example, all names in C++ mode begin with

c++-

Making variables local to the mode is also desirable so that they are known only within a buffer that is running the mode.[80] To do this, use the make-local-variable function, as in:

(make-local-variable 'calc-stack)

Notice that the name of the variable, not its value, is needed; therefore a single quote precedes the variable name, turning it into a symbol.

Finally, various major modes use special buffers that are not attached to files. For example, the C-x C-b (for list-buffers) command creates a buffer called

*Buffer List*

(pop-to-buffer "*Calc*")

There are a couple of useful variations on pop-to-buffer. We won't use them in our mode example, but they are handy in other circumstances.

switch-to-buffer

Same as the C-x b command covered in Chapter 4; can also be used with a buffer name argument in Lisp.

set-buffer

Used only within Lisp code to designate the buffer used for editing; the best function to use for creating a temporary "work" buffer within a Lisp function.

11.5.2 More Lisp Basics: Lists

A Reverse Polish Notation calculator uses a data structure called a stack. Think of a stack as being similar to a spring-loaded dish stack in a cafeteria. When you enter a number into a RPN calculator, you push it onto the stack. When you apply an operator such as plus or minus, you pop the top two numbers off the stack, add or subtract them, and push the result back on the stack.

The list, a fundamental concept of Lisp, is a natural for implementing stacks. The list is the main concept that sets Lisp apart from other programming languages. It is a data structure that has two parts: the head and tail. These are known in Lisp jargon, for purely historical reasons, as car and cdr respectively. Think of these terms as "the first thing in the list" and "the rest of the list." The functions car and cdr, when given a list argument, return the head and tail of it, respectively.[81] Two functions are often used for making lists. cons (construct) takes two arguments, which become the head and tail of the list respectively. list takes a list of elements and makes them into a list. For example, this:

(list 2 3 4 5)

makes a list of the numbers from 2 to 5, and this:

(cons 1 (list 2 3 4 5))

makes a list of the numbers from 1 to 5. car applied to that list would return

1

(2 3 4 5)

These concepts are important because stacks, such as that used in the calculator mode, are easily implemented as lists. To push the value of x onto the stack calc-stack, we can just say this:

(setq calc-stack (cons x calc-stack))

If we want to get at the value at the top of the stack, the following returns that value:

(car calc-stack)

To pop the top value off the stack, we say this:

(setq calc-stack (cdr calc-stack))

Bear in mind that the elements of a list can be anything, including other lists. (This is why a list is called a recursive data structure.) In fact (ready to be confused?) just about everything in Lisp that is not an atom is a list. This includes functions, which are basically lists of function name, arguments, and expressions to be evaluated. The idea of functions as lists will come in handy very soon.

11.5.3 The Calculator Mode

The complete Lisp code for the calculator mode appears at the end of this section; you should refer to it while reading the following explanation. If you download or type the code in, you can use the calculator by typing M-x calc-mode Enter. You will be put in the buffer

*Calc*

Table 11-7. Calculator mode commands

=

p

c

Blank spaces are not necessary, except to separate numbers. For example, typing this:

4 17*6-=

followed by C-j, evaluates (4 * 17) - 6 and causes the result, 62, to be printed.

The heart of the code for the calculator mode is the functions calc-eval and calc-next-token. (See the code at the end of this section for these.) calc-eval is bound to C-j in Calculator mode. Starting at the beginning of the line preceding C-j, it calls calc-next-token to grab each token (number, operator, or command letter) in the line and evaluate it.

calc-next-token uses a cond construct to see if there is a number, operator, or command letter at point by using the regular expressions calc-number-regexp, calc-operator-regexp, and calc-command-regexp. According to which regular expression was matched, it sets the variable calc-proc-fun to the name (symbol) of the function that should be run (either calc-push-number, calc-operate, or calc-command), and it sets

tok

In calc-eval, we see where the idea of a function as a list comes in. The funcall function reflects the fact that there is little difference between code and data in Lisp. We can put together a list consisting of a symbol and a bunch of expressions and evaluate it as a function, using the symbol as the function name and the expressions as arguments; this is what funcall does. In this case, the following:

(funcall calc-proc-fun tok)

treats the symbol value of calc-proc-fun as the name of the function to be called and calls it with the argument

tok

• If the token is a number, calc-push-number pushes the number onto the stack.

• If the token is an operator, calc-operate performs the operation on the top two numbers on the stack (see below).

• If the token is a command, calc-command performs the appropriate command.

The function calc-operate takes the idea of functions as lists of data a step further by converting the token from the user directly into a function (an arithmetic operator). This step is accomplished by the function read, which takes a character string and converts it into a symbol. Thus, calc-operate uses funcall and read in combination as follows:

(defun calc-operate (tok)

 (let ((op1 (calc-pop))

    (op2 (calc-pop)))

  (calc-push (funcall (read tok) op2 op1))))

This function takes the name of an arithmetic operator (as a string) as its argument. As we saw earlier, the string

tok

*Calc*

+

*

cdr

+

(funcall '+ op2 op1)

Thus, the function + is called with the two arguments, which is exactly equivalent to simply (+ op2 op1). Finally, the result of the function is pushed back onto the stack.

All this voodoo is necessary so that, for example, the user can type a plus sign and Lisp automatically converts it into a plus function. We could have done the same thing less elegantly—and less efficiently—by writing calc-operate with a cond construct (as in calc-next-token), which would look like this:

(defun calc-operate (tok)

 (let ((op1 (calc-pop))

    (op2 (calc-pop)))

  (cond ((equal tok "+")

      (+ op2 op1))

     ((equal tok "-")

      (- op2 op1))

     ((equal tok "*")

      (* op2 op1))

     ((equal tok "/")

      (/ op2 op1))

     (t

      (% op2 op1)))))

The final thing to notice in the calculator mode code is the function calc-mode, which starts the mode. It creates (and pops to) the

*Calc*

nil

11.5.4 Lisp Code for the Calculator Mode

Now you should be able to understand all of the code for the calculator mode. You will notice that there really isn't that much code at all! This is testimony to the power of Lisp and the versatility of built-in Emacs functions. Once you understand how this mode works, you should be ready to start rolling your own. Without any further ado, here is the code:

;; Calculator mode.

;;

;; Supports the operators +, -, *, /, and % (remainder).

;; Commands: ;; c clear the stack

;; = print the value at the top of the stack

;; p print the entire stack contents

;;

(defvar calc-mode-map nil

 "Local keymap for calculator mode buffers.")

; set up the calculator mode keymap with

; C-j (linefeed) as "eval" key

(if calc-mode-map

  nil

 (setq calc-mode-map (make-sparse-keymap))

 (define-key calc-mode-map "\C-j" 'calc-eval))

(defconst calc-number-regexp

 "-?\\([0-9]+\\.?\\|\\.\\)[0-9]*\\(e[0-9]+\\)?"

 "Regular expression for recognizing numbers.")

(defconst calc-operator-regexp "[-+*/%]"

 "Regular expression for recognizing operators.")

(defconst calc-command-regexp "[c=ps]"

 "Regular expression for recognizing commands.")

(defconst calc-whitespace "[ \t]"

 "Regular expression for recognizing whitespace.")

;; stack functions

(defun calc-push (num)

 (if (numberp num)

 (setq calc-stack (cons num calc-stack))))

(defun calc-top ( )

 (if (not calc-stack)

   (error "stack empty.")

  (car calc-stack)))

(defun calc-pop ( )

 (let ((val (calc-top)))

  (if val

   (setq calc-stack (cdr calc-stack)))

  val))

;; functions for user commands:

(defun calc-print-stack ( )

 "Print entire contents of stack, from top to bottom."

 (if calc-stack

   (progn

    (insert "\n")

    (let ((stk calc-stack))

     (while calc-stack

      (insert (number-to-string (calc-pop)) " "))

     (setq calc-stack stk)))

  (error "stack empty.")))

(defun calc-clear-stack ( )

 "Clear the stack."

 (setq calc-stack nil)

 (message "stack cleared."))

(defun calc-command (tok)

 "Given a command token, perform the appropriate action."

 (cond ((equal tok "c")

     (calc-clear-stack))

    ((equal tok "=")

     (insert "\n" (number-to-string (calc-top))))

    ((equal tok "p")

     (calc-print-stack))

    (t

     (message (concat "invalid command: " tok)))))

(defun calc-operate (tok)

 "Given an arithmetic operator (as string), pop two numbers

off the stack, perform operation tok (given as string), push

the result onto the stack."

 (let ((op1 (calc-pop))

    (op2 (calc-pop)))

  (calc-push (funcall (read tok) op2 op1))))

(defun calc-push-number (tok)

 "Given a number (as string), push it (as number)

onto the stack."

 (calc-push (string-to-number tok)))

(defun calc-invalid-tok (tok)

 (error (concat "Invalid token: " tok))

(defun calc-next-token ( )

 "Pick up the next token, based on regexp search.

As side effects, advance point one past the token,

and set name of function to use to process the token."

 (let (tok)

  (cond ((looking-at calc-number-regexp)

      (goto-char (match-end 0))

      (setq calc-proc-fun 'calc-push-number))

     ((looking-at calc-operator-regexp)

      (forward-char 1)

      (setq calc-proc-fun 'calc-operate))

     ((looking-at calc-command-regexp)

      (forward-char 1)

      (setq calc-proc-fun 'calc-command))

     ((looking-at ".")

         (forward-char 1)

      (setq calc-proc-fun 'calc-invalid-tok)))

  ;; pick up token and advance past it (and past whitespace)

  (setq tok (buffer-substring (match-beginning 0) (point)))

  (if (looking-at calc-whitespace)

   (goto-char (match-end 0)))

  tok))

(defun calc-eval ( )

 "Main evaluation function for calculator mode.

Process all tokens on an input line."

 (interactive)

 (beginning-of-line)

 (while (not (eolp))

  (let ((tok (calc-next-token)))

   (funcall calc-proc-fun tok)))

 (insert "\n"))

(defun calc-mode ( )

 "Calculator mode, using H-P style postfix notation.

Understands the arithmetic operators +, -, *, / and %,

plus the following commands:

  c clear stack

  = print top of stack

  p print entire stack contents (top to bottom)

Linefeed (C-j) is bound to an evaluation function that

will evaluate everything on the current line. No

whitespace is necessary, except to separate numbers."

 (interactive)

 (pop-to-buffer "*Calc*" nil)

 (kill-all-local-variables)

 (make-local-variable 'calc-stack)

 (setq calc-stack nil)

 (make-local-variable 'calc-proc-fun)

 (setq major-mode 'calc-mode)

 (setq mode-name "Calculator")

 (use-local-map calc-mode-map))

The following are some possible extensions to the calculator mode, offered as exercises. If you try them, you will increase your understanding of the mode's code and Emacs Lisp programming in general.

• Add an operator

^

4 5 ^

1024

expt

• Add support for octal (base 8) and/or hexadecimal (base 16) numbers. An octal number has a leading "0," and a hexadecimal has a leading "0x"; thus, 017 equals decimal 15, and 0x17 equals decimal 23.

• Add operators

\+

\*

4 5 6 \+

15

4 5 6 \*

120

• As an additional test of your knowledge of list handling in Lisp, complete the example (Example 5) from earlier in this chapter that searches compilation-error-regexp-alist for a match to a compiler error message. (Hint: make a copy of the list, then pick off the top element repeatedly until either a match is found or the list is exhausted.)

After you have become proficient at Emacs Lisp programming, you will want a library of Lisp functions and packages that you can call up from Emacs at will. Of course, you can define a few small functions in your .emacs file, but if you are writing bigger pieces of code for more specialized purposes, you will not want to clutter up your .emacs file—nor will you want Emacs to spend all that time evaluating the code each time you start it up. The answer is to build your own Lisp library, analogous to the Lisp directories that come with Emacs and contain all of its built-in Lisp code. After you have created a library, you can load whatever Lisp packages you need at a given time and not bother with the others.

Creating a library requires two simple steps. First, create a directory in which your Lisp code will reside. Most people create a elisp subdirectory of their home directory. Lisp files are expected to have names ending in .el (your .emacs file is an exception). The second step is to make your directory known to Emacs so that when you try to load a Lisp package, Emacs knows where to find it. Emacs keeps track of such directories in the global variable load-path, which is a list of strings that are directory names.

The initial value for load-path is populated with the names of the Lisp directories that come with Emacs, e.g., /usr/local/emacs/lisp. You will need to add the name of your own Lisp directory to load-path. One way to make this addition is to use the Lisp function append, which concatenates any number of list arguments together. For example, if your Lisp directory is ~/lisp, you would put the following in your .emacs file:

(setq load-path (append load-path (list "~yourname/lisp")))

The function list is necessary because all of the arguments to append must be lists. This line of code must precede any commands in your .emacs file that load packages from your Lisp directory.

When you load a library, Emacs searches directories in the order in which they appear in load-path; therefore, in this case, Emacs searches its default Lisp directory first. If you want your directory to be searched first, you should use the cons function described earlier instead of append, as follows:

(setq load-path (cons "~yourname/lisp" load-path))

This form is useful if you want to replace one of the standard Emacs packages with one of your own. For example, you'd use this form if you've written your own version of C mode and want to use it instead of the standard package. Notice that the directory name here is not surrounded by a call to list because cons's first argument can be an atom (a string in this case). This situation is similar to the use of cons for pushing values onto stacks, as in the calculator mode described earlier.

If you want Emacs to search the directory you happen to be in at any given time, simply add

nil

.

After you have created a private Lisp library and told Emacs where to find it, you're ready to load and use the Lisp packages that you've created. There are several ways of loading Lisp packages into Emacs. The first of these should be familiar from Chapter 10:

• Type M-x load-library Enter as a user command; see Chapter 10.

• Put the line

(load "package-name")

• Invoke Emacs with the command-line option

"-l package-name"

package-name

• Put the line

(autoload 'function "filename")

function

11.7.1 Byte-Compiling Lisp Files

After you have created your Lisp directory, you can make loading and running your Lisp files more efficient by byte-compiling them, or translating their code into byte code, a more compact, machine-readable form. Byte-compiling the Lisp file filename.el creates the byte code file filename.elc. Byte code files are typically 40 to 75 percent of the size of their non-byte-compiled counterparts.

Although byte-compiled files are more efficient, they are not strictly necessary. The load-library command, when given the argument

filename

You can byte-compile a single function in a buffer of Lisp code by placing your cursor anywhere in the function and typing M-x compile-defun. You can byte-compile an entire file of Lisp by invoking M-x byte-compile-file Enter and supplying the filename. If you omit the .el suffix, Emacs appends it and asks for confirmation. If you have changed the file but have not saved it, Emacs offers to save it first.

Then you will see an entertaining little display in the minibuffer as the byte-compiler does its work: the names of functions being compiled flash by. The byte-compiler creates a file with the same name as the original Lisp file but with

c

Finally, if you develop a directory with several Lisp files, and you make changes to some of them, you can use the byte-recompile-directory command to recompile only those Lisp files that have been changed since being byte-compiled (analogously to the Unix make utility). Just type M-x byte-recompile-directory Enter and supply the name of the Lisp directory or just press Enter for the default, which is the current directory.