Info Catalog elisp: Excursions elisp: Positions

elisp: Narrowing

 
 29.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 (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.
 
  -- 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 &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 (
      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)))
 
  -- 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 (
      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; 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 ----------
 

Info Catalog elisp: Excursions elisp: Positions