diff --git a/devel/216_48.md b/devel/216_48.md new file mode 100644 index 00000000..b8efb9a5 --- /dev/null +++ b/devel/216_48.md @@ -0,0 +1,51 @@ +# [216_48] 为 liii/cut 添加文档和测试用例 + +## 任务相关的代码文件 +- goldfish/liii/cut.scm +- tests/goldfish/liii/cut-test.scm +- tests/liii/cut-test.scm(新建) + +## 如何测试 +``` +xmake config --yes +xmake b goldfish +bin/gf fix tests/liii/cut-test.scm +bin/gf tests/liii/cut-test.scm +``` + +## 如何查看文档 +使用 `gf doc` 命令查看 cut 模块的文档: +``` +bin/gf doc liii/cut +``` + +## 2026/04/03 为 liii/cut 添加文档和测试用例(已完成) + +### What +为 `(liii cut)` 模块添加文档,使 `bin/gf doc liii/cut` 能够显示对 AI 编程有帮助的文档和测试用例。 + +1. 新建 `tests/liii/cut-test.scm` 文件,包含文档注释和测试用例 +2. 文档内容包括: + - 模块功能说明(SRFI-26 的 cut/cute 宏,用于创建部分应用函数) + - 常见用法示例(含占位符 `<>` 和可变参数 `<...>` 的使用) + - `cut` 与 `cute` 的区别(运行时求值 vs 创建时求值) + - 函数分类索引 + +### Why +- `bin/gf doc liii/cut` 目前显示 "No documentation and test cases available" +- 需要为 AI 编程提供清晰的 cut/cute 使用指南 +- cut 是函数式编程中常用的部分应用工具,对 AI 生成代码很有帮助 + +### How +1. 在 `tests/liii/` 目录下新建 `cut-test.scm` 文件(`gf doc` 命令从此目录提取文档) +2. 文件头部使用 `;;` 注释添加文档说明,格式参考 `tests/liii/argparse-test.scm` +3. 包含以下内容: + - 模块用途说明 + - 占位符语法:`<>` 表示单个参数位置,`<...>` 表示可变参数 + - cut vs cute 的区别说明 + - 典型使用场景示例 + - 函数分类索引 + +### 验证结果 +- 测试全部通过:19 correct, 0 failed +- `bin/gf doc liii/cut` 成功显示完整文档和测试用例 diff --git a/tests/goldfish/liii/cut-test.scm b/tests/goldfish/liii/cut-test.scm deleted file mode 100644 index 20304e18..00000000 --- a/tests/goldfish/liii/cut-test.scm +++ /dev/null @@ -1,54 +0,0 @@ -; -; Copyright (C) 2024 The Goldfish Scheme Authors -; -; Licensed under the Apache License, Version 2.0 (the "License"); -; you may not use this file except in compliance with the License. -; You may obtain a copy of the License at -; -; http://www.apache.org/licenses/LICENSE-2.0 -; -; Unless required by applicable law or agreed to in writing, software -; distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -; WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -; License for the specific language governing permissions and limitations -; under the License. -; - -(import (liii check) - (liii cut) -) ;import - -(check-set-mode! 'report-failed) - -(check ((cut list <> 'y <>) 'x 'z) => '(x y z)) -(check ((cut + 1 <...>) 2 3) => 6) -(check ((cut + 1 <...>)) => 1) -(check ((cut <> 1 <...>) + 2 3) => 6) -(check ((cut list <> <> <...>) 1 2 3) => '(1 2 3)) -(check ((cut list <> <> <...>) 1 2) => '(1 2)) -(check ((cut + 1 2)) => 3) -(check ((cut <>) list) => ()) -(check ((cut)) => ()) -(check ((cut <> #t <...>) if 1 0) => 1) - -(check-catch 'wrong-number-of-args ((cut list <> <>) 1)) -(check-catch 'wrong-number-of-args ((cut list <> <> <...>) 1)) -(check-catch 'syntax-error ((cut list <> <> <...> <>) 1 2 3)) - -(let* ((a 1) - (f (cut <> (set! a 2)))) - (check a => 1) - (check (f (lambda (x) x)) => 2) - (check a => 2) -) ;let* - -(let* ((a 1) - (f (cute <> (set! a 2)))) - (check a => 2) - (set! a 1) - (check (f (lambda (x) x)) => 2) - (check a => 1) -) ;let* - -(check-report) - diff --git a/tests/liii/cut-test.scm b/tests/liii/cut-test.scm new file mode 100644 index 00000000..f9d3a22a --- /dev/null +++ b/tests/liii/cut-test.scm @@ -0,0 +1,109 @@ +;; (liii cut) 模块测试文件 +;; +;; cut 和 cute 是 SRFI-26 提供的宏,用于创建部分应用(Partial Application)函数。 +;; 它们允许你预先填充函数的部分参数,留下一些参数位置待后续传入。 +;; +;; 核心用途:在不使用 lambda 的情况下快速创建函数闭包,适用于函数式编程中的参数预设。 + +;; ==== 语法说明 ==== +;; +;; (cut <函数> <参数>...) +;; - 创建一个新函数,<函数> 会被延迟到调用时执行 +;; - <> 表示单个参数占位符(slot),调用时按顺序填充 +;; - <...> 表示可变参数占位符(rest-slot),收集剩余所有参数 +;; +;; (cute <函数> <参数>...) +;; - 与 cut 类似,但参数在创建时立即求值(非调用时) +;; - 适用于参数包含副作用(如 set!)的场景 + +;; ==== 常见用法示例 ==== +;; +;; 示例1:预设函数的第一个参数 +;; ((cut + 10 <>) 5) => 15 +;; +;; 示例2:预设函数的中间参数 +;; ((cut list 'a <> 'c) 'b) => (a b c) +;; +;; 示例3:使用多个占位符 +;; ((cut list <> <>) 'x 'y) => (x y) +;; +;; 示例4:结合可变参数 +;; ((cut + 1 <...>) 2 3 4) => 10 +;; ((cut <> 1 <...>) + 2 3) => 6 +;; +;; 示例5:将占位符作为函数位置 +;; ((cut <> 'arg) procedure?) => #f (procedure? 对符号返回 #f) + +;; ==== cut vs cute 的区别 ==== +;; +;; cut: 参数在调用时才求值 +;; (let ((a 1)) +;; (define f (cut + a <>)) +;; (set! a 10) +;; (f 5)) => 15 (使用 a 的当前值 10) +;; +;; cute: 参数在创建时就求值 +;; (let ((a 1)) +;; (define f (cute + a <>)) +;; (set! a 10) +;; (f 5)) => 6 (使用 a 创建时的值 1) + +;; ==== 使用场景 ==== +;; +;; 1. 快速创建单参数函数传递给 map/filter +;; (map (cut * 2 <>) '(1 2 3)) => (2 4 6) +;; +;; 2. 预设回调函数的上下文参数 +;; (button :on-click (cut handle-click 'save)) +;; +;; 3. 构建函数管道中的中间转换器 +;; (compose (cut string-append "prefix-" <>) number->string) + +;; ==== 函数分类索引 ==== + +;; 一、部分应用宏 +;; cut - 延迟求值的部分应用(参数在调用时求值) +;; cute - 立即求值的部分应用(参数在创建时求值) + +;; ==== 单元测试 ==== + +(import (liii check) + (liii cut) +) ;import + +(check-set-mode! 'report-failed) + +;; 基础占位符测试 +(check ((cut list <> 'y <>) 'x 'z) => '(x y z)) +(check ((cut + 1 <...>) 2 3) => 6) +(check ((cut + 1 <...>)) => 1) +(check ((cut <> 1 <...>) + 2 3) => 6) +(check ((cut list <> <> <...>) 1 2 3) => '(1 2 3)) +(check ((cut list <> <> <...>) 1 2) => '(1 2)) +(check ((cut + 1 2)) => 3) +(check ((cut <>) list) => ()) +(check ((cut)) => ()) +(check ((cut <> #t <...>) if 1 0) => 1) + +;; 错误处理测试 +(check-catch 'wrong-number-of-args ((cut list <> <>) 1)) +(check-catch 'wrong-number-of-args ((cut list <> <> <...>) 1)) +(check-catch 'syntax-error ((cut list <> <> <...> <>) 1 2 3)) + +;; cut vs cute 求值时机对比测试 +(let* ((a 1) + (f (cut <> (set! a 2)))) + (check a => 1) + (check (f (lambda (x) x)) => 2) + (check a => 2) +) ;let* + +(let* ((a 1) + (f (cute <> (set! a 2)))) + (check a => 2) + (set! a 1) + (check (f (lambda (x) x)) => 2) + (check a => 1) +) ;let* + +(check-report)