Function: pp-fill

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

Signature

(pp-fill BEG &optional END)

Documentation

Break lines in Lisp code between BEG and END so it fits within fill-column.

Presumes the current buffer has syntax and indentation properly configured for that. Designed under the assumption that the region occupies a single line, tho it should also work if that's not the case. Can also be called with a single argument, in which case it inserts and pretty-prints that arg at point.

Probably introduced at or before Emacs version 30.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/pp.el.gz
(defun pp-fill (beg &optional end)
  "Break lines in Lisp code between BEG and END so it fits within `fill-column'.
Presumes the current buffer has syntax and indentation properly
configured for that.
Designed under the assumption that the region occupies a single line,
tho it should also work if that's not the case.
Can also be called with a single argument, in which case
it inserts and pretty-prints that arg at point."
  (interactive "r")
  (if (null end) (pp--object beg #'pp-fill)
    (goto-char beg)
    (let* ((end (copy-marker end t))
           (avoid-unbreakable
            (lambda ()
              (and (memq (char-before) '(?# ?s ?f))
                   (memq (char-after) '(?\[ ?\())
                   (looking-back "#[sf]?" (- (point) 2))
                   (goto-char (match-beginning 0)))))
           (newline (lambda ()
                      (skip-chars-forward ")]}")
                      (unless (save-excursion (skip-chars-forward " \t") (eolp))
                        (funcall avoid-unbreakable)
                        (insert "\n")
                        (indent-according-to-mode)))))
      (while (progn (forward-comment (point-max))
                    (< (point) end))
        (let ((beg (point))
              ;; Whether we're in front of an element with paired delimiters.
              ;; Can be something funky like #'(lambda ..) or ,'#s(...)
              ;; Or also #^[..].
              (paired (when (looking-at "['`,#]*[[:alpha:]^]*\\([({[\"]\\)")
                        (match-beginning 1))))
          ;; Go to the end of the sexp.
          (goto-char (or (scan-sexps (or paired (point)) 1) end))
          (unless
              (and
               ;; The sexp is all on a single line.
               (save-excursion (not (search-backward "\n" beg t)))
               ;; And its end is within `fill-column'.
               (or (pp--within-fill-column-p)
                   ;; If the end of the sexp is beyond `fill-column',
                   ;; try to move the sexp to its own line.
                   (and
                    (save-excursion
                      (goto-char beg)
                      ;; We skip backward over open parens because cutting
                      ;; the line right after an open paren does not help
                      ;; reduce the indentation depth.
                      ;; Similarly, we prefer to cut before a "." than after
                      ;; it because it reduces the indentation depth.
                      (while
                          (progn
                            (funcall avoid-unbreakable)
                            (let ((pos (point)))
                              (skip-chars-backward " \t({[',.")
                              (while (and (memq (char-after) '(?\. ?\{))
                                          (not (memq (char-before)
                                                     '(nil ?\n ?\) \" ?\]))))
                                ;; `.' and `{' within symbols?  (Bug#76715)
                                (forward-char 1))
                              (not (eql pos (point))))))
                      (if (bolp)
                          ;; The sexp already starts on its own line.
                          (progn (goto-char beg) nil)
                        (setq beg (copy-marker beg t))
                        (if paired (setq paired (copy-marker paired t)))
                        ;; We could try to undo this insertion if it
                        ;; doesn't reduce the indentation depth, but I'm
                        ;; not sure it's worth the trouble.
                        (insert "\n") (indent-according-to-mode)
                        t))
                    ;; Check again if we moved the whole exp to a new line.
                    (pp--within-fill-column-p))))
            ;; The sexp is spread over several lines, and/or its end is
            ;; (still) beyond `fill-column'.
            (when (and paired (not (eq ?\" (char-after paired))))
              ;; The sexp has sub-parts, so let's try and spread
              ;; them over several lines.
              (save-excursion
                (goto-char beg)
                (when (looking-at "(\\([^][()\" \t\n;']+\\)")
                  ;; Inside an expression of the form (SYM ARG1
                  ;; ARG2 ... ARGn) where SYM has a `lisp-indent-function'
                  ;; property that's a number, insert a newline after
                  ;; the corresponding ARGi, because it tends to lead to
                  ;; more natural and less indented code.
                  (let* ((sym (intern-soft (match-string 1)))
                         (lif (and sym (get sym 'lisp-indent-function))))
                    (if (eq lif 'defun) (setq lif 2))
                    (when (natnump lif)
                      (goto-char (match-end 0))
                      ;; Do nothing if there aren't enough args.
                      (ignore-error scan-error
                        (forward-sexp lif)
                        (funcall newline))))))
              (save-excursion
                (pp-fill (1+ paired) (1- (point)))))
            ;; Now the sexp either ends beyond `fill-column' or is
            ;; spread over several lines (or both).  Either way, the
            ;; rest of the line should be moved to its own line.
            (funcall newline)))))))