Function: fill-paragraph

fill-paragraph is an interactive and byte-compiled function defined in fill.el.gz.

Signature

(fill-paragraph &optional JUSTIFY REGION)

Documentation

Fill paragraph at or after point.

If JUSTIFY is non-nil (interactively, with prefix argument), justify as well. If sentence-end-double-space is non-nil, then period followed by one space does not end a sentence, so don't break a line there. The variable fill-column controls the width for filling.

If fill-paragraph-function is non-nil, we call it (passing our argument to it), and if it returns non-nil, we simply return its value.

If fill-paragraph-function is nil, return the fill-prefix used for filling.

The REGION argument is non-nil if called interactively; in that case, if Transient Mark mode is enabled and the mark is active, call fill-region to fill each of the paragraphs in the active region, instead of just filling the current paragraph.

Probably introduced at or before Emacs version 1.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/textmodes/fill.el.gz
(defun fill-paragraph (&optional justify region)
  "Fill paragraph at or after point.

If JUSTIFY is non-nil (interactively, with prefix argument), justify as well.
If `sentence-end-double-space' is non-nil, then period followed by one
space does not end a sentence, so don't break a line there.
The variable `fill-column' controls the width for filling.

If `fill-paragraph-function' is non-nil, we call it (passing our
argument to it), and if it returns non-nil, we simply return its value.

If `fill-paragraph-function' is nil, return the `fill-prefix' used for filling.

The REGION argument is non-nil if called interactively; in that
case, if Transient Mark mode is enabled and the mark is active,
call `fill-region' to fill each of the paragraphs in the active
region, instead of just filling the current paragraph."
  (interactive (progn
		 (barf-if-buffer-read-only)
		 (list (if current-prefix-arg 'full) t)))
  (let ((hash (and (not (buffer-modified-p))
                   (buffer-hash))))
    (prog1
        (or
         ;; 1. Fill the region if it is active when called interactively.
         (and region transient-mark-mode mark-active
              (not (eq (region-beginning) (region-end)))
              (or (fill-region (region-beginning) (region-end) justify) t))
         ;; 2. Try fill-paragraph-function.
         (and (not (eq fill-paragraph-function t))
              (or fill-paragraph-function
                  (and (minibufferp (current-buffer))
                       (= 1 (point-min))))
              (let ((function (or fill-paragraph-function
                                  ;; In the minibuffer, don't count
                                  ;; the width of the prompt.
                                  'fill-minibuffer-function))
                    ;; If fill-paragraph-function is set, it probably
                    ;; takes care of comments and stuff.  If not, it
                    ;; will have to set fill-paragraph-handle-comment
                    ;; back to t explicitly or return nil.
                    (fill-paragraph-handle-comment nil)
                    (fill-paragraph-function t))
                (funcall function justify)))
         ;; 3. Try our syntax-aware filling code.
         (and fill-paragraph-handle-comment
              ;; Our code only handles \n-terminated comments right now.
              comment-start (equal comment-end "")
              (let ((fill-paragraph-handle-comment nil))
                (fill-comment-paragraph justify)))
         ;; 4. If it all fails, default to the good ol' text paragraph filling.
         (let ((before (point))
               (paragraph-start paragraph-start)
               ;; Fill prefix used for filling the paragraph.
               fill-pfx)
           ;; Try to prevent code sections and comment sections from being
           ;; filled together.
           (when (and fill-paragraph-handle-comment comment-start-skip)
             (setq paragraph-start
                   (concat paragraph-start "\\|[ \t]*\\(?:"
                           comment-start-skip "\\)")))
           (save-excursion
             ;; To make sure the return value of forward-paragraph is
             ;; meaningful, we have to start from the beginning of
             ;; line, otherwise skipping past the last few chars of a
             ;; paragraph-separator would count as a paragraph (and
             ;; not skipping any chars at EOB would not count as a
             ;; paragraph even if it is).
             (move-to-left-margin)
             (if (not (zerop (fill-forward-paragraph 1)))
                 ;; There's no paragraph at or after point: give up.
                 (setq fill-pfx "")
               (let ((end (point))
                     (beg (progn (fill-forward-paragraph -1) (point))))
                 (goto-char before)
                 (setq fill-pfx
                       (if use-hard-newlines
                           ;; Can't use fill-region-as-paragraph, since this
                           ;; paragraph may still contain hard newlines.  See
                           ;; fill-region.
                           (fill-region beg end justify)
                         (fill-region-as-paragraph beg end justify))))))
           fill-pfx))
      ;; If we didn't change anything in the buffer (and the buffer
      ;; was previously unmodified), then flip the modification status
      ;; back to "unchanged".
      (when (and hash
                 (equal hash (buffer-hash)))
        (set-buffer-modified-p nil)))))