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.

View in manual

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)))
  (with-buffer-unmodified-if-unchanged
    (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))))