31.4 Narrowing

Narrowing means limiting the text addressable by Emacs editing commands to a limited range of characters in a buffer. The text that remains addressable is called the accessible portion of the buffer.

Narrowing is specified with two buffer positions, which become the beginning and end of the accessible portion. For most editing commands and primitives, these positions replace the values of the beginning and end of the buffer. While narrowing is in effect, no text outside the accessible portion is displayed, and point cannot move outside the accessible portion. Note that narrowing does not alter actual buffer positions (see Point); it only determines which positions are considered the accessible portion of the buffer. Most functions refuse to operate on text that is outside the accessible portion.

Commands for saving buffers are unaffected by narrowing; they save the entire buffer regardless of any narrowing.

If you need to display in a single buffer several very different types of text, consider using an alternative facility described in Swapping Text Between Two Buffers.

Command: narrow-to-region start end

This function sets the accessible portion of the current buffer to start at start and end at end. Both arguments should be character positions.

In an interactive call, start and end are set to the bounds of the current region (point and the mark, with the smallest first).

However, when the narrowing has been set by with-restriction with a label argument (see below), narrow-to-region can be used only within the limits of that narrowing. If start or end are outside these limits, the corresponding limit set by with-restriction is used instead. To gain access to other portions of the buffer, use without-restriction with the same label.

Command: narrow-to-page &optional move-count

This function sets the accessible portion of the current buffer to include just the current page. An optional first argument move-count non-nil means to move forward or backward by move-count pages and then narrow to one page. The variable page-delimiter specifies where pages start and end (see Standard Regular Expressions Used in Editing).

In an interactive call, move-count is set to the numeric prefix argument.

Command: widen

This function cancels any narrowing in the current buffer, so that the entire contents are accessible. This is called widening. It is equivalent to the following expression:

(narrow-to-region 1 (1+ (buffer-size)))

However, when a narrowing has been set by with-restriction with a label argument (see below), the limits set by with-restriction are restored, instead of canceling the narrowing. To gain access to other portions of the buffer, use without-restriction with the same label.

Function: buffer-narrowed-p

This function returns non-nil if the buffer is narrowed, and nil otherwise.

Special Form: save-restriction body…

This special form saves the current bounds of the accessible portion, evaluates the body forms, and finally restores the saved bounds, thus restoring the same state of narrowing (or absence thereof) formerly in effect. The state of narrowing is restored even in the event of an abnormal exit via throw or error (see Nonlocal Exits). Therefore, this construct is a clean way to narrow a buffer temporarily.

This construct also saves and restores the narrowings that were set by with-restriction with a label argument (see below).

The value returned by save-restriction is that returned by the last form in body, or nil if no body forms were given.

Caution: it is easy to make a mistake when using the save-restriction construct. Read the entire description here before you try it.

If body changes the current buffer, save-restriction still restores the restrictions on the original buffer (the buffer whose restrictions it saved from), but it does not restore the identity of the current buffer.

save-restriction does not restore point; use save-excursion for that. If you use both save-restriction and save-excursion together, save-excursion should come first (on the outside). Otherwise, the old point value would be restored with temporary narrowing still in effect. If the old point value were outside the limits of the temporary narrowing, this would fail to restore it accurately.

Here is a simple example of correct use of save-restriction:

---------- Buffer: foo ----------
This is the contents of foo
This is the contents of foo
This is the contents of foo∗
---------- Buffer: foo ----------

(save-excursion
  (save-restriction
    (goto-char 1)
    (forward-line 2)
    (narrow-to-region 1 (point))
    (goto-char (point-min))
    (replace-string "foo" "bar")))

---------- Buffer: foo ----------
This is the contents of bar
This is the contents of bar
This is the contents of foo∗
---------- Buffer: foo ----------
Special Form: with-restriction start end [:label label] body

This special form saves the current bounds of the accessible portion of the buffer, sets the accessible portion to start at start and end at end, evaluates the body forms, and restores the saved bounds. In that case it is equivalent to

(save-restriction
  (narrow-to-region start end)
  body)

When the optional argument label, which is evaluated to get the label to use and must yield a non-nil value, is present, the narrowing is labeled. A labeled narrowing differs from a non-labeled one in several ways:

  • During the evaluation of the body form, narrow-to-region and widen can be used only within the start and end limits.
  • To lift the restriction introduced by with-restriction and gain access to other portions of the buffer, use without-restriction with the same label argument. (Another way to gain access to other portions of the buffer is to use an indirect buffer (see Indirect Buffers).)
  • Labeled narrowings can be nested.
  • Labeled narrowings can only be used in Lisp programs: they are never visible on display, and never interfere with narrowings set by the user.

If you use with-restriction with the optional label argument, we recommend documenting the label in the doc strings of the functions which use it, so that other Lisp programs your code calls could lift the labeled narrowing if and when it needs.

Special Form: without-restriction [:label label] body

This special form saves the current bounds of the accessible portion of the buffer, widens the buffer, evaluates the body forms, and restores the saved bounds. In that case it is equivalent to

(save-restriction
  (widen)
  body)

When the optional argument label is present, the narrowing set by with-restriction with the same label argument is lifted.