[nongnu] elpa/swift-mode 0d1ef0ef18: Add specialized comment fill function

[ELPA Syncer]

branch: elpa/swift-mode
commit 0d1ef0ef183398143b13fb8c76c1284df0d5e616
Author: Josh Caswell <woolsweatersoft@gmail.com>
Commit: taku0 <taku0@users.noreply.github.com>

    Add specialized comment fill function
    
    This incorporates certain Swift comment markup elements into comment
    filling, allowing `fill-paragraph` to nicely format most Swift doc
    comments.
    
    A new variable allows the user to configure their comment fill column
    differently from the code fill column, defaulting to 80.
    
    The implementation does not (yet) preserve indented lists or recognize
    fenced code blocks.
---
 swift-mode-fill.el                  | 188 ++++++++++++++++++++++++++++++++++++
 swift-mode.el                       |   4 +-
 test/swift-files/fill/comment.swift | 115 ++++++++++++++++++++++
 test/swift-mode-test-fill.el        | 146 ++++++++++++++++++++++++++++
 test/swift-mode-test-indent.el      |   2 +-
 test/swift-mode-test.el             |   4 +-
 6 files changed, 456 insertions(+), 3 deletions(-)

diff --git a/swift-mode-fill.el b/swift-mode-fill.el
new file mode 100644
index 0000000000..2b1bef47f0
--- /dev/null
+++ b/swift-mode-fill.el
@@ -0,0 +1,188 @@
+;;; swift-mode-fill.el --- Major-mode for Apple's Swift programming language, 
paragraph filling. -*- lexical-binding: t -*-
+
+;; Copyright (C) 2022 Josh Caswell
+
+;; Authors: Josh Caswell (https://github.com/woolsweater)
+
+;; This file is not part of GNU Emacs.
+
+;; This program is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Routines for paragraph filling
+
+;;; Code:
+
+(require 'rx)
+(require 'swift-mode-lexer)
+
+(defcustom swift-mode:comment-fill-column 80
+  "Fill column for comment wrapping in Swift code.
+
+This may be different than the fill column for the rest of the source.  See
+also `swift-mode:comment-fill-function'."
+  :type 'integer
+  :group 'swift
+  :safe 'integerp)
+
+(make-variable-buffer-local 'swift-mode:comment-fill-column)
+
+(defconst swift-mode:doc-comment-annotation-re
+  (let ((bullet '(any ?- ?+ ?*))
+        (any-spacing '(* blank))
+        (identifier '(+ (syntax word))))
+    (rx-to-string
+     `(seq
+       ;; Explicitly include indentation here, for `forward-paragraph'
+       ;; search (see usage of 'parstart' there)
+       ,any-spacing
+       ,bullet ,any-spacing ,identifier
+       ;; For '- parameter foo:'
+       (? ,any-spacing ,identifier)
+       ,any-spacing ?:)))
+  "Regex to match Swift documentation comment markup labels, like '- remark:'.
+
+This is used by `swift-mode:comment-fill-function' to extend
+`paragraph-start' such that the built-in fill functions recognize
+these elements as the beginnings of their own paragraphs.")
+
+(defsubst swift-mode:-find-slash-comment-edges (slashes)
+  "Helper for `swift-mode:comment-fill-function' handling '///' style.
+
+Search backwards and forwards for contiguous lines that
+open (after any indentation) with SLASHES.  Return the buffer
+locations for the beginning and end of the comment contents.  For
+this style of comment, the content beginning is after the first
+delimiter; the end is the end of the last contiguous line found.
+
+Point may be anywhere in the comment when this is called."
+  (let ((orig-point (point))
+        start end)
+    (back-to-indentation)
+    (while (and (not (bobp))
+                (looking-at-p slashes))
+      (forward-line -1)
+      (back-to-indentation))
+    (setq start (progn
+                  (search-forward slashes nil t)
+                  (point)))
+    (goto-char orig-point)
+    (while (and (not (eobp))
+                (looking-at-p slashes))
+      (forward-line 1)
+      (unless (eobp)
+        (back-to-indentation)))
+    (setq end (if (progn
+                    (back-to-indentation)
+                    (looking-at-p slashes))
+                  ;; Edge case: comment is last thing in buffer with no 
trailing
+                  ;; newline.
+                  (point-max)
+                (forward-line -1)
+                (move-end-of-line 1)
+                (point)))
+    (cons start end)))
+
+(defsubst swift-mode:-fix-up-star-comment-edges ()
+  "Helper for `swift-mode:comment-fill-function' handling '/**' style.
+
+Ensure each delimiter is on its own line, then return the buffer
+locations for the beginning and end of the comment
+contents (excluding the delimiters).
+
+Point is assumed to be just after the opening delimiter and its
+trailing whitespace (if any) when this is called."
+  (when (not (looking-at-p "\n"))
+    (delete-horizontal-space)
+    (insert-and-inherit "\n")
+    (indent-according-to-mode))
+
+  (let ((start (point))
+        (end (progn (re-search-forward "\\*+/")
+                    (match-beginning 0))))
+    (goto-char end)
+    (skip-chars-backward " \t")
+    (if (bolp)
+        (setq end (- (point) 1))
+      (insert-and-inherit "\n")
+      (indent-according-to-mode))
+    (cons start end)))
+
+(defun swift-mode:comment-fill-function (justify)
+  "Handle comment filling in Swift code.
+
+Delegates to `fill-region' with `fill-column' bound to the value of
+`swift-mode:comment-fill-column' so that comments can be wrapped at
+different width than the rest of the source source.  JUSTIFY is as the
+argument of the same name in `fill-region'.
+
+The function determines which style of comment is at or around
+point and does preliminary cleanup as needed (the built-in fill
+functions do not handle the '/**' style of comment particularly
+well)."
+  ;; TODO A leading star on an empty line screws up paragraph calculation.
+  ;; TODO Recognize fenced code blocks.
+  ;; TODO Handle trailing comments.
+  (let ((chunk (swift-mode:chunk-after)))
+    (if (not (or (swift-mode:chunk:comment-p chunk)
+                 (looking-at-p comment-start-skip)))
+        ;; If not in a comment, just let `fill-paragraph' try to handle it
+        nil
+      (save-match-data
+        (save-excursion
+          ;; Move to opening delimiter if not already there.
+          (let ((start (swift-mode:chunk:start chunk)))
+            (when start
+              (goto-char start)))
+          (skip-syntax-forward " ")
+
+          ;; We want these two bound to their special values when delegating to
+          ;; `fill-region'.
+          (let ((fill-column swift-mode:comment-fill-column)
+                (paragraph-start (concat
+                                  swift-mode:doc-comment-annotation-re
+                                  "\\|"
+                                  paragraph-start)))
+            (cond
+
+             ;; Slash-style comment
+             ((looking-at "/\\{2,\\}")
+              (let* ((slashes (match-string-no-properties 0))
+                     (edges (swift-mode:-find-slash-comment-edges slashes))
+                     (start (car edges))
+                     (end (cdr edges)))
+                ;; Factor the comment markers into paragraph recognition
+                (let ((paragraph-start (concat "[[:blank:]]*" slashes
+                                               "\\(?:" paragraph-start "\\)"))
+                      (paragraph-separate (concat "[[:blank:]]*" slashes
+                                                  "\\(?:" paragraph-separate
+                                                  "\\)")))
+                  (fill-region start end justify :preserve-spaces)
+                  (indent-region start end))))
+
+             ;; Star-style comment
+             ((re-search-forward "/\\*\\{2,\\} *" nil t)
+              (let* ((edges (swift-mode:-fix-up-star-comment-edges))
+                     (start (car edges))
+                     (end (cdr edges)))
+                (fill-region start end justify :preserve-spaces)
+                (indent-region start end))))))
+
+        ;; Make sure `fill-paragraph' does not undo our work.
+        t))))
+
+(provide 'swift-mode-fill)
+
+;;; swift-mode-fill.el ends here
diff --git a/swift-mode.el b/swift-mode.el
index cd8e10ecef..0bb0b42b7e 100644
--- a/swift-mode.el
+++ b/swift-mode.el
@@ -36,6 +36,7 @@
 
 (require 'swift-mode-lexer)
 (require 'swift-mode-indent)
+(require 'swift-mode-fill)
 (require 'swift-mode-font-lock)
 (require 'swift-mode-beginning-of-defun)
 (require 'swift-mode-repl)
@@ -147,7 +148,7 @@ Signal `scan-error' if it hits opening parentheses."
 
 ;;;###autoload
 (defsubst swift-mode:add-supported-extension-for-speedbar ()
-  "Register .swfit to speedbar."
+  "Register .swift to speedbar."
   (if (fboundp 'speedbar-add-supported-extension)
       (speedbar-add-supported-extension ".swift")
     (add-hook 'speedbar-load-hook
@@ -193,6 +194,7 @@ Signal `scan-error' if it hits opening parentheses."
   (setq-local fill-indent-according-to-mode t)
   (setq-local comment-multi-line t)
   (setq-local comment-line-break-function #'swift-mode:indent-new-comment-line)
+  (setq-local fill-paragraph-function #'swift-mode:comment-fill-function)
 
   (setq-local parse-sexp-lookup-properties t)
   (add-hook 'syntax-propertize-extend-region-functions
diff --git a/test/swift-files/fill/comment.swift 
b/test/swift-files/fill/comment.swift
new file mode 100644
index 0000000000..e5cc595db4
--- /dev/null
+++ b/test/swift-files/fill/comment.swift
@@ -0,0 +1,115 @@
+// swift-mode:test:case-begin (Slash style doc comment)
+
+/// Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
+/// tempor incididunt ut labore et dolore magna aliqua. Ut
+///
+/// - parameter foo: enim ad minim veniam, quis nostrud exercitation ullamco
+/// laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in
+/// reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
+/// pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui
+/// officia deserunt mollit anim id est laborum.
+/// - parameter bar: enim ad minim veniam, quis nostrud exercitation ullamco
+/// - returns: Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
+/// eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad 
minim
+/// veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
+/// commodo consequat. Duis aute irure dolor in reprehenderit in voluptate 
velit
+/// esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat
+/// cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id
+/// est laborum.
+///
+/// - warning: reprehenderit in voluptate velit esse
+
+// swift-mode:test:case-input-begin
+
+/// Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod 
tempor incididunt ut labore et
+/// dolore magna aliqua. Ut
+///
+/// - parameter foo: enim ad minim veniam, quis nostrud exercitation ullamco 
laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
+/// in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla 
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui 
officia deserunt mollit anim id est laborum.
+/// - parameter bar: enim ad minim veniam, quis nostrud exercitation ullamco
+/// - returns: Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed 
do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim 
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo 
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse 
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non 
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+///
+/// - warning: reprehenderit in voluptate velit esse
+
+// swift-mode:test:case-end (Slash style doc comment)
+
+// swift-mode:test:eval (setq swift-mode:comment-fill-column 96)
+// swift-mode:test:case-begin (Slash line comment)
+
+// Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod 
tempor incididunt ut
+// labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud 
exercitation ullamco
+
+// swift-mode:test:case-input-begin
+
+// Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod 
tempor incididunt ut labore et dolore magna
+// aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
+
+// swift-mode:test:case-end
+
+// swift-mode:test:eval (setq swift-mode:comment-fill-column 80)
+// swift-mode:test:case-begin (Star style doc comment)
+
+/**
+ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod 
tempor
+ incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+ nostrud exercitation ullamco
+
+ - parameter foo: laboris nisi ut
+ - parameter bar: aliquip ex ea commodo consequat. Duis aute irure dolor in
+ reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
+ pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui
+ officia deserunt mollit anim id est laborum.
+ - parameter baz: enim ad minim veniam, quis nostrud exercitation ullamco
+
+ - returns: Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
+ eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+ Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
+ aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in
+ voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
+ occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit 
anim
+ id est laborum.
+
+ - important: Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
+ eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
+ veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea 
commodo
+ consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
+ cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+ proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+ */
+
+// swift-mode:test:case-input-begin
+
+/**
+ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod 
tempor incididunt ut labore et dolore magna aliqua. Ut
+ enim ad minim veniam, quis nostrud exercitation ullamco
+
+ - parameter foo: laboris nisi ut
+ - parameter bar: aliquip ex ea commodo consequat. Duis aute irure dolor in 
reprehenderit
+ in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
+ occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit 
anim
+ id est laborum.
+ - parameter baz: enim ad minim veniam, quis nostrud exercitation ullamco
+
+ - returns: Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do 
eiusmod tempor incididunt ut labore
+ et dolore magna aliqua.
+
+ Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut 
aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in 
voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint 
occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim 
id est laborum.
+
+ - important: Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do 
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim 
veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo 
consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse 
cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non 
proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+ */
+
+// swift-mode:test:case-end (Star style doc comment)
+
+// swift-mode:test:case-begin (Star comment, single line)
+
+/**
+ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod 
tempor
+ incididunt ut
+ */
+
+// swift-mode:test:case-input-begin
+
+/** Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod 
tempor incididunt ut */
+
+// swift-mode:test:case-end (Star comment, single line)
diff --git a/test/swift-mode-test-fill.el b/test/swift-mode-test-fill.el
new file mode 100644
index 0000000000..c75d979d4a
--- /dev/null
+++ b/test/swift-mode-test-fill.el
@@ -0,0 +1,146 @@
+;;; swift-mode-test-fill.el --- Test for swift-mode: filling -*- 
lexical-binding: t -*-
+
+;; Copyright (C) 2016, 2022 taku0, Josh Caswell
+
+;; Authors: taku0 (https://github.com/taku0)
+;;        Josh Caswell (https://github.com/woolsweater)
+
+;; This file is not part of GNU Emacs.
+
+;; This program is free software: you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+;;; Commentary:
+
+;; Test for swift-mode: paragraph fill
+;; Execute swift-mode:run-test:fill interactively or in batch mode.
+
+;;; Code:
+
+(require 'swift-mode)
+(require 'swift-mode-fill)
+
+(defun swift-mode:run-test:fill
+    (&optional error-buffer error-counts progress-reporter)
+  "Run paragraph fill tests for `swift-mode'.
+
+ERROR-BUFFER is the buffer to collect errors.  ERROR-COUNTS is an
+association list holding counts of errors, updated destructively.
+PROGRESS-REPORTER is a `progress-reporter' used when the tests are run
+interactively."
+  (interactive)
+  (if (not swift-mode:test:running)
+      (swift-mode:run-test '(swift-mode:run-test:fill))
+    (let ((current-line 0))
+      (setq default-directory
+            (concat (file-name-as-directory swift-mode:test:basedir)
+                    (file-name-as-directory "swift-files")
+                    "fill"))
+
+      (dolist (swift-file (file-expand-wildcards "*.swift"))
+        (redisplay)
+        (with-temp-buffer
+          (switch-to-buffer (current-buffer))
+          (insert-file-contents-literally swift-file)
+          (swift-mode)
+          (setq current-line 0)
+          (while (not (eobp))
+            (when (not noninteractive)
+              (progress-reporter-update progress-reporter))
+            (setq current-line (1+ current-line))
+            (cond
+             ((= (line-beginning-position) (line-end-position))
+              ;; Empty line
+              nil)
+
+             ((looking-at ".*//.*swift-mode:test:eval\\(.*\\)")
+              (eval-region (match-beginning 1) (match-end 1)))
+
+             ((looking-at ".*//.*swift-mode:test:case-begin")
+              (progn
+                ;; Marker comments must have a blank line separating them from
+                ;; the test input or they will interfere with filling.
+                (forward-line 2)
+                (let*
+                    ((status (swift-mode:test-current-case-fill
+                              swift-file current-line error-buffer))
+                     (count-assoc (assq status error-counts)))
+                  (setcdr count-assoc (1+ (cdr count-assoc))))))
+
+             (t (swift-mode:show-error
+                 error-buffer swift-file current-line
+                 "warning" "Unexpected test case input")))
+            (forward-line)))))))
+
+(defun swift-mode:test-current-case-fill (swift-file current-line error-buffer)
+  "Run the current fill test case.
+
+This applies `fill-paragraph' to the input string and compares the result
+to the expected value.
+
+SWIFT-FILE is the filename of the current test case.
+CURRENT-LINE is the current line number.
+ERROR-BUFFER is the buffer to output errors."
+  (let (expected
+        computed
+        (status 'ok))
+    (setq expected (swift-mode:test-fill:capture-expected))
+    ;; Marker comments must have a blank line separating them from
+    ;; the test input or they will interfere with filling.
+    (forward-line 2)
+    (setq computed (swift-mode:test-fill:perform-fill))
+    (forward-line)
+
+    (when (not (string= expected computed))
+      (setq status 'error)
+
+      (swift-mode:show-error
+       error-buffer swift-file current-line
+       "error"
+       (concat "Fill region failure\n"
+               "Expected: ```\n" expected "```\n\n"
+               "Actual: ```\n" computed "```")))
+    status))
+
+(defsubst swift-mode:test-fill:capture-expected ()
+  "Collect the expected result for this test case into a string."
+  (let ((start (point))
+        (end (point)))
+    (while (not (looking-at ".*//.*swift-mode:test:case-input-begin"))
+      (setq end (point))
+      (forward-line))
+    (buffer-substring start end)))
+
+(defsubst swift-mode:test-fill:perform-fill ()
+  "Run `fill-paragraph' on the case's input, returning the resulting string."
+  (let ((start (point))
+        end)
+    (while (not (looking-at ".*//.*swift-mode:test:case-end"))
+      (setq end (point))
+      (forward-line))
+
+    ;; Filling should work correctly from any place inside the contents
+    (goto-char start)
+    (forward-char (random (- (1- end) start)))
+    (fill-paragraph)
+
+    ;; Newline characters may have been added; find new end
+    (beginning-of-line)
+    (while (not (looking-at ".*//.*swift-mode:test:case-end"))
+      (setq end (point))
+      (forward-line))
+    (buffer-substring start end)))
+
+(provide 'swift-mode-test-fill)
+
+;;; swift-mode-test-fill.el ends here
diff --git a/test/swift-mode-test-indent.el b/test/swift-mode-test-indent.el
index 950382a6c4..686e38c8d4 100644
--- a/test/swift-mode-test-indent.el
+++ b/test/swift-mode-test-indent.el
@@ -104,7 +104,7 @@ ERROR-BUFFER is the buffer to output errors."
        error-buffer swift-file current-line
        (if known-bug "warning" "error")
        (concat
-        (if known-bug "(knwon bug) " "")
+        (if known-bug "(known bug) " "")
         "indent: expected "
         (prin1-to-string original-indent)
         " but "
diff --git a/test/swift-mode-test.el b/test/swift-mode-test.el
index be38595f7b..f7ddffa8a7 100644
--- a/test/swift-mode-test.el
+++ b/test/swift-mode-test.el
@@ -30,6 +30,7 @@
 (require 'swift-mode-test-beginning-of-defun)
 (require 'swift-mode-test-imenu)
 (require 'swift-mode-test-font-lock)
+(require 'swift-mode-test-fill)
 
 (defvar swift-mode:test:basedir
   (file-name-directory (or load-file-name buffer-file-name)))
@@ -50,7 +51,8 @@ Return the error-buffer"
   '(swift-mode:run-test:indent
     swift-mode:run-test:beginning-of-defun
     swift-mode:run-test:imenu
-    swift-mode:run-test:font-lock))
+    swift-mode:run-test:font-lock
+    swift-mode:run-test:fill))
 
 (defun swift-mode:run-test (&optional tests)
   "Run TESTS for `swift-mode'."