An Introduction to Programming in Emacs Lisp

2.1 Buffer Names

The two functions, buffer-name and buffer-file-name, show the difference between a file and a buffer. When you evaluate the following expression, (buffer-name), the name of the buffer appears in the echo area. When you evaluate (buffer-file-name), the name of the file to which the buffer refers appears in the echo area. Usually, the name returned by (buffer-name) is the same as the name of the file to which it refers, and the name returned by (buffer-file-name) is the full path-name of the file.

A file and a buffer are two different entities. A file is information recorded permanently in the computer (unless you delete it). A buffer, on the other hand, is information inside of Emacs that will vanish at the end of the editing session (or when you kill the buffer). Usually, a buffer contains information that you have copied from a file; we say the buffer is visiting that file. This copy is what you work on and modify. Changes to the buffer do not change the file, until you save the buffer. When you save the buffer, the buffer is copied to the file and is thus saved permanently.

If you are reading this in Info inside of GNU Emacs, you can evaluate each of the following expressions by positioning the cursor after it and typing C-x C-e.

(buffer-name)

(buffer-file-name)

When I do this in Info, the value returned by evaluating (buffer-name) is "*info*", and the value returned by evaluating (buffer-file-name) is nil.

On the other hand, while I am writing this document, the value returned by evaluating (buffer-name) is "introduction.texinfo", and the value returned by evaluating (buffer-file-name) is "/gnu/work/intro/introduction.texinfo".

The former is the name of the buffer and the latter is the name of the file. In Info, the buffer name is "*info*". Info does not point to any file, so the result of evaluating (buffer-file-name) is nil. The symbol nil is from the Latin word for “nothing”; in this case, it means that the buffer is not associated with any file. (In Lisp, nil is also used to mean “false” and is a synonym for the empty list, ().)

When I am writing, the name of my buffer is "introduction.texinfo". The name of the file to which it points is "/gnu/work/intro/introduction.texinfo".

(In the expressions, the parentheses tell the Lisp interpreter to treat buffer-name and buffer-file-name as functions; without the parentheses, the interpreter would attempt to evaluate the symbols as variables. See Variables.)

In spite of the distinction between files and buffers, you will often find that people refer to a file when they mean a buffer and vice versa. Indeed, most people say, “I am editing a file,” rather than saying, “I am editing a buffer which I will soon save to a file.” It is almost always clear from context what people mean. When dealing with computer programs, however, it is important to keep the distinction in mind, since the computer is not as smart as a person.

The word “buffer”, by the way, comes from the meaning of the word as a cushion that deadens the force of a collision. In early computers, a buffer cushioned the interaction between files and the computer’s central processing unit. The drums or tapes that held a file and the central processing unit were pieces of equipment that were very different from each other, working at their own speeds, in spurts. The buffer made it possible for them to work together effectively. Eventually, the buffer grew from being an intermediary, a temporary holding place, to being the place where work is done. This transformation is rather like that of a small seaport that grew into a great city: once it was merely the place where cargo was warehoused temporarily before being loaded onto ships; then it became a business and cultural center in its own right.

Not all buffers are associated with files. For example, a *scratch* buffer does not visit any file. Similarly, a *Help* buffer is not associated with any file.

In the old days, when you lacked a ~/.emacs file and started an Emacs session by typing the command emacs alone, without naming any files, Emacs started with the *scratch* buffer visible. Nowadays, you will see a splash screen. You can follow one of the commands suggested on the splash screen, visit a file, or press q to quit the splash screen and reach the *scratch* buffer.

If you switch to the *scratch* buffer, type (buffer-name), position the cursor after it, and then type C-x C-e to evaluate the expression. The name "*scratch*" will be returned and will appear in the echo area. "*scratch*" is the name of the buffer. When you type (buffer-file-name) in the *scratch* buffer and evaluate that, nil will appear in the echo area, just as it does when you evaluate (buffer-file-name) in Info.

Incidentally, if you are in the *scratch* buffer and want the value returned by an expression to appear in the *scratch* buffer itself rather than in the echo area, type C-u C-x C-e instead of C-x C-e. This causes the value returned to appear after the expression. The buffer will look like this:

(buffer-name)"*scratch*"

You cannot do this in Info since Info is read-only and it will not allow you to change the contents of the buffer. But you can do this in any buffer you can edit; and when you write code or documentation (such as this book), this feature is very useful.

2.2 Getting Buffers

The buffer-name function returns the name of the buffer; to get the buffer itself, a different function is needed: the current-buffer function. If you use this function in code, what you get is the buffer itself.

A name and the object or entity to which the name refers are different from each other. You are not your name. You are a person to whom others refer by name. If you ask to speak to George and someone hands you a card with the letters ‘G’, ‘e’, ‘o’, ‘r’, ‘g’, and ‘e’ written on it, you might be amused, but you would not be satisfied. You do not want to speak to the name, but to the person to whom the name refers. A buffer is similar: the name of the scratch buffer is *scratch*, but the name is not the buffer. To get a buffer itself, you need to use a function such as current-buffer.

However, there is a slight complication: if you evaluate current-buffer in an expression on its own, as we will do here, what you see is a printed representation of the name of the buffer without the contents of the buffer. Emacs works this way for two reasons: the buffer may be thousands of lines long—too long to be conveniently displayed; and, another buffer may have the same contents but a different name, and it is important to distinguish between them.

Here is an expression containing the function:

(current-buffer)

If you evaluate this expression in Info in Emacs in the usual way, #<buffer *info*> will appear in the echo area. The special format indicates that the buffer itself is being returned, rather than just its name.

Incidentally, while you can type a number or symbol into a program, you cannot do that with the printed representation of a buffer: the only way to get a buffer itself is with a function such as current-buffer.

A related function is other-buffer. This returns the most recently selected buffer other than the one you are in currently, not a printed representation of its name. If you have recently switched back and forth from the *scratch* buffer, other-buffer will return that buffer.

You can see this by evaluating the expression:

(other-buffer)

You should see #<buffer *scratch*> appear in the echo area, or the name of whatever other buffer you switched back from most recently⁶.

2.3 Switching Buffers

The other-buffer function actually provides a buffer when it is used as an argument to a function that requires one. We can see this by using other-buffer and switch-to-buffer to switch to a different buffer.

But first, a brief introduction to the switch-to-buffer function. When you switched back and forth from Info to the *scratch* buffer to evaluate (buffer-name), you most likely typed C-x b and then typed *scratch*⁷ when prompted in the minibuffer for the name of the buffer to which you wanted to switch. The keystrokes, C-x b, cause the Lisp interpreter to evaluate the interactive function switch-to-buffer. As we said before, this is how Emacs works: different keystrokes call or run different functions. For example, C-f calls forward-char, M-e calls forward-sentence, and so on.

By writing switch-to-buffer in an expression, and giving it a buffer to switch to, we can switch buffers just the way C-x b does:

(switch-to-buffer (other-buffer))

The symbol switch-to-buffer is the first element of the list, so the Lisp interpreter will treat it as a function and carry out the instructions that are attached to it. But before doing that, the interpreter will note that other-buffer is inside parentheses and work on that symbol first. other-buffer is the first (and in this case, the only) element of this list, so the Lisp interpreter calls or runs the function. It returns another buffer. Next, the interpreter runs switch-to-buffer, passing to it, as an argument, the other buffer, which is what Emacs will switch to. If you are reading this in Info, try this now. Evaluate the expression. (To get back, type C-x b RET.)⁸

In the programming examples in later sections of this document, you will see the function set-buffer more often than switch-to-buffer. This is because of a difference between computer programs and humans: humans have eyes and expect to see the buffer on which they are working on their computer terminals. This is so obvious, it almost goes without saying. However, programs do not have eyes. When a computer program works on a buffer, that buffer does not need to be visible on the screen.

switch-to-buffer is designed for humans and does two different things: it switches the buffer to which Emacs’s attention is directed; and it switches the buffer displayed in the window to the new buffer. set-buffer, on the other hand, does only one thing: it switches the attention of the computer program to a different buffer. The buffer on the screen remains unchanged (of course, normally nothing happens there until the command finishes running).

Also, we have just introduced another jargon term, the word call. When you evaluate a list in which the first symbol is a function, you are calling that function. The use of the term comes from the notion of the function as an entity that can do something for you if you call it—just as a plumber is an entity who can fix a leak if you call him or her.

2.4 Buffer Size and the Location of Point

Finally, let’s look at several rather simple functions, buffer-size, point, point-min, and point-max. These give information about the size of a buffer and the location of point within it.

The function buffer-size tells you the size of the current buffer; that is, the function returns a count of the number of characters in the buffer.

(buffer-size)

You can evaluate this in the usual way, by positioning the cursor after the expression and typing C-x C-e.

In Emacs, the current position of the cursor is called point. The expression (point) returns a number that tells you where the cursor is located as a count of the number of characters from the beginning of the buffer up to point.

You can see the character count for point in this buffer by evaluating the following expression in the usual way:

(point)

As I write this, the value of point is 65724. The point function is frequently used in some of the examples later in this book.

The value of point depends, of course, on its location within the buffer. If you evaluate point in this spot, the number will be larger:

(point)

For me, the value of point in this location is 66043, which means that there are 319 characters (including spaces) between the two expressions. (Doubtless, you will see different numbers, since I will have edited this since I first evaluated point.)

The function point-min is somewhat similar to point, but it returns the value of the minimum permissible value of point in the current buffer. This is the number 1 unless narrowing is in effect. (Narrowing is a mechanism whereby you can restrict yourself, or a program, to operations on just a part of a buffer. See Narrowing and Widening.) Likewise, the function point-max returns the value of the maximum permissible value of point in the current buffer.

2.5 Exercise

Find a file with which you are working and move towards its middle. Find its buffer name, file name, length, and your position in the file.

3.1 The defun Macro

In Lisp, a symbol such as mark-whole-buffer has code attached to it that tells the computer what to do when the function is called. This code is called the function definition and is created by evaluating a Lisp expression that starts with the symbol defun (which is an abbreviation for define function).

In subsequent sections, we will look at function definitions from the Emacs source code, such as mark-whole-buffer. In this section, we will describe a simple function definition so you can see how it looks. This function definition uses arithmetic because it makes for a simple example. Some people dislike examples using arithmetic; however, if you are such a person, do not despair. Hardly any of the code we will study in the remainder of this introduction involves arithmetic or mathematics. The examples mostly involve text in one way or another.

A function definition has up to five parts following the word defun:

1. The name of the symbol to which the function definition should be attached.
2. A list of the arguments that will be passed to the function. If no arguments will be passed to the function, this is an empty list, ().
3. Documentation describing the function. (Technically optional, but strongly recommended.)
4. Optionally, an expression to make the function interactive so you can use it by typing M-x and then the name of the function; or by typing an appropriate key or keychord.
5. The code that instructs the computer what to do: the body of the function definition.

It is helpful to think of the five parts of a function definition as being organized in a template, with slots for each part:

(defun function-name (arguments…)
  "optional-documentation…"
  (interactive argument-passing-info)     ; optional
  body…)

As an example, here is the code for a function that multiplies its argument by 7. (This example is not interactive. See Making a Function Interactive, for that information.)

(defun multiply-by-seven (number)
  "Multiply NUMBER by seven."
  (* 7 number))

