[0005] fmt: 优化 #() 结构的格式化 (#775)

Author: da-liii

devel/0005.md

@@ -0,0 +1,42 @@
+# [0005] gf fmt reader vector 多行格式优化
+
+## 任务相关的代码文件
+- tools/fmt/liii/goldfmt-format.scm
+- tools/fmt/tests/liii/goldfmt-format/format-string-test.scm
+- tests/liii/json/json-to-string-test.scm
+
+## 如何测试
+```bash
+xmake b goldfish
+bin/gf fmt tools/fmt/
+bin/gf tests/tools/fmt/tests/liii/goldfmt-format/
+```
+
+## 2026/05/07 gf fmt reader vector 多行格式末尾添加 `) ;#` 标记
+
+### What
+优化 `gf fmt` 对 reader vector（`#(...)`）的多行格式输出，使其在跨行时末尾添加 `) ;#` 注释标记，提高可读性和括号匹配清晰度。
+
+1. 新增 `last-line-column` 函数：计算字符串最后一行的列号，用于精确控制内容在行内的起始位置
+2. 新增 `reader-append-close` 函数：判断在关闭括号前是否需要先换行（当末尾为 `;#` 时追加换行和缩进）
+3. `reader-append-rest` 函数新增 `close-indent` 参数：传递缩进上下文信息，使闭括号位置正确对齐
+4. `format-reader-vector-multiline` 中将末尾的 `)` 替换为 `\n) ;#`，并在 `reader-append-rest` 中传递正确缩进
+5. 优化 `reader-append-rest` 中 item 的缩进计算：使用 `last-line-column` 而非固定 `rest-indent`，使后续元素在已有内容后内联时位置更精确
+
+### Why
+之前多行 reader vector 的格式如：
+```scheme
+#((("text" . "1") ("type" . "text"))
+  (("text" . "2") ("type" . "text")))
+```
+多层嵌套时闭括号 `)` 混在一起难以区分。改为在末尾添加 `;#` 注释标记，配合换行和缩进，使 vector 的结尾一目了然：
+```scheme
+#((("text" . "1") ("type" . "text"))
+  (("text" . "2") ("type" . "text"))
+) ;#
+```
+
+### How
+- `reader-append-close` 通过检查结果字符串是否以 `;#` 结尾来判断是否需要先换行：如果是，则追加 `\n<缩进>)`；否则直接追加 `)`。这一设计确保了单行格式不受影响。
+- `last-line-column` 遍历字符串，遇到换行符则重置列号，否则累加，最终返回最后一行的列位置。
+- 测试用例同步更新：`json-to-string-test.scm` 和 `format-string-test.scm` 中的多行 reader vector 期望值全部更新为带 `) ;#` 的新格式。

tests/liii/json/json-to-string-test.scm

@@ -63,7 +63,9 @@
 
 (check (json->string '(("messages"
                         . #((("role" . "user") ("content" . #(1 2 3)))
-                            (("role" . "user") ("content" . "中文")))))
+                            (("role" . "user") ("content" . "中文"))
+                          ) ;#
+                       ))
        ) ;json->string
   =>
   "{\"messages\":[{\"role\":\"user\",\"content\":[1,2,3]},{\"role\":\"user\",\"content\":\"中文\"}]}"
@@ -74,8 +76,12 @@
                         . #((("role" . "user")
                              ("content"
                               . #((("text" . "1") ("type" . "text"))
-                                  (("text" . "2") ("type" . "text")))))
-                                  (("role" . "user") ("content" . "中文")))))
+                                  (("text" . "2") ("type" . "text"))
+                                ) ;#
+                             ))
+                            (("role" . "user") ("content" . "中文"))
+                          ) ;#
+                       ))
        ) ;json->string
   =>
   "{\"messages\":[{\"role\":\"user\",\"content\":[{\"text\":\"1\",\"type\":\"text\"},{\"text\":\"2\",\"type\":\"text\"}]},{\"role\":\"user\",\"content\":\"中文\"}]}"

tools/fmt/liii/goldfmt-format.scm

