From 7b23b26de96aa65cbeeb2397e168f8f1ca0dfc92 Mon Sep 17 00:00:00 2001 From: Li Jin Date: Thu, 8 May 2025 09:54:21 +0800 Subject: Updated docs. --- doc/docs/zh/doc/README.md | 176 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 136 insertions(+), 40 deletions(-) (limited to 'doc/docs/zh') diff --git a/doc/docs/zh/doc/README.md b/doc/docs/zh/doc/README.md index 754566c..11dc108 100755 --- a/doc/docs/zh/doc/README.md +++ b/doc/docs/zh/doc/README.md @@ -122,7 +122,7 @@ export 🌛 = "月之脚本" * **下载预编译的二进制程序** - 您可以下载预编译的二进制程序，包括兼容不同 Lua 版本的二进制可执行文件和库文件。 + 你可以下载预编译的二进制程序，包括兼容不同 Lua 版本的二进制可执行文件和库文件。  在[这里](https://github.com/IppClub/YueScript/releases)下载预编译的二进制程序。 @@ -132,14 +132,14 @@ export 🌛 = "月之脚本" 在Lua中使用月之脚本模块： -* **用法 1** +* **用法 1** 在Lua中引入 "你的脚本入口文件.yue"。 ```Lua require("yue")("你的脚本入口文件") ``` 当你在同一路径下把 "你的脚本入口文件.yue" 编译成了 "你的脚本入口文件.lua" 时，仍然可以使用这个代码加载 .lua 代码文件。在其余的月之脚本文件中，只需正常使用 **require** 或 **import**进行脚本引用即可。错误消息中的代码行号也会被正确处理。 -* **用法 2** +* **用法 2** 手动引入月之脚本模块并重写错误消息来帮助调试。 ```lua local yue = require("yue") @@ -151,7 +151,7 @@ end, function(err) end) ``` -* **用法 3** +* **用法 3** 在Lua中使用月之脚本编译器功能。 ```lua local yue = require("yue") @@ -202,12 +202,12 @@ f! 不添加任何选项执行命令可以进入REPL模式， 在单行输入符号 '$' 并换行后，可以开始或是停止多行输入模式 ``` -  使用案例： -  递归编译当前路径下扩展名为 **.yue** 的每个月之脚本文件： **yue .** -  编译并将结果保存到目标路径： **yue -t /target/path/ .** -  编译并保留调试信息： **yue -l .** -  编译并生成压缩代码： **yue -m .** -  直接执行代码： **yue -e 'print 123'** +  使用案例： +  递归编译当前路径下扩展名为 **.yue** 的每个月之脚本文件： **yue .** +  编译并将结果保存到目标路径： **yue -t /target/path/ .** +  编译并保留调试信息： **yue -l .** +  编译并生成压缩代码： **yue -m .** +  直接执行代码： **yue -e 'print 123'**   执行一个月之脚本文件： **yue -e main.yue** ## 宏 @@ -333,7 +333,7 @@ end ### 导出宏 -宏函数可以从一个模块中导出，并在另一个模块中导入。您必须将导出的宏函数放在一个单独的文件中使用，而且只有宏定义、宏导入和宏展开可以放入这个宏导出模块中。 +宏函数可以从一个模块中导出，并在另一个模块中导入。你必须将导出的宏函数放在一个单独的文件中使用，而且只有宏定义、宏导入和宏展开可以放入这个宏导出模块中。 ```moonscript -- 文件: utils.yue export macro map = (items, action) -> "[#{action} for _ in *#{items}]" @@ -439,7 +439,7 @@ tb::func! if tb != nil ### 链式比较 -您可以在月之脚本中进行比较表达式的链式书写： +你可以在月之脚本中进行比较表达式的链式书写： ```moonscript print 1 < 2 <= 2 < 3 == 3 > 2 >= 1 == 1 < 3 != 5 @@ -528,7 +528,7 @@ tab[] = "Value" ### 表扩展 -您可以使用前置 `...` 操作符在Lua表中插入数组表或哈希表。 +你可以使用前置 `...` 操作符在Lua表中插入数组表或哈希表。 ```moonscript parts = @@ -569,7 +569,7 @@ merge = {...a, ...b} **<>** 操作符可提供元表操作的快捷方式。 -* **元表创建** +* **元表创建** 使用空括号 **<>** 或被 **<>** 包围的元方法键创建普通的Lua表。 ```moonscript @@ -605,7 +605,7 @@ close _ = <close>: -> print "超出范围" -* **元表访问** +* **元表访问** 使用 **<>** 或被 **<>** 包围的元方法名或在 **<>** 中编写某些表达式来访问元表。 ```moonscript @@ -629,7 +629,7 @@ print tb.item -* **元表解构** +* **元表解构** 使用被 **<>** 包围的元方法键解构元表。 ```moonscript @@ -680,7 +680,7 @@ with? io.open "test.txt", "w" ### 管道 -与其使用一系列嵌套的函数调用，您还可以考虑使用运算符 **|>** 来传递值。 +与其使用一系列嵌套的函数调用，你还可以考虑使用运算符 **|>** 来传递值。 ```moonscript "你好" |> print @@ -731,7 +731,7 @@ a ??= false ### 隐式对象 -您可以在表格块内使用符号 **\*** 开始编写一系列隐式结构。如果您正在创建隐式对象，对象的字段必须具有相同的缩进。 +你可以在表格块内使用符号 **\*** 开始编写一系列隐式结构。如果你正在创建隐式对象，对象的字段必须具有相同的缩进。 ```moonscript list = * 1 @@ -859,7 +859,7 @@ do 导出语句提供了一种简洁的方式来定义当前的模块。 -* **命名导出** +* **命名导出** 带命名的导出将定义一个局部变量，并在导出的表中添加一个同名的字段。 ```moonscript @@ -923,7 +923,7 @@ export["a-b-c"] = 123 -* **未命名导出** +* **未命名导出** 未命名导出会将要导出的目标项目添加到导出表的数组部分。 ```moonscript @@ -953,7 +953,7 @@ export with tmp -* **默认导出** +* **默认导出** 在导出语句中使用 **default** 关键字，来替换导出的表为一个目标的对象。 ```moonscript @@ -1223,7 +1223,7 @@ print first, second, color -在进行解构时，您可以指定默认值，如： +在进行解构时，你可以指定默认值，如： ```moonscript {:name = "nameless", :job = "jobless"} = person @@ -1234,7 +1234,7 @@ print first, second, color -在进行列表解构时，您可以使用`_`作为占位符： +在进行列表解构时，你可以使用`_`作为占位符： ```moonscript [_, two, _, four] = items @@ -1322,7 +1322,7 @@ print "好的" ### While 赋值 -您可以在 while 循环中同样使用赋值来获取循环条件的值。 +你可以在 while 循环中同样使用赋值来获取循环条件的值。 ```moonscript while byte := stream\read_one! -- 对 byte 做一些操作 @@ -1338,7 +1338,7 @@ while byte := stream\read_one! ## 可变参数赋值 -您可以将函数返回的结果赋值给一个可变参数符号 `...`。然后使用Lua的方式访问其内容。 +你可以将函数返回的结果赋值给一个可变参数符号 `...`。然后使用Lua的方式访问其内容。 ```moonscript list = [1, 2, 3, 4, 5] fn = (ok) -> ok, table.unpack list @@ -1360,7 +1360,7 @@ print ok, count, first ## 空白 -月之脚本是一个对空白敏感的语言。您必须在相同的缩进中使用空格 **' '** 或制表符 **'\t'** 来编写一些代码块，如函数体、值列表和一些控制块。包含不同空白的表达式可能意味着不同的事情。制表符被视为4个空格，但最好不要混合使用空格和制表符。 +月之脚本是一个对空白敏感的语言。你必须在相同的缩进中使用空格 **' '** 或制表符 **'\t'** 来编写一些代码块，如函数体、值列表和一些控制块。包含不同空白的表达式可能意味着不同的事情。制表符被视为4个空格，但最好不要混合使用空格和制表符。 ### 多行链式调用 @@ -1529,7 +1529,7 @@ print "我有#{math.random! * 100}%的把握。" ### 数字字面量 -您可以在数字字面量中使用下划线来增加可读性。 +你可以在数字字面量中使用下划线来增加可读性。 ```moonscript integer = 1_000_000 @@ -1644,7 +1644,7 @@ print "数字的和是", sum 10, 20 -如果您需要做显式返回，可以使用return关键字： +如果你需要做显式返回，可以使用return关键字： ```moonscript sum = (x, y) -> return x + y @@ -1850,7 +1850,7 @@ print @value -您可以通过一个占位符指定回调函数的传参位置。 +你可以通过一个占位符指定回调函数的传参位置。 ```moonscript (x) <- map _, [1, 2, 3] @@ -1863,7 +1863,7 @@ x * 2 -如果您希望在反向回调处理后继续编写更多其它的代码，您可以使用do语句将不归属反向回调的代码分开。 +如果你希望在反向回调处理后继续编写更多其它的代码，你可以使用do语句将不归属反向回调的代码分开。 ```moonscript result, msg = do @@ -2037,7 +2037,7 @@ list_with_one_element = [ 1, ] ## 推导式 -推导式为我们提供了一种便捷的语法，通过遍历现有对象并对其值应用表达式来构造出新的表格。月之脚本有两种推导式：列表推导式和表格推导式。它们最终都是产生Lua表格；列表推导式将值累积到类似数组的表格中，而表格推导式允许您在每次遍历时设置新表格的键和值。 +推导式为我们提供了一种便捷的语法，通过遍历现有对象并对其值应用表达式来构造出新的表格。月之脚本有两种推导式：列表推导式和表格推导式。它们最终都是产生Lua表格；列表推导式将值累积到类似数组的表格中，而表格推导式允许你在每次遍历时设置新表格的键和值。 ### 列表推导式 @@ -2286,7 +2286,7 @@ doubled_evens = for i = 1, 20 -您还可以结合for循环表达式与continue语句来过滤值。 +你还可以结合for循环表达式与continue语句来过滤值。 注意出现在函数体末尾的for循环，不会被当作是一个表达式，并将循环结果累积到一个列表中作为返回值（相反，函数将返回nil）。如果要函数末尾的循环转换为列表表达式，可以使用返回语句加for循环表达式。 @@ -2513,7 +2513,7 @@ print "你真幸运！" unless math.random! > 0.1 ### 范围表达式 -您可以使用范围表达式来编写进行范围检查的代码。 +你可以使用范围表达式来编写进行范围检查的代码。 ```moonscript a = 5 @@ -2684,7 +2684,7 @@ else -值得注意的是，在生成Lua代码时，我们要做检查的目标变量会放在==表达式的右侧。当您希望给when子句的比较对象定义一个\_\_eq元方法来重载判断逻辑时，可能会有用。 +值得注意的是，在生成Lua代码时，我们要做检查的目标变量会放在==表达式的右侧。当你希望给when子句的比较对象定义一个\_\_eq元方法来重载判断逻辑时，可能会有用。 ### 表格匹配 @@ -2744,9 +2744,105 @@ switch item +你也可以匹配数组元素、表格字段，甚至使用数组或表格字面量来匹配嵌套的结构。 + +匹配数组元素。 + +```moonscript +switch tb + when [1, 2, 3] + print "1, 2, 3" + when [1, b, 3] + print "1, #{b}, 3" + when [1, 2, b = 3] -- 变量b有默认值 + print "1, 2, #{b}" +``` + +
+switch tb
+  when [1, 2, 3]
+    print "1, 2, 3"
+  when [1, b, 3]
+    print "1, #{b}, 3"
+  when [1, 2, b = 3] -- 变量b有默认值
+    print "1, 2, #{b}"
+
+ + +匹配表格字段。 + +```moonscript +switch tb + when success: true, :result + print "成功", result + when success: false + print "失败", result + else + print "无效值" +``` + +
+switch tb
+  when success: true, :result
+    print "成功", result
+  when success: false
+    print "失败", result
+  else
+    print "无效值"
+
+ + +匹配嵌套的表格结构。 + +```moonscript +switch tb + when data: {type: "success", :content} + print "成功", content + when data: {type: "error", :content} + print "失败", content + else + print "无效值" +``` + +
+switch tb
+  when data: {type: "success", :content}
+    print "成功", content
+  when data: {type: "error", :content}
+    print "失败", content
+  else
+    print "无效值"
+
+ + +匹配表格数组。 + +```moonscript +switch tb + when [ + {a: 1, b: 2} + {a: 3, b: 4} + {a: 5, b: 6} + fourth + ] + print "匹配成功", fourth +``` + +
+switch tb
+  when [
+      {a: 1, b: 2}
+      {a: 3, b: 4}
+      {a: 5, b: 6}
+      fourth
+    ]
+    print "匹配成功", fourth
+
+ + ## 面向对象编程 -在以下的示例中，月之脚本生成的Lua代码可能看起来会很复杂。所以最好主要关注月之脚本代码层面的意义，然后如果您想知道关于面向对象功能的实现细节，再查看Lua代码。 +在以下的示例中，月之脚本生成的Lua代码可能看起来会很复杂。所以最好主要关注月之脚本代码层面的意义，然后如果你想知道关于面向对象功能的实现细节，再查看Lua代码。 一个简单的类： @@ -3214,7 +3310,7 @@ x = class ### 类混合 -您可以通过使用 `using` 关键字来实现类混合。这意味着您可以从一个普通 Lua 表格或已定义的类对象中，复制函数到您创建的新类中。当您使用普通 Lua 表格进行类混合时，您有机会用自己的实现来重写类的索引方法（例如元方法 `__index`）。然而，当您从一个类对象做混合时，需要注意的是该类对象的元方法将不会被复制到新类。 +你可以通过使用 `using` 关键字来实现类混合。这意味着你可以从一个普通 Lua 表格或已定义的类对象中，复制函数到你创建的新类中。当你使用普通 Lua 表格进行类混合时，你有机会用自己的实现来重写类的索引方法（例如元方法 `__index`）。然而，当你从一个类对象做混合时，需要注意的是该类对象的元方法将不会被复制到新类。 ```moonscript MyIndex = __index: var: 1 @@ -3316,7 +3412,7 @@ me = create_person "Leaf", [dad, mother, sister] 在此用法中，with可以被视为K组合子（k-combinator）的一种特殊形式。 -如果您想给表达式另外起一个名称的话，with语句中的表达式也可以是一个赋值语句。 +如果你想给表达式另外起一个名称的话，with语句中的表达式也可以是一个赋值语句。 ```moonscript with str = "你好" @@ -3373,7 +3469,7 @@ print var -- 这里是nil -月之脚本的 **do** 也可以用作表达式。允许您将多行代码的处理合并为一个表达式，并将do语句代码块的最后一个语句作为表达式返回的结果。 +月之脚本的 **do** 也可以用作表达式。允许你将多行代码的处理合并为一个表达式，并将do语句代码块的最后一个语句作为表达式返回的结果。 ```moonscript counter = do @@ -4332,8 +4428,8 @@ simplified: boolean 版权 (c) 2017-2025 李瑾 \ -特此免费授予任何获得本软件副本和相关文档文件（下称“软件”）的人不受限制地处置该软件的权利，包括不受限制地使用、复制、修改、合并、发布、分发、转授许可和/或出售该软件副本，以及再授权被配发了本软件的人如上的权利，须在下列条件下： -上述版权声明和本许可声明应包含在该软件的所有副本或实质成分中。 +特此免费授予任何获得本软件副本和相关文档文件（下称“软件”）的人不受限制地处置该软件的权利，包括不受限制地使用、复制、修改、合并、发布、分发、转授许可和/或出售该软件副本，以及再授权被配发了本软件的人如上的权利，须在下列条件下： +上述版权声明和本许可声明应包含在该软件的所有副本或实质成分中。 本软件是“如此”提供的，没有任何形式的明示或暗示的保证，包括但不限于对适销性、特定用途的适用性和不侵权的保证。在任何情况下，作者或版权持有人都不对任何索赔、损害或其他责任负责，无论这些追责来自合同、侵权或其它行为中，还是产生于、源于或有关于本软件以及本软件的使用或其它处置。 -- cgit v1.2.3-55-g6feb