This definition begins with a parenthesis and the symbol defun, followed by the name of the function.

The name of the function is followed by a list that contains the arguments that will be passed to the function. This list is called the argument list. In this example, the list has only one element, the symbol, number. When the function is used, the symbol will be bound to the value that is used as the argument to the function.

Instead of choosing the word number for the name of the argument, I could have picked any other name. For example, I could have chosen the word multiplicand. I picked the word “number” because it tells what kind of value is intended for this slot; but I could just as well have chosen the word “multiplicand” to indicate the role that the value placed in this slot will play in the workings of the function. I could have called it foogle, but that would have been a bad choice because it would not tell humans what it means. The choice of name is up to the programmer and should be chosen to make the meaning of the function clear.

Indeed, you can choose any name you wish for a symbol in an argument list, even the name of a symbol used in some other function: the name you use in an argument list is private to that particular definition. In that definition, the name refers to a different entity than any use of the same name outside the function definition. Suppose you have a nick-name “Shorty” in your family; when your family members refer to “Shorty”, they mean you. But outside your family, in a movie, for example, the name “Shorty” refers to someone else. Because a name in an argument list is private to the function definition, you can change the value of such a symbol inside the body of a function without changing its value outside the function. The effect is similar to that produced by a let expression. (See let.)

The argument list is followed by the documentation string that describes the function. This is what you see when you type C-h f and the name of a function. Incidentally, when you write a documentation string like this, you should make the first line a complete sentence since some commands, such as apropos, print only the first line of a multi-line documentation string. Also, you should not indent the second line of a documentation string, if you have one, because that looks odd when you use C-h f (describe-function). The documentation string is optional, but it is so useful, it should be included in almost every function you write.

The third line of the example consists of the body of the function definition. (Most functions’ definitions, of course, are longer than this.) In this function, the body is the list, (* 7 number), which says to multiply the value of number by 7. (In Emacs Lisp, * is the function for multiplication, just as + is the function for addition.)

When you use the multiply-by-seven function, the argument number evaluates to the actual number you want used. Here is an example that shows how multiply-by-seven is used; but don’t try to evaluate this yet!

(multiply-by-seven 3)

The symbol number, specified in the function definition in the next section, is bound to the value 3 in the actual use of the function. Note that although number was inside parentheses in the function definition, the argument passed to the multiply-by-seven function is not in parentheses. The parentheses are written in the function definition so the computer can figure out where the argument list ends and the rest of the function definition begins.

If you evaluate this example, you are likely to get an error message. (Go ahead, try it!) This is because we have written the function definition, but not yet told the computer about the definition—we have not yet loaded the function definition in Emacs. Installing a function is the process that tells the Lisp interpreter the definition of the function. Installation is described in the next section.

3.2 Install a Function Definition

If you are reading this inside of Info in Emacs, you can try out the multiply-by-seven function by first evaluating the function definition and then evaluating (multiply-by-seven 3). A copy of the function definition follows. Place the cursor after the last parenthesis of the function definition and type C-x C-e. When you do this, multiply-by-seven will appear in the echo area. (What this means is that when a function definition is evaluated, the value it returns is the name of the defined function.) At the same time, this action installs the function definition.

(defun multiply-by-seven (number)
  "Multiply NUMBER by seven."
  (* 7 number))

By evaluating this defun, you have just installed multiply-by-seven in Emacs. The function is now just as much a part of Emacs as forward-word or any other editing function you use. (multiply-by-seven will stay installed until you quit Emacs. To reload code automatically whenever you start Emacs, see Installing Code Permanently.)

• The effect of installation
• Change a Function Definition

(multiply-by-seven 3)

multiply-by-seven is a Lisp function.

(multiply-by-seven NUMBER)

Multiply NUMBER by seven.

(defun multiply-by-seven (number)       ; Second version.
  "Multiply NUMBER by seven."
  (+ number number number number number number number))

3.3 Make a Function Interactive

You make a function interactive by placing a list that begins with the special form interactive immediately after the documentation. A user can invoke an interactive function by typing M-x and then the name of the function; or by typing the keys to which it is bound, for example, by typing C-n for next-line or C-x h for mark-whole-buffer.

Interestingly, when you call an interactive function interactively, the value returned is not automatically displayed in the echo area. This is because you often call an interactive function for its side effects, such as moving forward by a word or line, and not for the value returned. If the returned value were displayed in the echo area each time you typed a key, it would be very distracting.

• An Interactive multiply-by-seven, An Overview
• An Interactive multiply-by-seven

(defun multiply-by-seven (number)       ; Interactive version.
  "Multiply NUMBER by seven."
  (interactive "p")
  (message "The result is %d" (* 7 number)))

(defun multiply-by-seven (number)       ; Interactive version.
  "Multiply NUMBER by seven."
  (interactive "p")
  (message "The result is %d" (* 7 number)))

(message "The result is %d" (* 7 number))

(message "The result is %d" (* 7 5))

3.4 Different Options for interactive

In the example, multiply-by-seven used "p" as the argument to interactive. This argument told Emacs to interpret your typing either C-u followed by a number or META followed by a number as a command to pass that number to the function as its argument. Emacs has more than twenty characters predefined for use with interactive. In almost every case, one of these options will enable you to pass the right information interactively to a function. (See Code Characters for interactive in The GNU Emacs Lisp Reference Manual.)

Consider the function zap-to-char. Its interactive expression is

(interactive "p\ncZap to char: ")

The first part of the argument to interactive is ‘p’, with which you are already familiar. This argument tells Emacs to interpret a prefix, as a number to be passed to the function. You can specify a prefix either by typing C-u followed by a number or by typing META followed by a number. The prefix is the number of specified characters. Thus, if your prefix is three and the specified character is ‘x’, then you will delete all the text up to and including the third next ‘x’. If you do not set a prefix, then you delete all the text up to and including the specified character, but no more.

The ‘c’ tells the function the name of the character to which to delete.

More formally, a function with two or more arguments can have information passed to each argument by adding parts to the string that follows interactive. When you do this, the information is passed to each argument in the same order it is specified in the interactive list. In the string, each part is separated from the next part by a ‘\n’, which is a newline. For example, you can follow ‘p’ with a ‘\n’ and an ‘cZap to char: ’. This causes Emacs to pass the value of the prefix argument (if there is one) and the character.

In this case, the function definition looks like the following, where arg and char are the symbols to which interactive binds the prefix argument and the specified character:

(defun name-of-function (arg char)
  "documentation…"
  (interactive "p\ncZap to char: ")
  body-of-function…)

(The space after the colon in the prompt makes it look better when you are prompted. See The Definition of copy-to-buffer, for an example.)

When a function does not take arguments, interactive does not require any. Such a function contains the simple expression (interactive). The mark-whole-buffer function is like this.

Alternatively, if the special letter-codes are not right for your application, you can pass your own arguments to interactive as a list.

See The Definition of append-to-buffer, for an example. See Using Interactive in The GNU Emacs Lisp Reference Manual, for a more complete explanation about this technique.

3.5 Install Code Permanently

When you install a function definition by evaluating it, it will stay installed until you quit Emacs. The next time you start a new session of Emacs, the function will not be installed unless you evaluate the function definition again.

At some point, you may want to have code installed automatically whenever you start a new session of Emacs. There are several ways of doing this:

• If you have code that is just for yourself, you can put the code for the function definition in your .emacs initialization file. When you start Emacs, your .emacs file is automatically evaluated and all the function definitions within it are installed. See Your .emacs File.
• Alternatively, you can put the function definitions that you want installed in one or more files of their own and use the load function to cause Emacs to evaluate and thereby install each of the functions in the files. See Loading Files.
• Thirdly, if you have code that your whole site will use, it is usual to put it in a file called site-init.el that is loaded when Emacs is built. This makes the code available to everyone who uses your machine. (See the INSTALL file that is part of the Emacs distribution.)

Finally, if you have code that everyone who uses Emacs may want, you can post it on a computer network or send a copy to the Free Software Foundation. (When you do this, please license the code and its documentation under a license that permits other people to run, copy, study, modify, and redistribute the code and which protects you from having your work taken from you.) If you send a copy of your code to the Free Software Foundation, and properly protect yourself and others, it may be included in the next release of Emacs. In large part, this is how Emacs has grown over the past years, by donations.

3.6 let

The let expression is a special form in Lisp that you will need to use in most function definitions.

let is used to attach or bind a symbol to a value in such a way that the Lisp interpreter will not confuse the variable with a variable of the same name that is not part of the function.

To understand why the let special form is necessary, consider the situation in which you own a home that you generally refer to as “the house”, as in the sentence, “The house needs painting.” If you are visiting a friend and your host refers to “the house”, he is likely to be referring to his house, not yours, that is, to a different house.

If your friend is referring to his house and you think he is referring to your house, you may be in for some confusion. The same thing could happen in Lisp if a variable that is used inside of one function has the same name as a variable that is used inside of another function, and the two are not intended to refer to the same value. The let special form prevents this kind of confusion.

• let Prevents Confusion
• The Parts of a let Expression
• Sample let Expression
• Uninitialized Variables in a let Statement
• How let Binds Variables

(let varlist body…)

(let ((variable value)
      (variable value)
      …)
  body…)

(let ((zebra "stripes")
      (tiger "fierce"))
  (message "One kind of animal has %s and another is %s."
           zebra tiger))

"One kind of animal has stripes and another is fierce."

