GNU Info

Info Node: (elisp)Narrowing

(elisp)Narrowing


Prev: Excursions Up: Positions
Enter node , (file) or (file)node

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 most Emacs 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.

   Values such as positions or line numbers, which usually count from
the beginning of the buffer, do so despite narrowing, but the functions
which use them refuse to operate on text that is inaccessible.

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

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

 - Command: narrow-to-page 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 (Note:
     Standard Regexps).

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

 - 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 (Note:
     Nonlocal Exits).  Therefore, this construct is a clean way to
     narrow a buffer temporarily.

     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 and the mark; 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 ----------


automatically generated by info2www version 1.2.2.9