Node:if & or, Next:Insert or, Previous:insert-buffer body, Up:insert-buffer

5.2.3 insert-buffer With an if Instead of an or

The job to be done is to make sure the value of buffer is a buffer itself and not the name of a buffer. If the value is the name, then the buffer itself must be got.

You can imagine yourself at a conference where an usher is wandering around holding a list with your name on it and looking for you: the usher is "bound" to your name, not to you; but when the usher finds you and takes your arm, the usher becomes "bound" to you.

In Lisp, you might describe this situation like this:

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

We want to do the same thing with a buffer--if we do not have the buffer itself, we want to get it.

Using a predicate called bufferp that tells us whether we have a buffer (rather than its name), we can write the code like this:

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

Here, the true-or-false-test of the if expression is (not (bufferp buffer)); and the then-part is the expression (setq buffer (get-buffer buffer)).

In the test, the function bufferp returns true if its argument is a buffer--but false if its argument is the name of the buffer. (The last character of the function name bufferp is the character p; as we saw earlier, such use of p is a convention that indicates that the function is a predicate, which is a term that means that the function will determine whether some property is true or false. See Using the Wrong Type Object as an Argument.)

The function not precedes the expression (bufferp buffer), so the true-or-false-test looks like this:

(not (bufferp buffer))

not is a function that returns true if its argument is false and false if its argument is true. So if (bufferp buffer) returns true, the not expression returns false and vice-versa: what is "not true" is false and what is "not false" is true.

Using this test, the if expression works as follows: when the value of the variable buffer is actually a buffer rather then its name, the true-or-false-test returns false and the if expression does not evaluate the then-part. This is fine, since we do not need to do anything to the variable buffer if it really is a buffer.

On the other hand, when the value of buffer is not a buffer itself, but the name of a buffer, the true-or-false-test returns true and the then-part of the expression is evaluated. In this case, the then-part is (setq buffer (get-buffer buffer)). This expression uses the get-buffer function to return an actual buffer itself, given its name. The setq then sets the variable buffer to the value of the buffer itself, replacing its previous value (which was the name of the buffer).