(let ((birch 3)
      pine
      fir
      (oak 'some))
  (message
   "Here are %d variables with %s, %s, and %s value."
   birch pine fir oak))

"Here are 3 variables with nil, nil, and some value."

;;; -*- lexical-binding: t -*-

;;; -*- lexical-binding: t -*-

(setq x 0)

(defun getx ()
  x)

(setq x 1)

(let ((x 2))
  (getx))
     ⇒ 1

;;; -*- lexical-binding: nil -*-

(setq x 0)

(defun getx ()
  x)

(setq x 1)

(let ((x 2))
  (getx))
     ⇒ 2

3.7 The if Special Form

Another special form is the conditional if. This form is used to instruct the computer to make decisions. You can write function definitions without using if, but it is used often enough, and is important enough, to be included here. It is used, for example, in the code for the function beginning-of-buffer.

The basic idea behind an if, is that if a test is true, then an expression is evaluated. If the test is not true, the expression is not evaluated. For example, you might make a decision such as, “if it is warm and sunny, then go to the beach!”

• if in more detail
• The type-of-animal Function in Detail

(if true-or-false-test
    action-to-carry-out-if-test-is-true)

(if (> 5 4)                             ; if-part
    (message "5 is greater than 4!"))   ; then-part

(defun type-of-animal (characteristic)
  "Print message in echo area depending on CHARACTERISTIC.
If the CHARACTERISTIC is the string \"fierce\",
then warn of a tiger."
  (if (equal characteristic "fierce")
      (message "It is a tiger!")))

(type-of-animal "fierce")

(type-of-animal "striped")

(defun name-of-function (argument-list)
  "documentation…"
  body…)

(defun type-of-animal (characteristic)
  "Print message in echo area depending on CHARACTERISTIC.
If the CHARACTERISTIC is the string \"fierce\",
then warn of a tiger."
  body: the if expression)

(if true-or-false-test
    action-to-carry-out-if-the-test-returns-true)

(if (equal characteristic "fierce")
    (message "It is a tiger!"))

(equal characteristic "fierce")

3.8 If–then–else Expressions

An if expression may have an optional third argument, called the else-part, for the case when the true-or-false-test returns false. When this happens, the second argument or then-part of the overall if expression is not evaluated, but the third or else-part is evaluated. You might think of this as the cloudy day alternative for the decision “if it is warm and sunny, then go to the beach, else read a book!”.

The word “else” is not written in the Lisp code; the else-part of an if expression comes after the then-part. In the written Lisp, the else-part is usually written to start on a line of its own and is indented less than the then-part:

(if true-or-false-test
    action-to-carry-out-if-the-test-returns-true
  action-to-carry-out-if-the-test-returns-false)

For example, the following if expression prints the message ‘4 is not greater than 5!’ when you evaluate it in the usual way:

(if (> 4 5)                               ; if-part
    (message "4 falsely greater than 5!") ; then-part
  (message "4 is not greater than 5!"))   ; else-part

Note that the different levels of indentation make it easy to distinguish the then-part from the else-part. (GNU Emacs has several commands that automatically indent if expressions correctly. See GNU Emacs Helps You Type Lists.)

We can extend the type-of-animal function to include an else-part by simply incorporating an additional part to the if expression.

You can see the consequences of doing this if you evaluate the following version of the type-of-animal function definition to install it and then evaluate the two subsequent expressions to pass different arguments to the function.

(defun type-of-animal (characteristic)  ; Second version.
  "Print message in echo area depending on CHARACTERISTIC.
If the CHARACTERISTIC is the string \"fierce\",
then warn of a tiger; else say it is not fierce."
  (if (equal characteristic "fierce")
      (message "It is a tiger!")
    (message "It is not fierce!")))

(type-of-animal "fierce")

(type-of-animal "striped")

When you evaluate (type-of-animal "fierce"), you will see the following message printed in the echo area: "It is a tiger!"; but when you evaluate (type-of-animal "striped"), you will see "It is not fierce!".

(Of course, if the characteristic were "ferocious", the message "It is not fierce!" would be printed; and it would be misleading! When you write code, you need to take into account the possibility that some such argument will be tested by the if and write your program accordingly.)

3.9 Truth and Falsehood in Emacs Lisp

There is an important aspect to the truth test in an if expression. So far, we have spoken of “true” and “false” as values of predicates as if they were new kinds of Emacs Lisp objects. In fact, “false” is just our old friend nil. Anything else—anything at all—is “true”.

The expression that tests for truth is interpreted as true if the result of evaluating it is a value that is not nil. In other words, the result of the test is considered true if the value returned is a number such as 47, a string such as "hello", or a symbol (other than nil) such as flowers, or a list (so long as it is not empty), or even a buffer!

• An explanation of nil

(if 4
    'true
  'false)

(if nil
    'true
  'false)

(> 5 4)

(> 4 5)

3.10 save-excursion

The save-excursion function is the final special form that we will discuss in this chapter.

In Emacs Lisp programs used for editing, the save-excursion function is very common. It saves the location of point, executes the body of the function, and then restores point to its previous position if its location was changed. Its primary purpose is to keep the user from being surprised and disturbed by unexpected movement of point.

• Point and Mark
• Template for a save-excursion Expression

(save-excursion
  body…)

(save-excursion
  first-expression-in-body
  second-expression-in-body
  third-expression-in-body
   …
  last-expression-in-body)

(let varlist
  (save-excursion
    body…))

3.11 Review

In the last few chapters we have introduced a macro and a fair number of functions and special forms. Here they are described in brief, along with a few similar functions that have not been mentioned yet.

eval-last-sexp

Evaluate the last symbolic expression before the current location of point. The value is printed in the echo area unless the function is invoked with an argument; in that case, the output is printed in the current buffer. This command is normally bound to C-x C-e.

defun

Define function. This macro has up to five parts: the name, a template for the arguments that will be passed to the function, documentation, an optional interactive declaration, and the body of the definition.

For example, in Emacs the function definition of dired-unmark-all-marks is as follows.

(defun dired-unmark-all-marks ()
  "Remove all marks from all files in the Dired buffer."
  (interactive)
  (dired-unmark-all-files ?\r))

interactive

Declare to the interpreter that the function can be used interactively. This special form may be followed by a string with one or more parts that pass the information to the arguments of the function, in sequence. These parts may also tell the interpreter to prompt for information. Parts of the string are separated by newlines, ‘\n’.

Common code characters are:

b

The name of an existing buffer.

f

The name of an existing file.

p

The numeric prefix argument. (Note that this p is lower case.)

r

Point and the mark, as two numeric arguments, smallest first. This is the only code letter that specifies two successive arguments rather than one.

See Code Characters for ‘interactive’ in The GNU Emacs Lisp Reference Manual, for a complete list of code characters.

let

Declare that a list of variables is for use within the body of the let and give them an initial value, either nil or a specified value; then evaluate the rest of the expressions in the body of the let and return the value of the last one. Inside the body of the let, the Lisp interpreter does not see the values of the variables of the same names that are bound outside of the let.

For example,

(let ((foo (buffer-name))
      (bar (buffer-size)))
  (message
   "This buffer is %s and has %d characters."
   foo bar))

save-excursion

Record the values of point and the current buffer before evaluating the body of this special form. Restore the value of point and buffer afterward.

For example,

(message "We are %d characters into this buffer."
         (- (point)
            (save-excursion
              (goto-char (point-min)) (point))))

if

Evaluate the first argument to the function; if it is true, evaluate the second argument; else evaluate the third argument, if there is one.

The if special form is called a conditional. There are other conditionals in Emacs Lisp, but if is perhaps the most commonly used.

For example,

(if (= 22 emacs-major-version)
    (message "This is version 22 Emacs")
  (message "This is not version 22 Emacs"))

<

>

<=

>=

The < function tests whether its first argument is smaller than its second argument. A corresponding function, >, tests whether the first argument is greater than the second. Likewise, <= tests whether the first argument is less than or equal to the second and >= tests whether the first argument is greater than or equal to the second. In all cases, both arguments must be numbers or markers (markers indicate positions in buffers).

=

The = function tests whether two arguments, both numbers or markers, are equal.

equal

eq

Test whether two objects are the same. equal uses one meaning of the word “same” and eq uses another: equal returns true if the two objects have a similar structure and contents, such as two copies of the same book. On the other hand, eq, returns true if both arguments are actually the same object.

string<

string-lessp

string=

string-equal

The string-lessp function tests whether its first argument is smaller than the second argument. A shorter, alternative name for the same function (a defalias) is string<.

The arguments to string-lessp must be strings or symbols; the ordering is lexicographic, so case is significant. The print names of symbols are used instead of the symbols themselves.

An empty string, ‘""’, a string with no characters in it, is smaller than any string of characters.

string-equal provides the corresponding test for equality. Its shorter, alternative name is string=. There are no string test functions that correspond to >, >=, or <=.

message

Print a message in the echo area. The first argument is a string that can contain ‘%s’, ‘%d’, or ‘%c’ to print the value of arguments that follow the string. The argument used by ‘%s’ must be a string or a symbol; the argument used by ‘%d’ must be a number. The argument used by ‘%c’ must be an ASCII code number; it will be printed as the character with that ASCII code. (Various other %-sequences have not been mentioned.)

setq

set

The setq special form sets the value of its first argument to the value of the second argument. The first argument is automatically quoted by setq. It does the same for succeeding pairs of arguments.

buffer-name

Without an argument, return the name of the buffer, as a string.

buffer-file-name

Without an argument, return the name of the file the buffer is visiting.

current-buffer

Return the buffer in which Emacs is active; it may not be the buffer that is visible on the screen.

other-buffer

Return the most recently selected buffer (other than the buffer passed to other-buffer as an argument and other than the current buffer).

switch-to-buffer

Select a buffer for Emacs to be active in and display it in the current window so users can look at it. Usually bound to C-x b.

set-buffer

Switch Emacs’s attention to a buffer on which programs will run. Don’t alter what the window is showing.

buffer-size

Return the number of characters in the current buffer.

point

Return the value of the current position of the cursor, as an integer counting the number of characters from the beginning of the buffer.

point-min

Return the minimum permissible value of point in the current buffer. This is 1, unless narrowing is in effect.

point-max

Return the value of the maximum permissible value of point in the current buffer. This is the end of the buffer, unless narrowing is in effect.

3.12 Exercises

• Write a non-interactive function that doubles the value of its argument, a number. Make that function interactive.
• Write a function that tests whether the current value of fill-column is greater than the argument passed to the function, and if so, prints an appropriate message.

4.1 Finding More Information

In this walk-through, I will describe each new function as we come to it, sometimes in detail and sometimes briefly. If you are interested, you can get the full documentation of any Emacs Lisp function at any time by typing C-h f and then the name of the function (and then RET). Similarly, you can get the full documentation for a variable by typing C-h v and then the name of the variable (and then RET).

Also, describe-function will tell you the location of the function definition.

Put point into the name of the file that contains the function and press the RET key. In this case, RET means push-button rather than “return” or “enter”. Emacs will take you directly to the function definition.

More generally, if you want to see a function in its original source file, you can use the xref-find-definitions function to jump to it. xref-find-definitions works with a wide variety of languages, not just Lisp, and C, and it works with non-programming text as well. For example, xref-find-definitions will jump to the various nodes in the Texinfo source file of this document (provided that you’ve run the etags utility to record all the nodes in the manuals that come with Emacs; see Create Tags Table in The GNU Emacs Manual).

To use the xref-find-definitions command, type M-. (i.e., press the period key while holding down the META key, or else type the ESC key and then type the period key), and then, at the prompt, type in the name of the function whose source code you want to see, such as mark-whole-buffer, and then type RET. (If the command doesn’t prompt, invoke it with an argument: C-u M-.; see Different Options for interactive.) Emacs will switch buffers and display the source code for the function on your screen¹¹. To switch back to your current buffer, type M-, or C-x b RET. (On some keyboards, the META key is labeled ALT.)

Incidentally, the files that contain Lisp code are conventionally called libraries. The metaphor is derived from that of a specialized library, such as a law library or an engineering library, rather than a general library. Each library, or file, contains functions that relate to a particular topic or activity, such as abbrev.el for handling abbreviations and other typing shortcuts, and help.el for help. (Sometimes several libraries provide code for a single activity, as the various rmail… files provide code for reading electronic mail.) In The GNU Emacs Manual, you will see sentences such as “The C-h p command lets you search the standard Emacs Lisp libraries by topic keywords.”

4.2 A Simplified beginning-of-buffer Definition

The beginning-of-buffer command is a good function to start with since you are likely to be familiar with it and it is easy to understand. Used as an interactive command, beginning-of-buffer moves the cursor to the beginning of the buffer, leaving the mark at the previous position. It is generally bound to M-<.

In this section, we will discuss a shortened version of the function that shows how it is most frequently used. This shortened function works as written, but it does not contain the code for a complex option. In another section, we will describe the entire function. (See Complete Definition of beginning-of-buffer.)

Before looking at the code, let’s consider what the function definition has to contain: it must include an expression that makes the function interactive so it can be called by typing M-x beginning-of-buffer or by typing a keychord such as M-<; it must include code to leave a mark at the original position in the buffer; and it must include code to move the cursor to the beginning of the buffer.

Here is the complete text of the shortened version of the function:

(defun simplified-beginning-of-buffer ()
  "Move point to the beginning of the buffer;
leave mark at previous position."
  (interactive)
  (push-mark)
  (goto-char (point-min)))

Like all function definitions, this definition has five parts following the macro defun:

1. The name: in this example, simplified-beginning-of-buffer.
2. A list of the arguments: in this example, an empty list, (),
3. The documentation string.
4. The interactive expression.
5. The body.

In this function definition, the argument list is empty; this means that this function does not require any arguments. (When we look at the definition for the complete function, we will see that it may be passed an optional argument.)

The interactive expression tells Emacs that the function is intended to be used interactively. In this example, interactive does not have an argument because simplified-beginning-of-buffer does not require one.

The body of the function consists of the two lines:

(push-mark)
(goto-char (point-min))

The first of these lines is the expression, (push-mark). When this expression is evaluated by the Lisp interpreter, it sets a mark at the current position of the cursor, wherever that may be. The position of this mark is saved in the mark ring.

The next line is (goto-char (point-min)). This expression jumps the cursor to the minimum point in the buffer, that is, to the beginning of the buffer (or to the beginning of the accessible portion of the buffer if it is narrowed. See Narrowing and Widening.)

The push-mark command sets a mark at the place where the cursor was located before it was moved to the beginning of the buffer by the (goto-char (point-min)) expression. Consequently, you can, if you wish, go back to where you were originally by typing C-x C-x.

That is all there is to the function definition!

When you are reading code such as this and come upon an unfamiliar function, such as goto-char, you can find out what it does by using the describe-function command. To use this command, type C-h f and then type in the name of the function and press RET. The describe-function command will print the function’s documentation string in a *Help* window. For example, the documentation for goto-char is:

Set point to POSITION, a number or marker.
Beginning of buffer is position (point-min), end is (point-max).

The function’s one argument is the desired position.

(The prompt for describe-function will offer you the symbol under or preceding the cursor, so you can save typing by positioning the cursor right over or after the function and then typing C-h f RET.)

The end-of-buffer function definition is written in the same way as the beginning-of-buffer definition except that the body of the function contains the expression (goto-char (point-max)) in place of (goto-char (point-min)).

4.3 The Definition of mark-whole-buffer

The mark-whole-buffer function is no harder to understand than the simplified-beginning-of-buffer function. In this case, however, we will look at the complete function, not a shortened version.

The mark-whole-buffer function is not as commonly used as the beginning-of-buffer function, but is useful nonetheless: it marks a whole buffer as a region by putting point at the beginning and a mark at the end of the buffer. It is generally bound to C-x h.

• An overview of mark-whole-buffer
• Body of mark-whole-buffer

(defun mark-whole-buffer ()
  "Put point at beginning and mark at end of buffer.
You probably should not use this function in Lisp programs;
it is usually a mistake for a Lisp function to use any subroutine
that uses or sets the mark."
  (interactive)
  (push-mark (point))
  (push-mark (point-max) nil t)
  (goto-char (point-min)))

(defun name-of-function (argument-list)
  "documentation…"
  (interactive-expression…)
  body…)

(push-mark (point))
(push-mark (point-max) nil t)
(goto-char (point-min))

(push-mark (point-max) nil t)

4.4 The Definition of append-to-buffer

The append-to-buffer command is more complex than the mark-whole-buffer command. What it does is copy the region (that is, the part of the buffer between point and mark) from the current buffer to a specified buffer.

• An Overview of append-to-buffer
• The append-to-buffer Interactive Expression
• The Body of append-to-buffer
• save-excursion in append-to-buffer

(defun append-to-buffer (buffer start end)
  "Append to specified buffer the text of the region.
It is inserted into that buffer before its point.

When calling from a program, give three arguments:
BUFFER (or buffer name), START and END.
START and END specify the portion of the current buffer to be copied."
  (interactive
   (list (read-buffer "Append to buffer: " (other-buffer
                                            (current-buffer) t))
         (region-beginning) (region-end)))

  (let ((oldbuf (current-buffer)))
    (save-excursion
      (let* ((append-to (get-buffer-create buffer))
             (windows (get-buffer-window-list append-to t t))
             point)
        (set-buffer append-to)
        (setq point (point))
        (barf-if-buffer-read-only)
        (insert-buffer-substring oldbuf start end)
        (dolist (window windows)
          (when (= (window-point window) point)
            (set-window-point window (point))))))))

(defun append-to-buffer (buffer start end)
  "documentation…"
  (interactive …)
  body…)

(interactive
 (list (read-buffer
        "Append to buffer: "
        (other-buffer (current-buffer) t))
       (region-beginning)
       (region-end)))

(other-buffer (current-buffer) t)

(interactive "BAppend to buffer: \nr")

(defun append-to-buffer (buffer start end)
  "documentation…"
  (interactive …)
  (let ((variable value))
        body…))

(oldbuf (current-buffer))

(let ((oldbuf (current-buffer)))
  … )

(defun …
  …
  …
  (let…
    (save-excursion
      …

(let ((oldbuf (current-buffer)))
  (save-excursion
    …
    (set-buffer …)
    (insert-buffer-substring oldbuf start end)
    …))

(save-excursion
  first-expression-in-body
  second-expression-in-body
   …
  last-expression-in-body)

(let* ((append-to (get-buffer-create buffer))
       (windows (get-buffer-window-list append-to t t))
       point)
  BODY...)

(set-buffer (get-buffer-create buffer))

(set-buffer append-to)

(insert-buffer-substring oldbuf start end)

(let (bind-oldbuf-to-value-of-current-buffer)
  (save-excursion                       ; Keep track of buffer.
    change-buffer
    insert-substring-from-oldbuf-into-buffer)

  change-back-to-original-buffer-when-finished
let-the-local-meaning-of-oldbuf-disappear-when-finished

4.5 Review

Here is a brief summary of the various functions discussed in this chapter.

describe-function

describe-variable

Print the documentation for a function or variable. Conventionally bound to C-h f and C-h v.

xref-find-definitions

Find the file containing the source for a function or variable and switch buffers to it, positioning point at the beginning of the item. Conventionally bound to M-. (that’s a period following the META key).

save-excursion

Save the location of point and restore its value after the arguments to save-excursion have been evaluated. Also, remember the current buffer and return to it.

push-mark

Set mark at a location and record the value of the previous mark on the mark ring. The mark is a location in the buffer that will keep its relative position even if text is added to or removed from the buffer.

goto-char

Set point to the location specified by the value of the argument, which can be a number, a marker, or an expression that returns the number of a position, such as (point-min).

insert-buffer-substring

Copy a region of text from a buffer that is passed to the function as an argument and insert the region into the current buffer.

mark-whole-buffer

Mark the whole buffer as a region. Normally bound to C-x h.

let*

Declare a list of variables and give them an initial value; then evaluate the rest of the expressions in the body of let*. The values of the variables can be used to bind ensuing variables in the list.

set-buffer

Switch the attention of Emacs to another buffer, but do not change the window being displayed. Used when the program rather than a human is to work on a different buffer.

get-buffer-create

get-buffer

Find a named buffer or create one if a buffer of that name does not exist. The get-buffer function returns nil if the named buffer does not exist.

4.6 Exercises

• Write your own simplified-end-of-buffer function definition; then test it to see whether it works.
• Use if and get-buffer to write a function that prints a message telling you whether a buffer exists.
• Using xref-find-definitions, find the source for the copy-to-buffer function.

5.1 The Definition of copy-to-buffer

After understanding how append-to-buffer works, it is easy to understand copy-to-buffer. This function copies text into a buffer, but instead of adding to the second buffer, it replaces all the previous text in the second buffer.

The body of copy-to-buffer looks like this,

…
(interactive "BCopy to buffer: \nr")
(let ((oldbuf (current-buffer)))
  (with-current-buffer (get-buffer-create buffer)
    (barf-if-buffer-read-only)
    (erase-buffer)
    (save-excursion
      (insert-buffer-substring oldbuf start end)))))

The copy-to-buffer function has a simpler interactive expression than append-to-buffer.

The definition then says

(with-current-buffer (get-buffer-create buffer) …

First, look at the earliest inner expression; that is evaluated first. That expression starts with get-buffer-create buffer. The function tells the computer to use the buffer with the name specified as the one to which you are copying, or if such a buffer does not exist, to create it. Then, the with-current-buffer function evaluates its body with that buffer temporarily current, after which it will switch back to the buffer we are at now¹².

(This demonstrates another way to shift the computer’s attention but not the user’s. The append-to-buffer function showed how to do the same with save-excursion and set-buffer. with-current-buffer is a newer, and arguably easier, mechanism.)

The barf-if-buffer-read-only function sends you an error message saying the buffer is read-only if you cannot modify it.

The next line has the erase-buffer function as its sole contents. That function erases the buffer.

Finally, the last two lines contain the save-excursion expression with insert-buffer-substring as its body. The insert-buffer-substring expression copies the text from the buffer you are in (and you have not seen the computer shift its attention, so you don’t know that that buffer is now called oldbuf).

Incidentally, this is what is meant by “replacement”. To replace text, Emacs erases the previous text and then inserts new text.

In outline, the body of copy-to-buffer looks like this:

(let (bind-oldbuf-to-value-of-current-buffer)
    (with-the-buffer-you-are-copying-to
      (but-do-not-erase-or-copy-to-a-read-only-buffer)
      (erase-buffer)
      (save-excursion
        insert-substring-from-oldbuf-into-buffer)))

5.2 The Definition of insert-buffer

insert-buffer is yet another buffer-related function. This command copies another buffer into the current buffer. It is the reverse of append-to-buffer or copy-to-buffer, since they copy a region of text from the current buffer to another buffer.

Here is a discussion based on the original code. The code was simplified in 2003 and is harder to understand.

(See New Body for insert-buffer, to see a discussion of the new body.)

In addition, this code illustrates the use of interactive with a buffer that might be read-only and the important distinction between the name of an object and the object actually referred to.

• The Code for insert-buffer
• The Interactive Expression in insert-buffer
• The Body of the insert-buffer Function
• insert-buffer With an if Instead of an or
• The or in the Body
• The let Expression in insert-buffer
• New Body for insert-buffer

(defun insert-buffer (buffer)
  "Insert after point the contents of BUFFER.
Puts mark after the inserted text.
BUFFER may be a buffer or a buffer name."
  (interactive "*bInsert buffer: ")

  (or (bufferp buffer)
      (setq buffer (get-buffer buffer)))
  (let (start end newmark)
    (save-excursion
      (save-excursion
        (set-buffer buffer)
        (setq start (point-min) end (point-max)))

      (insert-buffer-substring buffer start end)
      (setq newmark (point)))
    (push-mark newmark)))

(defun insert-buffer (buffer)
  "documentation…"
  (interactive "*bInsert buffer: ")
  body…)

(defun insert-buffer (buffer)
  "documentation…"
  (interactive "*bInsert buffer: ")
  (or …
      …

  (let (varlist)
      body-of-let… )

(if (not (holding-on-to-guest))
    (find-and-take-arm-of-guest))

(if (not (bufferp buffer))              ; if-part
    (setq buffer (get-buffer buffer)))  ; then-part

(not (bufferp buffer))

(or (bufferp buffer)
    (setq buffer (get-buffer buffer)))

(or (holding-on-to-guest) (find-and-take-arm-of-guest))

(save-excursion
  (set-buffer buffer)
  (setq start (point-min) end (point-max)))

(save-excursion
  (inner-save-excursion-expression
     (go-to-new-buffer-and-set-start-and-end)
  (insert-buffer-substring buffer start end)
  (setq newmark (point)))

(let (start end newmark)
  (save-excursion
    (save-excursion
      (set-buffer buffer)
      (setq start (point-min) end (point-max)))
    (insert-buffer-substring buffer start end)
    (setq newmark (point)))
  (push-mark newmark))

  (push-mark
   (save-excursion
     (insert-buffer-substring (get-buffer buffer))
     (point)))

   nil

5.3 Complete Definition of beginning-of-buffer

The basic structure of the beginning-of-buffer function has already been discussed. (See A Simplified beginning-of-buffer Definition.) This section describes the complex part of the definition.

As previously described, when invoked without an argument, beginning-of-buffer moves the cursor to the beginning of the buffer (in truth, the beginning of the accessible portion of the buffer), leaving the mark at the previous position. However, when the command is invoked with a number between one and ten, the function considers that number to be a fraction of the length of the buffer, measured in tenths, and Emacs moves the cursor that fraction of the way from the beginning of the buffer. Thus, you can either call this function with the key command M-<, which will move the cursor to the beginning of the buffer, or with a key command such as C-u 7 M-< which will move the cursor to a point 70% of the way through the buffer. If a number bigger than ten is used for the argument, it moves to the end of the buffer.

The beginning-of-buffer function can be called with or without an argument. The use of the argument is optional.

• Optional Arguments
• beginning-of-buffer with an Argument
• The Complete beginning-of-buffer

(defun beginning-of-buffer (&optional arg)

(defun beginning-of-buffer (&optional arg)
  "documentation…"
  (interactive "P")
  (or (is-the-argument-a-cons-cell arg)
      (and are-both-transient-mark-mode-and-mark-active-true)
      (push-mark))
  (let (determine-size-and-set-it)
    (goto-char
      (if-there-is-an-argument
          figure-out-where-to-go
        else-go-to
        (point-min))))
  do-nicety

(if (> (buffer-size) 10000)
    ;; Avoid overflow for large buffer sizes!
    (* (prefix-numeric-value arg)
       (/ size 10))
  (/
   (+ 10
      (* size
         (prefix-numeric-value arg)))
   10))

(if (buffer-is-large
    divide-buffer-size-by-10-and-multiply-by-arg
  else-use-alternate-calculation

(if (> size 10000)

(*
  (prefix-numeric-value arg)
  (/ size 10))

(* numeric-value-of-prefix-arg
   number-of-characters-in-one-tenth-of-the-accessible-buffer)

(goto-char (* (prefix-numeric-value arg)
              (/ size 10)))

(/ (+ 10 (* size (prefix-numeric-value arg))) 10)

  (/
   (+ 10
      (*
       size
       (prefix-numeric-value arg)))
   10)

(* size (prefix-numeric-value arg))

(defun beginning-of-buffer (&optional arg)
  "Move point to the beginning of the buffer;
leave mark at previous position.
With \\[universal-argument] prefix,
do not set mark at previous position.
With numeric arg N,
put point N/10 of the way from the beginning.

If the buffer is narrowed,
this command uses the beginning and size
of the accessible part of the buffer.

Don't use this command in Lisp programs!
\(goto-char (point-min)) is faster
and avoids clobbering the mark."
  (interactive "P")
  (or (consp arg)
      (and transient-mark-mode mark-active)
      (push-mark))

  (let ((size (- (point-max) (point-min))))
    (goto-char (if (and arg (not (consp arg)))
                   (+ (point-min)
                      (if (> size 10000)
                          ;; Avoid overflow for large buffer sizes!
                          (* (prefix-numeric-value arg)
                             (/ size 10))
                        (/ (+ 10 (* size (prefix-numeric-value arg)))
                           10)))
                 (point-min))))
  (if (and arg (not (consp arg))) (forward-line 1)))

\\[universal-argument]

(if (and arg (not (consp arg))) (forward-line 1))

5.4 Review

Here is a brief summary of some of the topics covered in this chapter.

or

Evaluate each argument in sequence, and return the value of the first argument that is not nil; if none return a value that is not nil, return nil. In brief, return the first true value of the arguments; return a true value if one or any of the others are true.

and

Evaluate each argument in sequence, and if any are nil, return nil; if none are nil, return the value of the last argument. In brief, return a true value only if all the arguments are true; return a true value if one and each of the others is true.

&optional

A keyword used to indicate that an argument to a function definition is optional; this means that the function can be evaluated without the argument, if desired.

prefix-numeric-value

Convert the raw prefix argument produced by (interactive "P") to a numeric value.

forward-line

Move point forward to the beginning of the next line, or if the argument is greater than one, forward that many lines. If it can’t move as far forward as it is supposed to, forward-line goes forward as far as it can and then returns a count of the number of additional lines it was supposed to move but couldn’t.

erase-buffer

Delete the entire contents of the current buffer.

bufferp

Return t if its argument is a buffer; otherwise return nil.

5.5 optional Argument Exercise

Write an interactive function with an optional argument that tests whether its argument, a number, is greater than or equal to, or else, less than the value of fill-column, and tells you which, in a message. However, if you do not pass an argument to the function, use 56 as a default value.

6.1 The save-restriction Special Form

In Emacs Lisp, you can use the save-restriction special form to keep track of whatever narrowing is in effect, if any. When the Lisp interpreter meets with save-restriction, it executes the code in the body of the save-restriction expression, and then undoes any changes to narrowing that the code caused. If, for example, the buffer is narrowed and the code that follows save-restriction gets rid of the narrowing, save-restriction returns the buffer to its narrowed region afterwards. In the what-line command, any narrowing the buffer may have is undone by the widen command that immediately follows the save-restriction command. Any original narrowing is restored just before the completion of the function.

The template for a save-restriction expression is simple:

(save-restriction
  body… )

The body of the save-restriction is one or more expressions that will be evaluated in sequence by the Lisp interpreter.

Finally, a point to note: when you use both save-excursion and save-restriction, one right after the other, you should use save-excursion outermost. If you write them in reverse order, you may fail to record narrowing in the buffer to which Emacs switches after calling save-excursion. Thus, when written together, save-excursion and save-restriction should be written like this:

(save-excursion
  (save-restriction
    body…))

In other circumstances, when not written together, the save-excursion and save-restriction special forms must be written in the order appropriate to the function.

For example,

  (save-restriction
    (widen)
    (save-excursion
    body…))

6.2 what-line

The what-line command tells you the number of the line in which the cursor is located. The function illustrates the use of the save-restriction and save-excursion commands. Here is the original text of the function:

(defun what-line ()
  "Print the current line number (in the buffer) of point."
  (interactive)
  (save-restriction
    (widen)
    (save-excursion
      (beginning-of-line)
      (message "Line %d"
               (1+ (count-lines 1 (point)))))))

(In modern versions of GNU Emacs, the what-line function has been expanded to tell you your line number in a narrowed buffer as well as your line number in a widened buffer. The modern version is more complex than the version shown here. If you feel adventurous, you might want to look at it after figuring out how this version works. You will probably need to use C-h f (describe-function). The newer version uses a conditional to determine whether the buffer has been narrowed.

Also, the modern version of what-line uses line-number-at-pos, which among other simple expressions, such as (goto-char (point-min)), moves point to the beginning of the current line with (forward-line 0) rather than beginning-of-line.)

The what-line function as shown here has a documentation line and is interactive, as you would expect. The next two lines use the functions save-restriction and widen.

The save-restriction special form notes whatever narrowing is in effect, if any, in the current buffer and restores that narrowing after the code in the body of the save-restriction has been evaluated.

The save-restriction special form is followed by widen. This function undoes any narrowing the current buffer may have had when what-line was called. (The narrowing that was there is the narrowing that save-restriction remembers.) This widening makes it possible for the line counting commands to count from the beginning of the buffer. Otherwise, they would have been limited to counting within the accessible region. Any original narrowing is restored just before the completion of the function by the save-restriction special form.

The call to widen is followed by save-excursion, which saves the location of the cursor (i.e., of point), and restores it after the code in the body of the save-excursion uses the beginning-of-line function to move point.

(Note that the (widen) expression comes between the save-restriction and save-excursion special forms. When you write the two save- … expressions in sequence, write save-excursion outermost.)

The last two lines of the what-line function are functions to count the number of lines in the buffer and then print the number in the echo area.

(message "Line %d"
         (1+ (count-lines 1 (point)))))))

The message function prints a one-line message at the bottom of the Emacs screen. The first argument is inside of quotation marks and is printed as a string of characters. However, it may contain a ‘%d’ expression to print a following argument. ‘%d’ prints the argument as a decimal, so the message will say something such as ‘Line 243’.

The number that is printed in place of the ‘%d’ is computed by the last line of the function:

(1+ (count-lines 1 (point)))

What this does is count the lines from the first position of the buffer, indicated by the 1, up to (point), and then add one to that number. (The 1+ function adds one to its argument.) We add one to it because line 2 has only one line before it, and count-lines counts only the lines before the current line.

After count-lines has done its job, and the message has been printed in the echo area, the save-excursion restores point to its original position; and save-restriction restores the original narrowing, if any.

6.3 Exercise with Narrowing

Write a function that will display the first 60 characters of the current buffer, even if you have narrowed the buffer to its latter half so that the first line is inaccessible. Restore point, mark, and narrowing. For this exercise, you need to use a whole potpourri of functions, including save-restriction, widen, goto-char, point-min, message, and buffer-substring.

(buffer-substring is a previously unmentioned function you will have to investigate yourself; or perhaps you will have to use buffer-substring-no-properties or filter-buffer-substring …, yet other functions. Text properties are a feature otherwise not discussed here. See Text Properties in The GNU Emacs Lisp Reference Manual.)

Additionally, do you really need goto-char or point-min? Or can you write the function without them?

7.1 car and cdr

The CAR of a list is, quite simply, the first item in the list. Thus the CAR of the list (rose violet daisy buttercup) is rose.

If you are reading this in Info in GNU Emacs, you can see this by evaluating the following:

(car '(rose violet daisy buttercup))

After evaluating the expression, rose will appear in the echo area.

car does not remove the first item from the list; it only reports what it is. After car has been applied to a list, the list is still the same as it was. In the jargon, car is “non-destructive”. This feature turns out to be important.

The CDR of a list is the rest of the list, that is, the cdr function returns the part of the list that follows the first item. Thus, while the CAR of the list '(rose violet daisy buttercup) is rose, the rest of the list, the value returned by the cdr function, is (violet daisy buttercup).

You can see this by evaluating the following in the usual way:

(cdr '(rose violet daisy buttercup))

When you evaluate this, (violet daisy buttercup) will appear in the echo area.

Like car, cdr does not remove any elements from the list—it just returns a report of what the second and subsequent elements are.

Incidentally, in the example, the list of flowers is quoted. If it were not, the Lisp interpreter would try to evaluate the list by calling rose as a function. In this example, we do not want to do that.

For operating on lists, the names first and rest would make more sense than the names car and cdr. Indeed, some programmers define first and rest as aliases for car and cdr, then write first and rest in their code.

However, lists in Lisp are built using a lower-level structure known as “cons cells” (see How Lists are Implemented), in which there is no such thing as “first” or “rest”, and the CAR and the CDR are symmetrical. Lisp does not try to hide the existence of cons cells, and programs do use them for things other than lists. For this reason, the names are helpful for reminding programmers that car and cdr are in fact symmetrical, despite the asymmetrical way they are used in lists.

When car and cdr are applied to a list made up of symbols, such as the list (pine fir oak maple), the element of the list returned by the function car is the symbol pine without any parentheses around it. pine is the first element in the list. However, the CDR of the list is a list itself, (fir oak maple), as you can see by evaluating the following expressions in the usual way:

(car '(pine fir oak maple))

(cdr '(pine fir oak maple))

On the other hand, in a list of lists, the first element is itself a list. car returns this first element as a list. For example, the following list contains three sub-lists, a list of carnivores, a list of herbivores and a list of sea mammals:

(car '((lion tiger cheetah)
       (gazelle antelope zebra)
       (whale dolphin seal)))

In this example, the first element or CAR of the list is the list of carnivores, (lion tiger cheetah), and the rest of the list is ((gazelle antelope zebra) (whale dolphin seal)).

(cdr '((lion tiger cheetah)
       (gazelle antelope zebra)
       (whale dolphin seal)))

It is worth saying again that car and cdr are non-destructive—that is, they do not modify or change lists to which they are applied. This is very important for how they are used.

Also, in the first chapter, in the discussion about atoms, I said that in Lisp, certain kinds of atom, such as an array, can be separated into parts; but the mechanism for doing this is different from the mechanism for splitting a list. As far as Lisp is concerned, the atoms of a list are unsplittable. (See Lisp Atoms.) The car and cdr functions are used for splitting lists and are considered fundamental to Lisp. Since they cannot split or gain access to the parts of an array, an array is considered an atom. Conversely, the other fundamental function, cons, can put together or construct a list, but not an array. (Arrays are handled by array-specific functions. See Arrays in The GNU Emacs Lisp Reference Manual.)

7.2 cons

The cons function constructs lists; it is the inverse of car and cdr. For example, cons can be used to make a four element list from the three element list, (fir oak maple):

(cons 'pine '(fir oak maple))

After evaluating this list, you will see

(pine fir oak maple)

appear in the echo area. cons causes the creation of a new list in which the element is followed by the elements of the original list.

We often say that cons puts a new element at the beginning of a list, or that it attaches or pushes elements onto the list, but this phrasing can be misleading, since cons does not change an existing list, but creates a new one.

Like car and cdr, cons is non-destructive.

• Build a list
• Find the Length of a List: length

(cons 'buttercup ())
     ⇒ (buttercup)

(cons 'daisy '(buttercup))
     ⇒ (daisy buttercup)

(cons 'violet '(daisy buttercup))
     ⇒ (violet daisy buttercup)

(cons 'rose '(violet daisy buttercup))
     ⇒ (rose violet daisy buttercup)

(length '(buttercup))
     ⇒ 1

(length '(daisy buttercup))
     ⇒ 2

(length (cons 'violet '(daisy buttercup)))
     ⇒ 3

(length ())
     ⇒ 0

(length )

Lisp error: (wrong-number-of-arguments length 0)

7.3 nthcdr

The nthcdr function is associated with the cdr function. What it does is take the CDR of a list repeatedly.

If you take the CDR of the list (pine fir oak maple), you will be returned the list (fir oak maple). If you repeat this on what was returned, you will be returned the list (oak maple). (Of course, repeated CDRing on the original list will just give you the original CDR since the function does not change the list. You need to evaluate the CDR of the CDR and so on.) If you continue this, eventually you will be returned an empty list, which in this case, instead of being shown as () is shown as nil.

For review, here is a series of repeated CDRs, the text following the ‘⇒’ shows what is returned.

(cdr '(pine fir oak maple))
     ⇒ (fir oak maple)

(cdr '(fir oak maple))
     ⇒ (oak maple)

(cdr '(oak maple))
     ⇒ (maple)

(cdr '(maple))
     ⇒ nil

(cdr 'nil)
     ⇒ nil

(cdr ())
     ⇒ nil

You can also do several CDRs without printing the values in between, like this:

(cdr (cdr '(pine fir oak maple)))
     ⇒ (oak maple)

In this example, the Lisp interpreter evaluates the innermost list first. The innermost list is quoted, so it just passes the list as it is to the innermost cdr. This cdr passes a list made up of the second and subsequent elements of the list to the outermost cdr, which produces a list composed of the third and subsequent elements of the original list. In this example, the cdr function is repeated and returns a list that consists of the original list without its first two elements.

The nthcdr function does the same as repeating the call to cdr. In the following example, the argument 2 is passed to the function nthcdr, along with the list, and the value returned is the list without its first two items, which is exactly the same as repeating cdr twice on the list:

(nthcdr 2 '(pine fir oak maple))
     ⇒ (oak maple)

Using the original four element list, we can see what happens when various numeric arguments are passed to nthcdr, including 0, 1, and 5:

;; Leave the list as it was.
(nthcdr 0 '(pine fir oak maple))
     ⇒ (pine fir oak maple)

;; Return a copy without the first element.
(nthcdr 1 '(pine fir oak maple))
     ⇒ (fir oak maple)

;; Return a copy of the list without three elements.
(nthcdr 3 '(pine fir oak maple))
     ⇒ (maple)

;; Return a copy lacking all four elements.
(nthcdr 4 '(pine fir oak maple))
     ⇒ nil

;; Return a copy lacking all elements.
(nthcdr 5 '(pine fir oak maple))
     ⇒ nil

7.4 nth

The nthcdr function takes the CDR of a list repeatedly. The nth function takes the CAR of the result returned by nthcdr. It returns the Nth element of the list.

Thus, if it were not defined in C for speed, the definition of nth would be:

(defun nth (n list)
  "Returns the Nth element of LIST.
N counts from zero.  If LIST is not that long, nil is returned."
  (car (nthcdr n list)))

(Originally, nth was defined in Emacs Lisp in subr.el, but its definition was redone in C in the 1980s.)

The nth function returns a single element of a list. This can be very convenient.

Note that the elements are numbered from zero, not one. That is to say, the first element of a list, its CAR is the zeroth element. This zero-based counting often bothers people who are accustomed to the first element in a list being number one, which is one-based.

For example:

(nth 0 '("one" "two" "three"))
    ⇒ "one"

(nth 1 '("one" "two" "three"))
    ⇒ "two"

It is worth mentioning that nth, like nthcdr and cdr, does not change the original list—the function is non-destructive. This is in sharp contrast to the setcar and setcdr functions.

7.5 setcar

As you might guess from their names, the setcar and setcdr functions set the CAR or the CDR of a list to a new value. They actually change the original list, unlike car and cdr which leave the original list as it was. One way to find out how this works is to experiment. We will start with the setcar function.

First, we can make a list and then set the value of a variable to the list, using the setq special form. Because we intend to use setcar to change the list, this setq should not use the quoted form '(antelope giraffe lion tiger), as that would yield a list that is part of the program and bad things could happen if we tried to change part of the program while running it. Generally speaking an Emacs Lisp program’s components should be constant (or unchanged) while the program is running. So we instead construct an animal list by using the list function, as follows:

(setq animals (list 'antelope 'giraffe 'lion 'tiger))

If you are reading this in Info inside of GNU Emacs, you can evaluate this expression in the usual fashion, by positioning the cursor after the expression and typing C-x C-e. (I’m doing this right here as I write this. This is one of the advantages of having the interpreter built into the computing environment. Incidentally, when there is nothing on the line after the final parentheses, such as a comment, point can be on the next line. Thus, if your cursor is in the first column of the next line, you do not need to move it. Indeed, Emacs permits any amount of white space after the final parenthesis.)

When we evaluate the variable animals, we see that it is bound to the list (antelope giraffe lion tiger):

animals
     ⇒ (antelope giraffe lion tiger)

Put another way, the variable animals points to the list (antelope giraffe lion tiger).

Next, evaluate the function setcar while passing it two arguments, the variable animals and the quoted symbol hippopotamus; this is done by writing the three element list (setcar animals 'hippopotamus) and then evaluating it in the usual fashion:

(setcar animals 'hippopotamus)

After evaluating this expression, evaluate the variable animals again. You will see that the list of animals has changed:

animals
     ⇒ (hippopotamus giraffe lion tiger)

The first element on the list, antelope is replaced by hippopotamus.

So we can see that setcar did not add a new element to the list as cons would have; it replaced antelope with hippopotamus; it changed the list.

7.6 setcdr

The setcdr function is similar to the setcar function, except that the function replaces the second and subsequent elements of a list rather than the first element.

(To see how to change the last element of a list, look ahead to The kill-new function, which uses the nthcdr and setcdr functions.)

To see how this works, set the value of the variable to a list of domesticated animals by evaluating the following expression:

(setq domesticated-animals (list 'horse 'cow 'sheep 'goat))

If you now evaluate the list, you will be returned the list (horse cow sheep goat):

domesticated-animals
     ⇒ (horse cow sheep goat)

Next, evaluate setcdr with two arguments, the name of the variable which has a list as its value, and the list to which the CDR of the first list will be set;

(setcdr domesticated-animals '(cat dog))

If you evaluate this expression, the list (cat dog) will appear in the echo area. This is the value returned by the function. The result we are interested in is the side effect, which we can see by evaluating the variable domesticated-animals:

domesticated-animals
     ⇒ (horse cat dog)

Indeed, the list is changed from (horse cow sheep goat) to (horse cat dog). The CDR of the list is changed from (cow sheep goat) to (cat dog).

7.7 Exercise

Construct a list of four birds by evaluating several expressions with cons. Find out what happens when you cons a list onto itself. Replace the first element of the list of four birds with a fish. Replace the rest of that list with a list of other fish.

8.1 zap-to-char

Let us look at the interactive zap-to-char function.

• The Complete zap-to-char Implementation
• The interactive Expression
• The Body of zap-to-char
• The search-forward Function
• The progn Special Form
• Summing up zap-to-char

(defun zap-to-char (arg char)
  "Kill up to and including ARG'th occurrence of CHAR.
Case is ignored if `case-fold-search' is non-nil in the current buffer.
Goes backward if ARG is negative; error if CHAR not found."
  (interactive "p\ncZap to char: ")
  (if (char-table-p translation-table-for-input)
      (setq char (or (aref translation-table-for-input char) char)))
  (kill-region (point) (progn
                         (search-forward (char-to-string char)
                                         nil nil arg)
                         (point))))

(interactive "p\ncZap to char: ")

(if (char-table-p translation-table-for-input)
    (setq char (or (aref translation-table-for-input char) char)))
(kill-region (point) (progn
                       (search-forward (char-to-string char) nil nil arg)
                       (point)))

(search-forward (char-to-string char) nil nil arg)

(search-forward "target-string"
                limit-of-search
                what-to-do-if-search-fails
                repeat-count)

(progn
  body…)

8.2 kill-region

The zap-to-char function uses the kill-region function. This function clips text from a region and copies that text to the kill ring, from which it may be retrieved.

The Emacs 22 version of that function uses condition-case and copy-region-as-kill, both of which we will explain. condition-case is an important special form.

In essence, the kill-region function calls condition-case, which takes three arguments. In this function, the first argument does nothing. The second argument contains the code that does the work when all goes well. The third argument contains the code that is called in the event of an error.

• The Complete kill-region Definition
• condition-case
• Lisp macro

(defun kill-region (beg end)
  "Kill (\"cut\") text between point and mark.
This deletes the text from the buffer and saves it in the kill ring.
The command \\[yank] can retrieve it from there. … "

  ;; • Since order matters, pass point first.
  (interactive (list (point) (mark)))
  ;; • And tell us if we cannot cut the text.
  ;; 'unless' is an 'if' without a then-part.
  (unless (and beg end)
    (error "The mark is not set now, so there is no region"))

  ;; • 'condition-case' takes three arguments.
  ;;    If the first argument is nil, as it is here,
  ;;    information about the error signal is not
  ;;    stored for use by another function.
  (condition-case nil

      ;; • The second argument to 'condition-case' tells the
      ;;    Lisp interpreter what to do when all goes well.

      ;;    It starts with a 'let' function that extracts the string
      ;;    and tests whether it exists.  If so (that is what the
      ;;    'when' checks), it calls an 'if' function that determines
      ;;    whether the previous command was another call to
      ;;    'kill-region'; if it was, then the new text is appended to
      ;;    the previous text; if not, then a different function,
      ;;    'kill-new', is called.

      ;;    The 'kill-append' function concatenates the new string and
      ;;    the old.  The 'kill-new' function inserts text into a new
      ;;    item in the kill ring.

      ;;    'when' is an 'if' without an else-part.  The second 'when'
      ;;    again checks whether the current string exists; in
      ;;    addition, it checks whether the previous command was
      ;;    another call to 'kill-region'.  If one or the other
      ;;    condition is true, then it sets the current command to
      ;;    be 'kill-region'.

      (let ((string (filter-buffer-substring beg end t)))
        (when string                    ;STRING is nil if BEG = END
          ;; Add that string to the kill ring, one way or another.
          (if (eq last-command 'kill-region)

              ;;    - 'yank-handler' is an optional argument to
              ;;    'kill-region' that tells the 'kill-append' and
              ;;    'kill-new' functions how deal with properties
              ;;    added to the text, such as 'bold' or 'italics'.
              (kill-append string (< end beg) yank-handler)
            (kill-new string nil yank-handler)))
        (when (or string (eq last-command 'kill-region))
          (setq this-command 'kill-region))
        nil)

    ;;  • The third argument to 'condition-case' tells the interpreter
    ;;    what to do with an error.

    ;;    The third argument has a conditions part and a body part.
    ;;    If the conditions are met (in this case,
    ;;             if text or buffer are read-only)
    ;;    then the body is executed.

    ;;    The first part of the third argument is the following:
    ((buffer-read-only text-read-only) ;; the if-part
     ;; …  the then-part
     (copy-region-as-kill beg end)

     ;;    Next, also as part of the then-part, set this-command, so
     ;;    it will be set in an error
     (setq this-command 'kill-region)
     ;;    Finally, in the then-part, send a message if you may copy
     ;;    the text to the kill ring without signaling an error, but
     ;;    don't if you may not.

     (if kill-read-only-ok
         (progn (message "Read only text copied to kill ring") nil)
       (barf-if-buffer-read-only)
       ;; If the buffer isn't read-only, the text is.
       (signal 'text-read-only (list (current-buffer)))))))

(condition-case
  var
  bodyform
  error-handler…)

If no errors, run only this code
    but, if errors, run this other code.

(if (eq last-command 'kill-region)
    (kill-append string (< end beg) yank-handler)
  (kill-new string nil yank-handler))

(kill-append string (< end beg) yank-handler)

8.3 copy-region-as-kill

The copy-region-as-kill function copies a region of text from a buffer and (via either kill-append or kill-new) saves it in the kill-ring.

If you call copy-region-as-kill immediately after a kill-region command, Emacs appends the newly copied text to the previously copied text. This means that if you yank back the text, you get it all, from both this and the previous operation. On the other hand, if some other command precedes the copy-region-as-kill, the function copies the text into a separate entry in the kill ring.

• The complete copy-region-as-kill function definition
• The Body of copy-region-as-kill

(defun copy-region-as-kill (beg end)
  "Save the region as if killed, but don't kill it.
In Transient Mark mode, deactivate the mark.
If `interprogram-cut-function' is non-nil, also save the text for a window
system cut and paste."
  (interactive "r")

  (if (eq last-command 'kill-region)
      (kill-append (filter-buffer-substring beg end) (< end beg))
    (kill-new (filter-buffer-substring beg end)))

  (if transient-mark-mode
      (setq deactivate-mark t))
  nil)

(defun copy-region-as-kill (argument-list)
  "documentation…"
  (interactive "r")
  body…)

  (if (eq last-command 'kill-region)
      ;; then-part
      (kill-append  (filter-buffer-substring beg end) (< end beg))
    ;; else-part
    (kill-new  (filter-buffer-substring beg end)))

(defun kill-append (string before-p &optional yank-handler)
  "Append STRING to the end of the latest kill in the kill ring.
If BEFORE-P is non-nil, prepend STRING to the kill.
… "
  (let* ((cur (car kill-ring)))
    (kill-new (if before-p (concat string cur) (concat cur string))
              (or (= (length cur) 0)
                  (equal yank-handler
                         (get-text-property 0 'yank-handler cur)))
              yank-handler)))

(if before-p                            ; if-part
    (concat string cur)                 ; then-part
  (concat cur string))                  ; else-part

(concat string cur)

(concat cur string))

(concat "abc" "def")
     ⇒ "abcdef"

(concat "new "
        (car '("first element" "second element")))
     ⇒ "new first element"

(concat (car
        '("first element" "second element")) " modified")
     ⇒ "first element modified"

(defun kill-new (string &optional replace yank-handler)
  "Make STRING the latest kill in the kill ring.
Set `kill-ring-yank-pointer' to point to it.

If `interprogram-cut-function' is non-nil, apply it to STRING.
Optional second argument REPLACE non-nil means that STRING will replace
the front of the kill ring, rather than being added to the list.
…"

  (if (> (length string) 0)
      (if yank-handler
          (put-text-property 0 (length string)
                             'yank-handler yank-handler string))
    (if yank-handler
        (signal 'args-out-of-range
                (list string "yank-handler specified for empty string"))))

  (if (fboundp 'menu-bar-update-yank-menu)
      (menu-bar-update-yank-menu string (and replace (car kill-ring))))

  (if (and replace kill-ring)
      (setcar kill-ring string)
    (push string kill-ring)
    (if (> (length kill-ring) kill-ring-max)
        (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))

  (setq kill-ring-yank-pointer kill-ring)
  (if interprogram-cut-function
      (funcall interprogram-cut-function string (not replace))))

Make STRING the latest kill in the kill ring.

  (if (and replace kill-ring)
      ;; then
      (setcar kill-ring string)

    ;; else
    (push string kill-ring)

    (if (> (length kill-ring) kill-ring-max)
        ;; avoid overly long kill ring
        (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil)))

  (setq kill-ring-yank-pointer kill-ring)
  (if interprogram-cut-function
      (funcall interprogram-cut-function string (not replace))))

(setcar kill-ring string)

(push string kill-ring)

(setq kill-ring (cons string kill-ring))

(add-to-list kill-ring string)

(setq example-list '("here is a clause" "another clause"))

example-list
     ⇒ ("here is a clause" "another clause")

(push "a third clause" example-list)

example-list
     ⇒ ("a third clause" "here is a clause" "another clause")

(if (> (length kill-ring) kill-ring-max)
    (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))

(setq trees (list 'maple 'oak 'pine 'birch))
     ⇒ (maple oak pine birch)

(setcdr (nthcdr 2 trees) nil)
     ⇒ nil

trees
     ⇒ (maple oak pine)

(setq kill-ring-yank-pointer kill-ring)

  (if (fboundp 'menu-bar-update-yank-menu)
       (menu-bar-update-yank-menu string (and replace (car kill-ring))))

  (if interprogram-cut-function
      (funcall interprogram-cut-function string (not replace))))

8.4 Digression into C

The copy-region-as-kill function (see copy-region-as-kill) uses the filter-buffer-substring function, which in turn uses the delete-and-extract-region function. It removes the contents of a region and you cannot get them back.

Unlike the other code discussed here, the delete-and-extract-region function is not written in Emacs Lisp; it is written in C and is one of the primitives of the GNU Emacs system. Since it is very simple, I will digress briefly from Lisp and describe it here.

Like many of the other Emacs primitives, delete-and-extract-region is written as an instance of a C macro, a macro being a template for code. The complete macro looks like this:

DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
       Sdelete_and_extract_region, 2, 2, 0,
       doc: /* Delete the text between START and END and return it.  */)
  (Lisp_Object start, Lisp_Object end)
{
  validate_region (&start, &end);
  if (XFIXNUM (start) == XFIXNUM (end))
    return empty_unibyte_string;
  return del_range_1 (XFIXNUM (start), XFIXNUM (end), 1, 1);
}

Without going into the details of the macro writing process, let me point out that this macro starts with the word DEFUN. The word DEFUN was chosen since the code serves the same purpose as defun does in Lisp. (The DEFUN C macro is defined in emacs/src/lisp.h.)

The word DEFUN is followed by seven parts inside of parentheses:

• The first part is the name given to the function in Lisp, delete-and-extract-region.
• The second part is the name of the function in C, Fdelete_and_extract_region. By convention, it starts with ‘F’. Since C does not use hyphens in names, underscores are used instead.
• The third part is the name for the C constant structure that records information on this function for internal use. It is the name of the function in C but begins with an ‘S’ instead of an ‘F’.
• The fourth and fifth parts specify the minimum and maximum number of arguments the function can have. This function demands exactly 2 arguments.
• The sixth part is nearly like the argument that follows the interactive declaration in a function written in Lisp: a letter followed, perhaps, by a prompt. The only difference from Lisp is when the macro is called with no arguments. Then you write a 0 (which is a null string), as in this macro.

  If you were to specify arguments, you would place them between quotation marks. The C macro for goto-char includes "NGoto char: " in this position to indicate that the function expects a raw prefix, in this case, a numerical location in a buffer, and provides a prompt.

• The seventh part is a documentation string, just like the one for a function written in Emacs Lisp. This is written as a C comment. (When you build Emacs, the program lib-src/make-docfile extracts these comments and uses them to make the documentation.)

In a C macro, the formal parameters come next, with a statement of what kind of object they are, followed by the body of the macro. For delete-and-extract-region the body consists of the following four lines:

validate_region (&start, &end);
if (XFIXNUM (start) == XFIXNUM (end))
  return empty_unibyte_string;
return del_range_1 (XFIXNUM (start), XFIXNUM (end), 1, 1);

The validate_region function checks whether the values passed as the beginning and end of the region are the proper type and are within range. If the beginning and end positions are the same, then return an empty string.

The del_range_1 function actually deletes the text. It is a complex function we will not look into. It updates the buffer and does other things. However, it is worth looking at the two arguments passed to del_range_1. These are XFIXNUM (start) and XFIXNUM (end).

As far as the C language is concerned, start and end are two opaque values that mark the beginning and end of the region to be deleted. More precisely, and requiring more expert knowledge to understand, the two values are of type Lisp_Object, which might be a C pointer, a C integer, or a C struct; C code ordinarily should not care how Lisp_Object is implemented.

Lisp_Object widths depend on the machine, and are typically 32 or 64 bits. A few of the bits are used to specify the type of information; the remaining bits are used as content.

‘XFIXNUM’ is a C macro that extracts the relevant integer from the longer collection of bits; the type bits are discarded.

The command in delete-and-extract-region looks like this:

del_range_1 (XFIXNUM (start), XFIXNUM (end), 1, 1);

It deletes the region between the beginning position, start, and the ending position, end.

From the point of view of the person writing Lisp, Emacs is all very simple; but hidden underneath is a great deal of complexity to make it all work.

8.5 Initializing a Variable with defvar

The copy-region-as-kill function is written in Emacs Lisp. Two functions within it, kill-append and kill-new, copy a region in a buffer and save it in a variable called the kill-ring. This section describes how the kill-ring variable is created and initialized using the defvar special form.

(Again we note that the term kill-ring is a misnomer. The text that is clipped out of the buffer can be brought back; it is not a ring of corpses, but a ring of resurrectable text.)

In Emacs Lisp, a variable such as the kill-ring is created and given an initial value by using the defvar special form. The name comes from “define variable”.

The defvar special form is similar to setq in that it sets the value of a variable. It is unlike setq in three ways: first, it marks the variable as “special” so that it is always dynamically bound, even when lexical-binding is t (see How let Binds Variables). Second, it only sets the value of the variable if the variable does not already have a value. If the variable already has a value, defvar does not override the existing value. Third, defvar has a documentation string.

(There is a related macro, defcustom, designed for variables that people customize. It has more features than defvar. (See Setting Variables with defcustom.)

• Seeing the Current Value of a Variable
• defvar and an asterisk

Documentation:
List of killed text sequences.
Since the kill ring is supposed to interact nicely with cut-and-paste
facilities offered by window systems, use of this variable should

interact nicely with `interprogram-cut-function' and
`interprogram-paste-function'.  The functions `kill-new',
`kill-append', and `current-kill' are supposed to implement this
interaction; you may want to use them instead of manipulating the kill
ring directly.

(defvar kill-ring nil
  "List of killed text sequences.
…")

(defvar shell-command-default-error-buffer nil
  "*Buffer name for `shell-command' … error output.
… ")

8.6 Review

Here is a brief summary of some recently introduced functions.

car

cdr

car returns the first element of a list; cdr returns the second and subsequent elements of a list.

For example:

(car '(1 2 3 4 5 6 7))
     ⇒ 1
(cdr '(1 2 3 4 5 6 7))
     ⇒ (2 3 4 5 6 7)

cons

cons constructs a list by prepending its first argument to its second argument.

For example:

(cons 1 '(2 3 4))
     ⇒ (1 2 3 4)

funcall

funcall evaluates its first argument as a function. It passes its remaining arguments to its first argument.

nthcdr

Return the result of taking CDR n times on a list. The “rest of the rest”, as it were.

For example:

(nthcdr 3 '(1 2 3 4 5 6 7))
     ⇒ (4 5 6 7)

setcar

setcdr

setcar changes the first element of a list; setcdr changes the second and subsequent elements of a list.

For example:

(setq triple (list 1 2 3))

(setcar triple '37)

triple
     ⇒ (37 2 3)

(setcdr triple '("foo" "bar"))

triple
     ⇒ (37 "foo" "bar")

progn

Evaluate each argument in sequence and then return the value of the last.

For example:

(progn 1 2 3 4)
     ⇒ 4

save-restriction

Record whatever narrowing is in effect in the current buffer, if any, and restore that narrowing after evaluating the arguments.

search-forward

Search for a string, and if the string is found, move point. With a regular expression, use the similar re-search-forward. (See Regular Expression Searches, for an explanation of regular expression patterns and searches.)

search-forward and re-search-forward take four arguments:

1. The string or regular expression to search for.
2. Optionally, the limit of the search.
3. Optionally, what to do if the search fails, return nil or an error message.
4. Optionally, how many times to repeat the search; if negative, the search goes backwards.

kill-region

delete-and-extract-region

copy-region-as-kill

kill-region cuts the text between point and mark from the buffer and stores that text in the kill ring, so you can get it back by yanking.

copy-region-as-kill copies the text between point and mark into the kill ring, from which you can get it by yanking. The function does not cut or remove the text from the buffer.

delete-and-extract-region removes the text between point and mark from the buffer and throws it away. You cannot get it back. (This is not an interactive command.)

8.7 Searching Exercises

• Write an interactive function that searches for a string. If the search finds the string, leave point after it and display a message that says “Found!”. (Do not use search-forward for the name of this function; if you do, you will overwrite the existing version of search-forward that comes with Emacs. Use a name such as test-search instead.)
• Write a function that prints the third element of the kill ring in the echo area, if any; if the kill ring does not contain a third element, print an appropriate message.

9.1 Symbols as a Chest of Drawers

In an earlier section, I suggested that you might imagine a symbol as being a chest of drawers. The function definition is put in one drawer, the value in another, and so on. What is put in the drawer holding the value can be changed without affecting the contents of the drawer holding the function definition, and vice versa.

Actually, what is put in each drawer is the address of the value or function definition. It is as if you found an old chest in the attic, and in one of its drawers you found a map giving you directions to where the buried treasure lies.

(In addition to its name, symbol definition, and variable value, a symbol has a drawer for a property list which can be used to record other information. Property lists are not discussed here; see Property Lists in The GNU Emacs Lisp Reference Manual.)

Here is a fanciful representation:

            Chest of Drawers            Contents of Drawers

            __   o0O0o   __
          /                 \
         ---------------------
        |    directions to    |            [map to]
        |     symbol name     |             bouquet
        |                     |
        +---------------------+
        |    directions to    |
        |  symbol definition  |             [none]
        |                     |
        +---------------------+
        |    directions to    |            [map to]
        |    variable value   |             (rose violet buttercup)
        |                     |
        +---------------------+
        |    directions to    |
        |    property list    |             [not described here]
        |                     |
        +---------------------+
        |/                   \|

9.2 Exercise

Set flowers to violet and buttercup. Cons two more flowers on to this list and set this new list to more-flowers. Set the CAR of flowers to a fish. What does the more-flowers list now contain?

10.1 Kill Ring Overview

The kill ring is a list of textual strings. This is what it looks like:

("some text" "a different piece of text" "yet more text")

If this were the contents of my kill ring and I pressed C-y, the string of characters saying ‘some text’ would be inserted in this buffer where my cursor is located.

The yank command is also used for duplicating text by copying it. The copied text is not cut from the buffer, but a copy of it is put on the kill ring and is inserted by yanking it back.

Three functions are used for bringing text back from the kill ring: yank, which is usually bound to C-y; yank-pop, which is usually bound to M-y; and rotate-yank-pointer, which is used by the two other functions.

These functions refer to the kill ring through a variable called the kill-ring-yank-pointer. Indeed, the insertion code for both the yank and yank-pop functions is:

(insert (car kill-ring-yank-pointer))

(Well, no more. In GNU Emacs 22, the function has been replaced by insert-for-yank which calls insert-for-yank-1 repetitively for each yank-handler segment. In turn, insert-for-yank-1 strips text properties from the inserted text according to yank-excluded-properties. Otherwise, it is just like insert. We will stick with plain insert since it is easier to understand.)

To begin to understand how yank and yank-pop work, it is first necessary to look at the kill-ring-yank-pointer variable.

10.2 The kill-ring-yank-pointer Variable

kill-ring-yank-pointer is a variable, just as kill-ring is a variable. It points to something by being bound to the value of what it points to, like any other Lisp variable.

Thus, if the value of the kill ring is:

("some text" "a different piece of text" "yet more text")

and the kill-ring-yank-pointer points to the second clause, the value of kill-ring-yank-pointer is:

("a different piece of text" "yet more text")

As explained in the previous chapter (see How Lists are Implemented), the computer does not keep two different copies of the text being pointed to by both the kill-ring and the kill-ring-yank-pointer. The words “a different piece of text” and “yet more text” are not duplicated. Instead, the two Lisp variables point to the same pieces of text. Here is a diagram:

kill-ring     kill-ring-yank-pointer
    |               |
    |      ___ ___  |     ___ ___      ___ ___
     ---> |   |   |  --> |   |   |    |   |   |
          |___|___|----> |___|___|--> |___|___|--> nil
            |              |            |
            |              |            |
            |              |             --> "yet more text"
            |              |
            |               --> "a different piece of text"
            |
             --> "some text"

Both the variable kill-ring and the variable kill-ring-yank-pointer are pointers. But the kill ring itself is usually described as if it were actually what it is composed of. The kill-ring is spoken of as if it were the list rather than that it points to the list. Conversely, the kill-ring-yank-pointer is spoken of as pointing to a list.

These two ways of talking about the same thing sound confusing at first but make sense on reflection. The kill ring is generally thought of as the complete structure of data that holds the information of what has recently been cut out of the Emacs buffers. The kill-ring-yank-pointer on the other hand, serves to indicate—that is, to point to—that part of the kill ring of which the first element (the CAR) will be inserted.

10.3 Exercises with yank and nthcdr

• Using C-h v (describe-variable), look at the value of your kill ring. Add several items to your kill ring; look at its value again. Using M-y (yank-pop), move all the way around the kill ring. How many items were in your kill ring? Find the value of kill-ring-max. Was your kill ring full, or could you have kept more blocks of text within it?
• Using nthcdr and car, construct a series of expressions to return the first, second, third, and fourth elements of a list.

11.1 while

The while special form tests whether the value returned by evaluating its first argument is true or false. This is similar to what the Lisp interpreter does with an if; what the interpreter does next, however, is different.

In a while expression, if the value returned by evaluating the first argument is false, the Lisp interpreter skips the rest of the expression (the body of the expression) and does not evaluate it. However, if the value is true, the Lisp interpreter evaluates the body of the expression and then again tests whether the first argument to while is true or false. If the value returned by evaluating the first argument is again true, the Lisp interpreter again evaluates the body of the expression.

The template for a while expression looks like this:

(while true-or-false-test
  body…)

• Looping with while
• A while Loop and a List
• An Example: print-elements-of-list
• A Loop with an Incrementing Counter
• Details of an Incrementing Loop
• Loop with a Decrementing Counter

(setq empty-list ())

empty-list

(setq animals '(gazelle giraffe lion tiger))

animals

(while animals
       …

(setq animals (cdr animals))

(while test-whether-list-is-empty
  body…
  set-list-to-cdr-of-list)

(setq animals '(gazelle giraffe lion tiger))

(defun print-elements-of-list (list)
  "Print each element of LIST on a line of its own."
  (while list
    (print (car list))
    (setq list (cdr list))))

(print-elements-of-list animals)

gazelle

giraffe

lion

tiger
nil

set-count-to-initial-value
(while (< count desired-number)         ; true-or-false-test
  body…
  (setq count (1+ count)))              ; incrementer

               *
              * *
             * * *
            * * * *

  (let ((total 0)
        (row-number 1))
    body…)

(<= row-number number-of-rows)

(setq total (+ total row-number))