Go to the previous, next section.

The  rotate-yank-pointer Function

The  rotate-yank-pointer function changes the element in the kill ring to which  kill-ring-yank-pointer points. For example, it can change  kill-ring-yank-pointer from pointing to the second element to point to the third element.

Here is the code for  rotate-yank-pointer :

(defun rotate-yank-pointer (arg)
  "Rotate the yanking point in the kill ring."
  (interactive "p")
  (let ((length (length kill-ring)))

    (if (zerop length)

        ;; then-part
        (error "Kill ring is empty")

      ;; else-part
      (setq kill-ring-yank-pointer
            (nthcdr (% (+ arg
                          (- length
                             (length
                              kill-ring-yank-pointer)))
                       length)
                    kill-ring)))))

The function looks complex, but as usual, it can be understood by taking it apart piece by piece. First look at it in skeletal form:

(defun rotate-yank-pointer (arg)
  "Rotate the yanking point in the kill ring."
  (interactive "p")
  (let varlist
    body@dots{})

This function takes one argument, called  arg . It has a brief documentation string; and it is interactive with a small `p', which means that the argument must be a processed prefix passed to the function as a number.

The body of the function definition is a  let expression, which itself has a body as well as a varlist.

The  let expression declares a variable that will be only usable within the bounds of this function. This variable is called  length and is bound to a value that is equal to the number of items in the kill ring. This is done by using the function called  length . (Note that this function has the same name as the variable called  length ; but one use of the word is to name the function and the other is to name the variable. The two are quite distinct. Similarly, an English speaker will distinguish between the meanings of the word `ship' when he says: "I must ship this package immediately." and "I must get aboard the ship immediately.")

The function  length tells the number of items there are in a list, so  (length kill-ring) returns the number of items there are in the kill ring.

Go to the previous, next section.