6. Narrowing and Widening

Narrowing is a feature of Emacs that makes it possible for you to focus on a specific part of a buffer, and work without accidentally changing other parts. Narrowing is normally disabled since it can confuse novices.

The Advantages of Narrowing

With narrowing, the rest of a buffer is made invisible, as if it weren't there. This is an advantage if, for example, you want to replace a word in one part of a buffer but not in another: you narrow to the part you want and the replacement is carried out only in that section, not in the rest of the buffer. Searches will only work within a narrowed region, not outside of one, so if you are fixing a part of a document, you can keep yourself from accidentally finding parts you do not need to fix by narrowing just to the region you want. (The key binding for narrow-to-region is C-x n n.)

However, narrowing does make the rest of the buffer invisible, which can scare people who inadvertently invoke narrowing and think they have deleted a part of their file. Moreover, the undo command (which is usually bound to C-x u) does not turn off narrowing (nor should it), so people can become quite desperate if they do not know that they can return the rest of a buffer to visibility with the widen command. (The key binding for widen is C-x n w.)

Narrowing is just as useful to the Lisp interpreter as to a human. Often, an Emacs Lisp function is designed to work on just part of a buffer; or conversely, an Emacs Lisp function needs to work on all of a buffer that has been narrowed. The what-line function, for example, removes the narrowing from a buffer, if it has any narrowing and when it has finished its job, restores the narrowing to what it was. On the other hand, the count-lines function, which is called by what-line, uses narrowing to restrict itself to just that portion of the buffer in which it is interested and then restores the previous situation.

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 text of the function in full:

(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)))))))

The function 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 of the mark, and restores them 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 `%d', `%s', or `%c' to print arguments that follow the string. `%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 and mark to their original positions; 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 save-restriction, widen, goto-char, point-min, buffer-substring, message, and other functions, a whole potpourri.