aether/builtins/
help.rs

1// src/builtins/help.rs
2//! 帮助文档系统
3
4use crate::evaluator::RuntimeError;
5use crate::value::Value;
6use std::collections::HashMap;
7use std::sync::OnceLock;
8
9/// 全局函数文档存储
10static FUNCTION_DOCS: OnceLock<HashMap<String, FunctionDocData>> = OnceLock::new();
11
12/// 函数文档数据
13#[derive(Debug, Clone)]
14pub struct FunctionDocData {
15    /// 函数名称
16    pub name: String,
17    /// 函数描述
18    pub description: String,
19    /// 参数列表(参数名和描述)
20    pub params: Vec<(String, String)>,
21    /// 返回值描述
22    pub returns: String,
23    /// 使用示例
24    pub example: Option<String>,
25}
26
27/// 初始化函数文档
28pub fn init_docs() -> HashMap<String, FunctionDocData> {
29    let mut docs = HashMap::new();
30
31    // 精确计算函数
32    docs.insert(
33        "TO_FRACTION".to_string(),
34        FunctionDocData {
35            name: "TO_FRACTION".to_string(),
36            description: "将数字转换为分数,用于精确计算".to_string(),
37            params: vec![("value".to_string(), "要转换的数字或分数".to_string())],
38            returns: "转换后的分数值".to_string(),
39            example: Some("TO_FRACTION(0.5)  => 1/2\nTO_FRACTION(0.333)  => 333/1000".to_string()),
40        },
41    );
42
43    docs.insert(
44        "TO_FLOAT".to_string(),
45        FunctionDocData {
46            name: "TO_FLOAT".to_string(),
47            description: "将分数转换为浮点数".to_string(),
48            params: vec![("fraction".to_string(), "要转换的分数值".to_string())],
49            returns: "转换后的浮点数".to_string(),
50            example: Some("TO_FLOAT(TO_FRACTION(1/3))  => 0.333...".to_string()),
51        },
52    );
53
54    docs.insert(
55        "SIMPLIFY".to_string(),
56        FunctionDocData {
57            name: "SIMPLIFY".to_string(),
58            description: "化简分数(约分)为最简形式".to_string(),
59            params: vec![("fraction".to_string(), "要化简的分数".to_string())],
60            returns: "化简后的最简分数".to_string(),
61            example: Some("SIMPLIFY(TO_FRACTION(6/8))  => 3/4".to_string()),
62        },
63    );
64
65    docs.insert(
66        "FRAC_ADD".to_string(),
67        FunctionDocData {
68            name: "FRAC_ADD".to_string(),
69            description: "分数加法运算,保证精确计算".to_string(),
70            params: vec![
71                ("a".to_string(), "第一个加数(数字或分数)".to_string()),
72                ("b".to_string(), "第二个加数(数字或分数)".to_string()),
73            ],
74            returns: "两个分数相加的精确结果".to_string(),
75            example: Some("FRAC_ADD(0.1, 0.2)  => 3/10 (而非 0.30000000000000004)".to_string()),
76        },
77    );
78
79    docs.insert(
80        "FRAC_SUB".to_string(),
81        FunctionDocData {
82            name: "FRAC_SUB".to_string(),
83            description: "分数减法运算,保证精确计算".to_string(),
84            params: vec![
85                ("a".to_string(), "被减数(数字或分数)".to_string()),
86                ("b".to_string(), "减数(数字或分数)".to_string()),
87            ],
88            returns: "两个分数相减的精确结果".to_string(),
89            example: Some("FRAC_SUB(0.5, 0.25)  => 1/4".to_string()),
90        },
91    );
92
93    docs.insert(
94        "FRAC_MUL".to_string(),
95        FunctionDocData {
96            name: "FRAC_MUL".to_string(),
97            description: "分数乘法运算,保证精确计算".to_string(),
98            params: vec![
99                ("a".to_string(), "第一个乘数(数字或分数)".to_string()),
100                ("b".to_string(), "第二个乘数(数字或分数)".to_string()),
101            ],
102            returns: "两个分数相乘的精确结果".to_string(),
103            example: Some("FRAC_MUL(0.1, 0.3)  => 3/100".to_string()),
104        },
105    );
106
107    docs.insert(
108        "FRAC_DIV".to_string(),
109        FunctionDocData {
110            name: "FRAC_DIV".to_string(),
111            description: "分数除法运算,保证精确计算,除数不能为零".to_string(),
112            params: vec![
113                ("a".to_string(), "被除数(数字或分数)".to_string()),
114                ("b".to_string(), "除数(数字或分数,不能为零)".to_string()),
115            ],
116            returns: "两个分数相除的精确结果".to_string(),
117            example: Some("FRAC_DIV(1, 3)  => 1/3".to_string()),
118        },
119    );
120
121    docs.insert(
122        "NUMERATOR".to_string(),
123        FunctionDocData {
124            name: "NUMERATOR".to_string(),
125            description: "获取分数的分子".to_string(),
126            params: vec![("fraction".to_string(), "分数值".to_string())],
127            returns: "分数的分子(浮点数)".to_string(),
128            example: Some("NUMERATOR(TO_FRACTION(3/4))  => 3".to_string()),
129        },
130    );
131
132    docs.insert(
133        "DENOMINATOR".to_string(),
134        FunctionDocData {
135            name: "DENOMINATOR".to_string(),
136            description: "获取分数的分母".to_string(),
137            params: vec![("fraction".to_string(), "分数值".to_string())],
138            returns: "分数的分母(浮点数)".to_string(),
139            example: Some("DENOMINATOR(TO_FRACTION(3/4))  => 4".to_string()),
140        },
141    );
142
143    docs.insert(
144        "GCD".to_string(),
145        FunctionDocData {
146            name: "GCD".to_string(),
147            description: "计算两个整数的最大公约数(Greatest Common Divisor)".to_string(),
148            params: vec![
149                ("a".to_string(), "第一个整数".to_string()),
150                ("b".to_string(), "第二个整数".to_string()),
151            ],
152            returns: "两个数的最大公约数".to_string(),
153            example: Some("GCD(12, 18)  => 6\nGCD(7, 13)  => 1".to_string()),
154        },
155    );
156
157    docs.insert(
158        "LCM".to_string(),
159        FunctionDocData {
160            name: "LCM".to_string(),
161            description: "计算两个整数的最小公倍数(Least Common Multiple)".to_string(),
162            params: vec![
163                ("a".to_string(), "第一个整数".to_string()),
164                ("b".to_string(), "第二个整数".to_string()),
165            ],
166            returns: "两个数的最小公倍数".to_string(),
167            example: Some("LCM(4, 6)  => 12\nLCM(3, 5)  => 15".to_string()),
168        },
169    );
170
171    // I/O 函数
172    docs.insert(
173        "PRINT".to_string(),
174        FunctionDocData {
175            name: "PRINT".to_string(),
176            description: "输出内容到控制台(不换行)".to_string(),
177            params: vec![("value".to_string(), "要输出的值".to_string())],
178            returns: "null".to_string(),
179            example: Some("PRINT(\"Hello\")  => 输出: Hello".to_string()),
180        },
181    );
182
183    docs.insert(
184        "PRINTLN".to_string(),
185        FunctionDocData {
186            name: "PRINTLN".to_string(),
187            description: "输出内容到控制台并换行".to_string(),
188            params: vec![("value".to_string(), "要输出的值".to_string())],
189            returns: "null".to_string(),
190            example: Some("PRINTLN(\"Hello World\")  => 输出: Hello World\\n".to_string()),
191        },
192    );
193
194    docs.insert(
195        "INPUT".to_string(),
196        FunctionDocData {
197            name: "INPUT".to_string(),
198            description: "从控制台读取用户输入".to_string(),
199            params: vec![("prompt".to_string(), "提示信息".to_string())],
200            returns: "用户输入的字符串".to_string(),
201            example: Some("name = INPUT(\"请输入姓名: \")".to_string()),
202        },
203    );
204
205    docs.insert(
206        "TRACE".to_string(),
207        FunctionDocData {
208            name: "TRACE".to_string(),
209            description: "记录调试信息到引擎内存缓冲区(宿主可读取,不产生 IO)".to_string(),
210            params: vec![("value".to_string(), "要记录的值(任意类型)".to_string())],
211            returns: "null".to_string(),
212            example: Some("TRACE(\"x=\" + TO_STRING(X))\nTRACE({\"a\": 1})".to_string()),
213        },
214    );
215
216    // 数组函数
217    docs.insert(
218        "RANGE".to_string(),
219        FunctionDocData {
220            name: "RANGE".to_string(),
221            description: "生成数字范围数组".to_string(),
222            params: vec![(
223                "end".to_string(),
224                "结束值(可选: start, end, step)".to_string(),
225            )],
226            returns: "数字数组".to_string(),
227            example: Some("RANGE(5)  => [0,1,2,3,4]\nRANGE(2, 8, 2)  => [2,4,6]".to_string()),
228        },
229    );
230
231    docs.insert(
232        "LEN".to_string(),
233        FunctionDocData {
234            name: "LEN".to_string(),
235            description: "获取数组、字符串或字典的长度".to_string(),
236            params: vec![("value".to_string(), "数组、字符串或字典".to_string())],
237            returns: "长度值".to_string(),
238            example: Some("LEN([1,2,3])  => 3\nLEN(\"hello\")  => 5".to_string()),
239        },
240    );
241
242    docs.insert(
243        "PUSH".to_string(),
244        FunctionDocData {
245            name: "PUSH".to_string(),
246            description: "向数组末尾添加元素".to_string(),
247            params: vec![
248                ("array".to_string(), "目标数组".to_string()),
249                ("element".to_string(), "要添加的元素".to_string()),
250            ],
251            returns: "新数组".to_string(),
252            example: Some("PUSH([1,2], 3)  => [1,2,3]".to_string()),
253        },
254    );
255
256    docs.insert(
257        "POP".to_string(),
258        FunctionDocData {
259            name: "POP".to_string(),
260            description: "移除并返回数组最后一个元素".to_string(),
261            params: vec![("array".to_string(), "目标数组".to_string())],
262            returns: "被移除的元素".to_string(),
263            example: Some("POP([1,2,3])  => 3".to_string()),
264        },
265    );
266
267    docs.insert(
268        "REVERSE".to_string(),
269        FunctionDocData {
270            name: "REVERSE".to_string(),
271            description: "反转数组元素顺序".to_string(),
272            params: vec![("array".to_string(), "要反转的数组".to_string())],
273            returns: "反转后的数组".to_string(),
274            example: Some("REVERSE([1,2,3])  => [3,2,1]".to_string()),
275        },
276    );
277
278    docs.insert(
279        "SORT".to_string(),
280        FunctionDocData {
281            name: "SORT".to_string(),
282            description: "对数组进行排序".to_string(),
283            params: vec![("array".to_string(), "要排序的数组".to_string())],
284            returns: "排序后的数组".to_string(),
285            example: Some("SORT([3,1,2])  => [1,2,3]".to_string()),
286        },
287    );
288
289    docs.insert(
290        "SUM".to_string(),
291        FunctionDocData {
292            name: "SUM".to_string(),
293            description: "计算数组元素之和".to_string(),
294            params: vec![("array".to_string(), "数字数组".to_string())],
295            returns: "总和".to_string(),
296            example: Some("SUM([1,2,3,4])  => 10".to_string()),
297        },
298    );
299
300    docs.insert(
301        "MAX".to_string(),
302        FunctionDocData {
303            name: "MAX".to_string(),
304            description: "找出数组中的最大值".to_string(),
305            params: vec![("array".to_string(), "数字数组".to_string())],
306            returns: "最大值".to_string(),
307            example: Some("MAX([1,5,3,2])  => 5".to_string()),
308        },
309    );
310
311    docs.insert(
312        "MIN".to_string(),
313        FunctionDocData {
314            name: "MIN".to_string(),
315            description: "找出数组中的最小值".to_string(),
316            params: vec![("array".to_string(), "数字数组".to_string())],
317            returns: "最小值".to_string(),
318            example: Some("MIN([1,5,3,2])  => 1".to_string()),
319        },
320    );
321
322    // 字符串函数
323    docs.insert(
324        "SPLIT".to_string(),
325        FunctionDocData {
326            name: "SPLIT".to_string(),
327            description: "按分隔符分割字符串".to_string(),
328            params: vec![
329                ("string".to_string(), "要分割的字符串".to_string()),
330                ("separator".to_string(), "分隔符".to_string()),
331            ],
332            returns: "字符串数组".to_string(),
333            example: Some("SPLIT(\"a,b,c\", \",\")  => [\"a\",\"b\",\"c\"]".to_string()),
334        },
335    );
336
337    docs.insert(
338        "UPPER".to_string(),
339        FunctionDocData {
340            name: "UPPER".to_string(),
341            description: "将字符串转换为大写".to_string(),
342            params: vec![("string".to_string(), "源字符串".to_string())],
343            returns: "大写字符串".to_string(),
344            example: Some("UPPER(\"hello\")  => \"HELLO\"".to_string()),
345        },
346    );
347
348    docs.insert(
349        "LOWER".to_string(),
350        FunctionDocData {
351            name: "LOWER".to_string(),
352            description: "将字符串转换为小写".to_string(),
353            params: vec![("string".to_string(), "源字符串".to_string())],
354            returns: "小写字符串".to_string(),
355            example: Some("LOWER(\"HELLO\")  => \"hello\"".to_string()),
356        },
357    );
358
359    docs.insert(
360        "TRIM".to_string(),
361        FunctionDocData {
362            name: "TRIM".to_string(),
363            description: "去除字符串首尾空白字符".to_string(),
364            params: vec![("string".to_string(), "源字符串".to_string())],
365            returns: "去除空白后的字符串".to_string(),
366            example: Some("TRIM(\"  hello  \")  => \"hello\"".to_string()),
367        },
368    );
369
370    // 数学函数 - 基础
371    docs.insert(
372        "ABS".to_string(),
373        FunctionDocData {
374            name: "ABS".to_string(),
375            description: "计算绝对值".to_string(),
376            params: vec![("x".to_string(), "数字".to_string())],
377            returns: "绝对值".to_string(),
378            example: Some("ABS(-5)  => 5".to_string()),
379        },
380    );
381
382    docs.insert(
383        "SQRT".to_string(),
384        FunctionDocData {
385            name: "SQRT".to_string(),
386            description: "计算平方根".to_string(),
387            params: vec![("x".to_string(), "数字".to_string())],
388            returns: "平方根".to_string(),
389            example: Some("SQRT(16)  => 4".to_string()),
390        },
391    );
392
393    docs.insert(
394        "POW".to_string(),
395        FunctionDocData {
396            name: "POW".to_string(),
397            description: "计算幂次方".to_string(),
398            params: vec![
399                ("base".to_string(), "底数".to_string()),
400                ("exponent".to_string(), "指数".to_string()),
401            ],
402            returns: "幂运算结果".to_string(),
403            example: Some("POW(2, 10)  => 1024".to_string()),
404        },
405    );
406
407    docs.insert(
408        "FLOOR".to_string(),
409        FunctionDocData {
410            name: "FLOOR".to_string(),
411            description: "向下取整".to_string(),
412            params: vec![("x".to_string(), "数字".to_string())],
413            returns: "不大于x的最大整数".to_string(),
414            example: Some("FLOOR(3.7)  => 3".to_string()),
415        },
416    );
417
418    docs.insert(
419        "CEIL".to_string(),
420        FunctionDocData {
421            name: "CEIL".to_string(),
422            description: "向上取整".to_string(),
423            params: vec![("x".to_string(), "数字".to_string())],
424            returns: "不小于x的最小整数".to_string(),
425            example: Some("CEIL(3.2)  => 4".to_string()),
426        },
427    );
428
429    docs.insert(
430        "ROUND".to_string(),
431        FunctionDocData {
432            name: "ROUND".to_string(),
433            description: "四舍五入到最接近的整数".to_string(),
434            params: vec![("x".to_string(), "数字".to_string())],
435            returns: "四舍五入后的整数".to_string(),
436            example: Some("ROUND(3.6)  => 4".to_string()),
437        },
438    );
439
440    // 数学函数 - 三角函数
441    docs.insert(
442        "SIN".to_string(),
443        FunctionDocData {
444            name: "SIN".to_string(),
445            description: "计算正弦值(弧度)".to_string(),
446            params: vec![("x".to_string(), "角度(弧度)".to_string())],
447            returns: "正弦值".to_string(),
448            example: Some("SIN(PI()/2)  => 1".to_string()),
449        },
450    );
451
452    docs.insert(
453        "COS".to_string(),
454        FunctionDocData {
455            name: "COS".to_string(),
456            description: "计算余弦值(弧度)".to_string(),
457            params: vec![("x".to_string(), "角度(弧度)".to_string())],
458            returns: "余弦值".to_string(),
459            example: Some("COS(0)  => 1".to_string()),
460        },
461    );
462
463    docs.insert(
464        "TAN".to_string(),
465        FunctionDocData {
466            name: "TAN".to_string(),
467            description: "计算正切值(弧度)".to_string(),
468            params: vec![("x".to_string(), "角度(弧度)".to_string())],
469            returns: "正切值".to_string(),
470            example: Some("TAN(PI()/4)  => 1".to_string()),
471        },
472    );
473
474    // 数学常数
475    docs.insert(
476        "PI".to_string(),
477        FunctionDocData {
478            name: "PI".to_string(),
479            description: "圆周率 π ≈ 3.14159...".to_string(),
480            params: vec![],
481            returns: "π 的值".to_string(),
482            example: Some("PI()  => 3.141592653589793".to_string()),
483        },
484    );
485
486    docs.insert(
487        "E".to_string(),
488        FunctionDocData {
489            name: "E".to_string(),
490            description: "自然常数 e ≈ 2.71828...".to_string(),
491            params: vec![],
492            returns: "e 的值".to_string(),
493            example: Some("E()  => 2.718281828459045".to_string()),
494        },
495    );
496
497    // 统计函数
498    docs.insert(
499        "MEAN".to_string(),
500        FunctionDocData {
501            name: "MEAN".to_string(),
502            description: "计算数组的平均值".to_string(),
503            params: vec![("array".to_string(), "数字数组".to_string())],
504            returns: "平均值".to_string(),
505            example: Some("MEAN([1,2,3,4,5])  => 3".to_string()),
506        },
507    );
508
509    docs.insert(
510        "MEDIAN".to_string(),
511        FunctionDocData {
512            name: "MEDIAN".to_string(),
513            description: "计算数组的中位数".to_string(),
514            params: vec![("array".to_string(), "数字数组".to_string())],
515            returns: "中位数".to_string(),
516            example: Some("MEDIAN([1,2,3,4,5])  => 3".to_string()),
517        },
518    );
519
520    docs.insert(
521        "VARIANCE".to_string(),
522        FunctionDocData {
523            name: "VARIANCE".to_string(),
524            description: "计算数组的方差".to_string(),
525            params: vec![("array".to_string(), "数字数组".to_string())],
526            returns: "方差".to_string(),
527            example: Some("VARIANCE([1,2,3,4,5])  => 2".to_string()),
528        },
529    );
530
531    docs.insert(
532        "STD".to_string(),
533        FunctionDocData {
534            name: "STD".to_string(),
535            description: "计算数组的标准差".to_string(),
536            params: vec![("array".to_string(), "数字数组".to_string())],
537            returns: "标准差".to_string(),
538            example: Some("STD([1,2,3,4,5])  => 1.414...".to_string()),
539        },
540    );
541
542    // 类型转换函数
543    docs.insert(
544        "TYPE".to_string(),
545        FunctionDocData {
546            name: "TYPE".to_string(),
547            description: "获取值的类型".to_string(),
548            params: vec![("value".to_string(), "任意值".to_string())],
549            returns: "类型名称字符串".to_string(),
550            example: Some("TYPE(123)  => \"Number\"\nTYPE(\"hello\")  => \"String\"".to_string()),
551        },
552    );
553
554    docs.insert(
555        "TO_STRING".to_string(),
556        FunctionDocData {
557            name: "TO_STRING".to_string(),
558            description: "将值转换为字符串".to_string(),
559            params: vec![("value".to_string(), "要转换的值".to_string())],
560            returns: "字符串".to_string(),
561            example: Some("TO_STRING(123)  => \"123\"".to_string()),
562        },
563    );
564
565    docs.insert(
566        "TO_NUMBER".to_string(),
567        FunctionDocData {
568            name: "TO_NUMBER".to_string(),
569            description: "将字符串转换为数字".to_string(),
570            params: vec![("string".to_string(), "数字字符串".to_string())],
571            returns: "数字".to_string(),
572            example: Some("TO_NUMBER(\"123\")  => 123".to_string()),
573        },
574    );
575
576    docs
577}
578
579/// HELP 函数实现
580///
581/// 用法:
582/// - HELP() - 列出所有可用函数
583/// - HELP("函数名") - 显示特定函数的详细文档
584pub fn help(args: &[Value]) -> Result<Value, RuntimeError> {
585    // 初始化文档(只执行一次)
586    let docs = FUNCTION_DOCS.get_or_init(init_docs);
587
588    if args.is_empty() {
589        // 列出所有函数
590        let mut output = String::from("=== Aether 内置函数列表 ===\n\n");
591
592        // 按类别组织函数
593        let categories = vec![
594            (
595                "精确计算",
596                vec![
597                    "TO_FRACTION",
598                    "TO_FLOAT",
599                    "SIMPLIFY",
600                    "FRAC_ADD",
601                    "FRAC_SUB",
602                    "FRAC_MUL",
603                    "FRAC_DIV",
604                    "NUMERATOR",
605                    "DENOMINATOR",
606                    "GCD",
607                    "LCM",
608                ],
609            ),
610            ("输入输出", vec!["PRINT", "PRINTLN", "INPUT"]),
611            ("调试", vec!["TRACE"]),
612            (
613                "数组操作",
614                vec![
615                    "RANGE", "LEN", "PUSH", "POP", "REVERSE", "SORT", "SUM", "MAX", "MIN",
616                ],
617            ),
618            (
619                "字符串操作",
620                vec![
621                    "SPLIT",
622                    "UPPER",
623                    "LOWER",
624                    "TRIM",
625                    "CONTAINS",
626                    "STARTS_WITH",
627                    "ENDS_WITH",
628                    "REPLACE",
629                    "REPEAT",
630                    "JOIN",
631                ],
632            ),
633            (
634                "数学函数 - 基础",
635                vec!["ABS", "SQRT", "POW", "FLOOR", "CEIL", "ROUND"],
636            ),
637            (
638                "数学函数 - 三角",
639                vec!["SIN", "COS", "TAN", "ASIN", "ACOS", "ATAN", "ATAN2"],
640            ),
641            ("数学函数 - 对数", vec!["LOG", "LN", "LOG2", "EXP", "EXP2"]),
642            ("数学常数", vec!["PI", "E", "TAU", "PHI"]),
643            (
644                "统计分析",
645                vec!["MEAN", "MEDIAN", "VARIANCE", "STD", "QUANTILE"],
646            ),
647            (
648                "向量运算",
649                vec!["DOT", "NORM", "CROSS", "DISTANCE", "NORMALIZE"],
650            ),
651            (
652                "矩阵运算",
653                vec!["MATMUL", "TRANSPOSE", "DETERMINANT", "INVERSE"],
654            ),
655            ("线性回归", vec!["LINEAR_REGRESSION"]),
656            ("概率分布", vec!["NORMAL_PDF", "NORMAL_CDF", "POISSON_PMF"]),
657            (
658                "精度计算",
659                vec![
660                    "ROUND_TO",
661                    "ADD_WITH_PRECISION",
662                    "SUB_WITH_PRECISION",
663                    "MUL_WITH_PRECISION",
664                    "DIV_WITH_PRECISION",
665                ],
666            ),
667            ("类型转换", vec!["TYPE", "TO_STRING", "TO_NUMBER"]),
668            ("字典操作", vec!["KEYS", "VALUES", "HAS", "MERGE"]),
669        ];
670
671        for (category, funcs) in categories {
672            output.push_str(&format!("【{}】\n", category));
673            for func_name in funcs {
674                if let Some(doc) = docs.get(func_name) {
675                    output.push_str(&format!("  {} - {}\n", doc.name, doc.description));
676                }
677            }
678            output.push('\n');
679        }
680
681        output.push_str("使用 HELP(\"函数名\") 查看详细文档\n");
682        output.push_str("例如: HELP(\"TO_FRACTION\")\n");
683
684        Ok(Value::String(output))
685    } else if args.len() == 1 {
686        // 显示特定函数的文档
687        match &args[0] {
688            Value::String(func_name) => {
689                let func_name_upper = func_name.to_uppercase();
690
691                if let Some(doc) = docs.get(&func_name_upper) {
692                    let mut output = "=".repeat(50);
693                    output.push_str(&format!("\n函数: {}\n", doc.name));
694                    output.push_str(&"=".repeat(50));
695                    output.push_str(&format!("\n\n描述:\n  {}\n\n", doc.description));
696
697                    if !doc.params.is_empty() {
698                        output.push_str("参数:\n");
699                        for (param_name, param_desc) in &doc.params {
700                            output.push_str(&format!("  - {}: {}\n", param_name, param_desc));
701                        }
702                        output.push('\n');
703                    }
704
705                    output.push_str(&format!("返回值:\n  {}\n\n", doc.returns));
706
707                    if let Some(example) = &doc.example {
708                        output.push_str("示例:\n");
709                        for line in example.lines() {
710                            output.push_str(&format!("  {}\n", line));
711                        }
712                    }
713
714                    output.push_str(&"=".repeat(50));
715                    output.push('\n');
716
717                    Ok(Value::String(output))
718                } else {
719                    Err(RuntimeError::InvalidOperation(format!(
720                        "函数 '{}' 不存在。使用 HELP() 查看所有可用函数。",
721                        func_name
722                    )))
723                }
724            }
725            _ => Err(RuntimeError::TypeErrorDetailed {
726                expected: "String".to_string(),
727                got: format!("{:?}", args[0]),
728            }),
729        }
730    } else {
731        Err(RuntimeError::WrongArity {
732            expected: 0, // or 1
733            got: args.len(),
734        })
735    }
736}