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, it 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.