Go to the previous, next section.

Initializing a Variable with  defvar

Unlike the  delete-region function, the  copy-region-as-kill function is written in Emacs Lisp. It copies a region in a buffer and saves it in a variable called the  kill-ring . This section describes how this variable is created and initialized.

(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 two ways: first, 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. Second,  defvar has a documentation string.

You can see the current value of a variable, any variable, by using the  describe-variable function, which is usually invoked by typing C-h v. If you type C-h v and then  kill-ring (followed by RET) when prompted, you will see what is in your current kill ring--this may be quite a lot! Conversely, if you have been doing nothing this Emacs session except read this document, you may have nothing in it. At the end of the `*Help*' buffer, you will see the documentation for  kill-ring :

List of killed text sequences.

The kill ring is defined by a  defvar in the following way:

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

In this variable definition, the variable is given an initial value of  nil , which makes sense, since if you have saved nothing, you want nothing back if you give a  yank command. The documentation string is written just like the documentation string of a  defun . As with the documentation string of the  defun , the first line of the documentation should be a complete sentence, since some commands, like  apropos , print only the first line of documentation. Succeeding lines should not be indented; otherwise they look odd when you use C-h v ( describe-variable ).

Most variables are internal to Emacs, but some are intended as options that you can readily set with the  edit-options command. (These settings last only for the duration of an editing session; to set a value permanently, write a `.emacs' file. See section Your `.emacs' File File}.)

A readily settable variable is distinguished from others in Emacs by an asterisk, `*', in the first column of its documentation string.

For example:

(defvar line-number-mode nil
  "*Non-nil means display line number in mode line.")

This means that you can use the  edit-options command to change the value of  line-number-mode .

Of course, you can also change the value of  line-number-mode by evaluating it within a  setq expression, like this:

(setq line-number-mode t)

@xref{Using setq, , Using

} setq }.

Go to the previous, next section.