@@ -391,26 +391,29 @@
     (define (format-reader-vector-multiline datum indent)
       (let* ((prefix (reader-vector-prefix datum))
              (item-indent (+ indent (string-length prefix)))
+             (close-marker (string-append "\n" (spaces indent) ") ;#"))
             ) ;
         (let loop
           ((items (reader-vector->list datum)) (pieces (list prefix)) (prefix-ready? #t))
           (if (null? items)
-            (apply string-append (reverse (cons ")" pieces)))
+            (apply string-append (reverse (cons close-marker pieces)))
             (let ((item (car items)))
               (if (newline-marker-datum? item)
                 (loop (cdr items)
                   (cons (spaces item-indent) (cons (reader-newlines (cadr item)) pieces))
                   #t
                 ) ;loop
-                (loop (cdr items)
-                  (cons (format-reader-datum-at item item-indent)
-                    (if prefix-ready?
-                      pieces
-                      (cons (string-append "\n" (spaces item-indent)) pieces)
-                    ) ;if
-                  ) ;cons
-                  #f
-                ) ;loop
+                (let ((item-text (string-trim (format-reader-datum-at item item-indent))))
+                  (loop (cdr items)
+                    (cons item-text
+                      (if prefix-ready?
+                        pieces
+                        (cons (string-append "\n" (spaces item-indent)) pieces)
+                      ) ;if
+                    ) ;cons
+                    #f
+                  ) ;loop
+                ) ;let
               ) ;if
             ) ;let
           ) ;if
@@ -462,33 +465,61 @@
       ) ;let
     ) ;define
 
-    (define (reader-append-rest current result rest-indent prefix-ready?)
+    (define (last-line-column text)
+      (let loop
+        ((i 0) (column 0))
+        (if (>= i (string-length text))
+          column
+          (loop (+ i 1)
+            (if (char=? (string-ref text i) #\newline) 0 (+ column 1))
+          ) ;loop
+        ) ;if
+      ) ;let
+    ) ;define
+
+    (define (reader-append-close result close-indent)
+      (if (string-suffix? ";#" result)
+        (string-append result "\n" (spaces close-indent) ")")
+        (string-append result ")")
+      ) ;if
+    ) ;define
+
+    (define (reader-append-rest current result rest-indent prefix-ready? close-indent)
       (cond ((pair? current)
              (let ((item (car current)))
                (if (newline-marker-datum? item)
                  (reader-append-rest (cdr current)
                    (string-append result (reader-newlines (cadr item)) (spaces rest-indent))
                    rest-indent
                    #t
+                   close-indent
                  ) ;reader-append-rest
                  (reader-append-rest (cdr current)
                    (string-append result
                      (if prefix-ready? "" (string-append "\n" (spaces rest-indent)))
-                     (format-reader-datum-at item rest-indent)
+                     (format-reader-datum-at item
+                       (if prefix-ready? (last-line-column result) rest-indent)
+                     ) ;format-reader-datum-at
                    ) ;string-append
                    rest-indent
                    #f
+                   close-indent
                  ) ;reader-append-rest
                ) ;if
              ) ;let
             ) ;
-            ((null? current) (string-append result ")"))
-            (else (string-append result
-                    (if prefix-ready? "" (string-append "\n" (spaces rest-indent)))
-                    ". "
-                    (format-reader-datum-at current (+ rest-indent 2))
-                    ")"
-                  ) ;string-append
+            ((null? current) (reader-append-close result close-indent))
+            (else (reader-append-close
+                    (let* ((prefix (if prefix-ready? "" (string-append "\n" (spaces rest-indent)))
+                           ) ;prefix
+                           (before-tail (string-append result prefix ". "))
+                          ) ;
+                      (string-append before-tail
+                        (format-reader-datum-at current (last-line-column before-tail))
+                      ) ;string-append
+                    ) ;let*
+                    close-indent
+                  ) ;reader-append-close
             ) ;else
       ) ;cond
     ) ;define
@@ -520,7 +551,7 @@
                             ) ;if
                ) ;body-indent
               ) ;
-          (reader-append-rest after-selected with-selected body-indent #f)
+          (reader-append-rest after-selected with-selected body-indent #f indent)
         ) ;let*
       ) ;if
     ) ;define

tools/fmt/tests/liii/goldfmt-format/format-string-test.scm

@@ -145,7 +145,14 @@
 
 (check (format-datum '(quote #(a (*newline* 1) b)))
   =>
-  "'#(a\n\n   b)"
+  "'#(a\n\n   b\n ) ;#"
+) ;check
+
+(check (format-datum '#((alpha beta gamma delta epsilon zeta eta theta iota kappa)
+                         (one two three four five six seven eight nine ten)
+                       ))
+  =>
+  "#((alpha beta gamma delta epsilon zeta eta theta iota kappa)\n  (one two three four five six seven eight nine ten)\n) ;#"
 ) ;check
 
 ;; 超过 max-inline-length 的 reader datum 应进入 head-aware 多行排版
@@ -207,7 +214,7 @@
 (check (format-string "(check (f '((\"messages\" . #(((\"role\" . \"user\") (\"content\" . #(((\"text\" . \"1\") (\"type\" . \"text\")) ((\"text\" . \"2\") (\"type\" . \"text\"))))) ((\"role\" . \"user\") (\"content\" . \"中文\")))))) => \"ok\")"
        ) ;format-string
   =>
-  "(check (f '((\"messages\"\n             . #(((\"role\" . \"user\")\n                  (\"content\"\n                   . #(((\"text\" . \"1\") (\"type\" . \"text\"))\n                       ((\"text\" . \"2\") (\"type\" . \"text\")))))\n                       ((\"role\" . \"user\") (\"content\" . \"中文\")))))\n       ) ;f\n  =>\n  \"ok\"\n) ;check\n"
+  "(check (f '((\"messages\"\n             . #(((\"role\" . \"user\")\n                  (\"content\"\n                   . #(((\"text\" . \"1\") (\"type\" . \"text\"))\n                       ((\"text\" . \"2\") (\"type\" . \"text\"))\n                     ) ;#\n                  ))\n                 ((\"role\" . \"user\") (\"content\" . \"中文\"))\n               ) ;#\n            ))\n       ) ;f\n  =>\n  \"ok\"\n) ;check\n"
 ) ;check
 
 (check-report)