5 files changed, 1885 insertions, 379 deletions

diff --git a/doc/docs/.vuepress/components/YueCompiler.vue b/doc/docs/.vuepress/components/YueCompiler.vue
index 6b6042c..3a22d1c 100755
--- a/doc/docs/.vuepress/components/YueCompiler.vue
+++ b/doc/docs/.vuepress/components/YueCompiler.vue
@@ -1,21 +1,21 @@
 <template>
                 <div style="width: 100%; height: auto;">
                         <div class="parent" style="background-color: #f5f7ff;">
-                                <div class="childL" style="height: 2.5em;">
+                                <div class="editor-section">
                                         <div class="childTitle">YueScript {{ info }}</div>
+                                        <div class="editor-container" ref='yueEditor'>
+                                                <ClientOnly>
+                                                        <prism-editor class="my-editor" v-model="code" :highlight="highlighterYue" @input="codeChanged($event)" line-numbers :readonly="readonly"></prism-editor>
+                                                </ClientOnly>
+                                        </div>
                                 </div>
-                                <div class="childR" style="height: 2.5em;">
+                                <div class="editor-section">
                                         <div class="childTitle">Lua</div>
-                                </div>
-                                <div class="childL" ref='yueEditor' style="height: 30em;">
-                                        <ClientOnly>
-                                                <prism-editor class="my-editor" v-model="code" :highlight="highlighterYue" @input="codeChanged($event)" line-numbers :readonly="readonly"></prism-editor>
-                                        </ClientOnly>
-                                </div>
-                                <div class="childR" style="height: 30em;">
-                                        <ClientOnly>
-                                                <prism-editor class="my-editor" v-model="compiled" :highlight="highlighterLua" @input="codeChanged($event)" readonly></prism-editor>
-                                        </ClientOnly>
+                                        <div class="editor-container">
+                                                <ClientOnly>
+                                                        <prism-editor class="my-editor" v-model="compiled" :highlight="highlighterLua" @input="codeChanged($event)" :line-numbers="isMobileLayout" readonly></prism-editor>
+                                                </ClientOnly>
+                                        </div>
                                 </div>
                         </div>
                         <div v-if="!compileronly">
@@ -57,9 +57,18 @@
                                 code: '',
                                 compiled: '',
                                 result: '',
+                                windowWidth: 0,
                         };
                 },
+                computed: {
+                        isMobileLayout() {
+                                return this.windowWidth <= 768;
+                        },
+                },
                 mounted () {
+                        this.windowWidth = window.innerWidth;
+                        window.addEventListener('resize', this.handleResize);
+
                         if (this.text !== '') {
                                 this.$data.code = this.text;
                                 this.codeChanged(this.text);
@@ -86,7 +95,13 @@
                         })(this);
                         check();
                 },
+                beforeDestroy() {
+                        window.removeEventListener('resize', this.handleResize);
+                },
                 methods: {
+                        handleResize() {
+                                this.windowWidth = window.innerWidth;
+                        },
                         runCode() {
                                 if (window.yue && this.$data.compiled !== '') {
                                         let res = '';
@@ -136,27 +151,35 @@
                 resize: none;
                 margin-top: 5px;
         }
-        .childL {
-                float: left;
-                width: 50%;
-                box-sizing: border-box;
-                background-clip: content-box;
-                background: #f5f7ff;
+
+        .parent {
+                display: flex;
+                flex-wrap: wrap;
+                width: 100%;
         }
-        .childR {
-                float: left;
+
+        .editor-section {
                 width: 50%;
                 box-sizing: border-box;
-                background-clip: content-box;
                 background: #f5f7ff;
         }
+
+        .editor-container {
+                height: 55vh;
+        }
+
         .childTitle {
                 width: 100%;
                 font-size: 1.2em;
                 color: #b7ae8f;
                 text-align: center;
                 padding: 0.2em;
+                height: 2.5em;
+                display: flex;
+                align-items: center;
+                justify-content: center;
         }
+
         .button {
                 float: right;
                 border: none;
@@ -173,9 +196,11 @@
                 margin-top: 10px;
                 margin-right: 5px;
         }
+
         .button:hover {
                 background-color: #beb69a;
         }
+
         .button:focus,
         .button:active:focus,
         .button.active:focus,
@@ -207,5 +232,19 @@
         .my-editor >>> .prism-editor__textarea:focus {
                 outline: none;
         }
-</style>
 
+        /* 移动端响应式布局 */
+        @media screen and (max-width: 768px) {
+                .parent {
+                        flex-direction: column;
+                }
+
+                .editor-section {
+                        width: 100%;
+                }
+
+                .editor-container {
+                        height: 30vh;
+                }
+        }
+</style>
diff --git a/doc/docs/README.md b/doc/docs/README.md
index 21e47c4..098d7da 100755
--- a/doc/docs/README.md
+++ b/doc/docs/README.md
@@ -3,6 +3,6 @@ home: true
 heroImage: ./image/yuescript.svg
 actionText: Quick Start →
 actionLink: /doc/
-footer: MIT Licensed | Copyright © 2017-2025 Li Jin
+footer: MIT Licensed | Copyright © 2017-2026 Li Jin
 ---
 
diff --git a/doc/docs/doc/README.md b/doc/docs/doc/README.md
index c4518bf..b5051d4 100755
--- a/doc/docs/doc/README.md
+++ b/doc/docs/doc/README.md
@@ -16,19 +16,29 @@ Yue (月) is the name of moon in Chinese and it's pronounced as [jyɛ].
 ### An Overview of YueScript
 ```moonscript
 -- import syntax
-import "yue" as :p, :to_lua
+import p, to_lua from "yue"
 
 -- object literals
 inventory =
   equipment:
-    * "sword"
-    * "shield"
+    - "sword"
+    - "shield"
   items:
-    * name: "potion"
+    - name: "potion"
       count: 10
-    * name: "bread"
+    - name: "bread"
       count: 3
 
+-- list comprehension
+map = (arr, action) ->
+  [action item for item in *arr]
+
+filter = (arr, cond) ->
+  [item for item in *arr when cond item]
+
+reduce = (arr, init, action): init ->
+  init = action init, item for item in *arr
+
 -- pipe operator
 [1, 2, 3]
   |> map (x) -> x * 2
@@ -51,19 +61,29 @@ export 🌛 = "月之脚本"
 <YueDisplay>
 <pre>
 -- import syntax
-import "yue" as :p, :to_lua
+import p, to_lua from "yue"
 
 -- object literals
 inventory =
   equipment:
-    * "sword"
-    * "shield"
+    - "sword"
+    - "shield"
   items:
-    * name: "potion"
+    - name: "potion"
       count: 10
-    * name: "bread"
+    - name: "bread"
       count: 3
 
+-- list comprehension
+map = (arr, action) ->
+  [action item for item in *arr]
+
+filter = (arr, cond) ->
+  [item for item in *arr when cond item]
+
+reduce = (arr, init, action): init ->
+  init = action init, item for item in *arr
+
 -- pipe operator
 [1, 2, 3]
   |> map (x) -> x * 2
@@ -132,14 +152,14 @@ export 🌛 = "月之脚本"
 
 &emsp;Use YueScript module in Lua:
 
-* **Case 1**  
+* **Case 1**
 Require "your_yuescript_entry.yue" in Lua.
 ```Lua
 require("yue")("your_yuescript_entry")
 ```
 &emsp;And this code still works when you compile "your_yuescript_entry.yue"  to "your_yuescript_entry.lua" in the same path. In the rest YueScript files just use the normal **require** or **import**. The code line numbers in error messages will also be handled correctly.
 
-* **Case 2**  
+* **Case 2**
 Require YueScript module and rewite message by hand.
 ```lua
 local yue = require("yue")
@@ -151,7 +171,7 @@ end, function(err)
 end)
 ```
 
-* **Case 3**  
+* **Case 3**
 Use the YueScript compiler function in Lua.
 ```lua
 local yue = require("yue")
@@ -203,12 +223,12 @@ Usage: yue [options|files|directories] ...
    Execute without options to enter REPL, type symbol '$'
    in a single line to start/stop multi-line mode
 ```
-&emsp;&emsp;Use cases:  
-&emsp;&emsp;Recursively compile every YueScript file with extension **.yue** under current path:  **yue .**  
-&emsp;&emsp;Compile and save results to a target path:  **yue -t /target/path/ .**  
-&emsp;&emsp;Compile and reserve debug info:  **yue -l .**  
-&emsp;&emsp;Compile and generate minified codes:  **yue -m .**  
-&emsp;&emsp;Execute raw codes:  **yue -e 'print 123'**  
+&emsp;&emsp;Use cases:
+&emsp;&emsp;Recursively compile every YueScript file with extension **.yue** under current path:  **yue .**
+&emsp;&emsp;Compile and save results to a target path:  **yue -t /target/path/ .**
+&emsp;&emsp;Compile and reserve debug info:  **yue -l .**
+&emsp;&emsp;Compile and generate minified codes:  **yue -m .**
+&emsp;&emsp;Execute raw codes:  **yue -e 'print 123'**
 &emsp;&emsp;Execute a YueScript file:  **yue -e main.yue**
 
 ## Macro
@@ -388,16 +408,16 @@ In YueScript, macro functions allow you to generate code at compile time. By nes
 
 ```moonscript
 macro Enum = (...) ->
-        items = {...}
-        itemSet = {item, true for item in *items}
-        (item) ->
-                error "got \"#{item}\", expecting one of #{table.concat items, ', '}" unless itemSet[item]
-                "\"#{item}\""
+  items = {...}
+  itemSet = {item, true for item in *items}
+  (item) ->
+    error "got \"#{item}\", expecting one of #{table.concat items, ', '}" unless itemSet[item]
+    "\"#{item}\""
 
 macro BodyType = $Enum(
-        Static
-        Dynamic
-        Kinematic
+  Static
+  Dynamic
+  Kinematic
 )
 
 print "Valid enum type:", $BodyType Static
@@ -407,16 +427,16 @@ print "Valid enum type:", $BodyType Static
 <YueDisplay>
 <pre>
 macro Enum = (...) ->
-        items = {...}
-        itemSet = {item, true for item in *items}
-        (item) ->
-                error "got \"#{item}\", expecting one of #{table.concat items, ', '}" unless itemSet[item]
-                "\"#{item}\""
+  items = {...}
+  itemSet = {item, true for item in *items}
+  (item) ->
+    error "got \"#{item}\", expecting one of #{table.concat items, ', '}" unless itemSet[item]
+    "\"#{item}\""
 
 macro BodyType = $Enum(
-        Static
-        Dynamic
-        Kinematic
+  Static
+  Dynamic
+  Kinematic
 )
 
 print "Valid enum type:", $BodyType Static
@@ -424,6 +444,54 @@ print "Valid enum type:", $BodyType Static
 </pre>
 </YueDisplay>
 
+### Argument Validation
+
+You can declare the expected AST node types in the argument list, and check whether the incoming macro arguments meet the expectations at compile time.
+
+```moonscript
+macro printNumAndStr = (num `Num, str `String) -> |
+  print(
+    #{num}
+    #{str}
+  )
+
+$printNumAndStr 123, "hello"
+```
+<YueDisplay>
+<pre>
+macro printNumAndStr = (num `Num, str `String) -> |
+  print(
+    #{num}
+    #{str}
+  )
+
+$printNumAndStr 123, "hello"
+</pre>
+</YueDisplay>
+
+If you need more flexible argument checking, you can use the built-in `$is_ast` macro function to manually check at the appropriate place.
+
+```moonscript
+macro printNumAndStr = (num, str) ->
+  error "expected Num as first argument" unless $is_ast Num, num
+  error "expected String as second argument" unless $is_ast String, str
+  "print(#{num}, #{str})"
+
+$printNumAndStr 123, "hello"
+```
+<YueDisplay>
+<pre>
+macro printNumAndStr = (num, str) ->
+  error "expected Num as first argument" unless $is_ast Num, num
+  error "expected String as second argument" unless $is_ast String, str
+  "print(#{num}, #{str})"
+
+$printNumAndStr 123, "hello"
+</pre>
+</YueDisplay>
+
+For more details about available AST nodes, please refer to the uppercased definitions in [yue_parser.cpp](https://github.com/IppClub/YueScript/blob/main/src/yuescript/yue_parser.cpp).
+
 ## Operator
 
 All of Lua's binary and unary operators are available. Additionally **!=** is as an alias for **~=**, and either **\\** or **::** can be used to write a chaining function call like `tb\func!` or `tb::func!`. And Yuescipt offers some other special operators to write more expressive codes.
@@ -466,47 +534,47 @@ Note the evaluation behavior of chained comparisons:
 
 ```moonscript
 v = (x) ->
-        print x
-        x
+  print x
+  x
 
 print v(1) < v(2) <= v(3)
 --[[
-        output:
-        2
-        1
-        3
-        true
+  output:
+  2
+  1
+  3
+  true
 ]]
 
 print v(1) > v(2) <= v(3)
 --[[
-        output:
-        2
-        1
-        false
+  output:
+  2
+  1
+  false
 ]]
 ```
 <YueDisplay>
 <pre>
 v = (x) ->
-        print x
-        x
+  print x
+  x
 
 print v(1) < v(2) <= v(3)
 --[[
-        output:
-        2
-        1
-        3
-        true
+  output:
+  2
+  1
+  3
+  true
 ]]
 
 print v(1) > v(2) <= v(3)
 --[[
-        output:
-        2
-        1
-        false
+  output:
+  2
+  1
+  false
 ]]
 </pre>
 </YueDisplay>
@@ -527,19 +595,36 @@ tab[] = "Value"
 </pre>
 </YueDisplay>
 
+You can also use the spread operator `...` to append all elements from one list to another:
+
+```moonscript
+tbA = [1, 2, 3]
+tbB = [4, 5, 6]
+tbA[] = ...tbB
+-- tbA is now [1, 2, 3, 4, 5, 6]
+```
+<YueDisplay>
+<pre>
+tbA = [1, 2, 3]
+tbB = [4, 5, 6]
+tbA[] = ...tbB
+-- tbA is now [1, 2, 3, 4, 5, 6]
+</pre>
+</YueDisplay>
+
 ### Table Spreading
 
 You can concatenate array tables or hash tables using spread operator `...` before expressions in table literals.
 
 ```moonscript
 parts =
-        * "shoulders"
-        * "knees"
+  * "shoulders"
+  * "knees"
 lyrics =
-        * "head"
-        * ...parts
-        * "and"
-        * "toes"
+  * "head"
+  * ...parts
+  * "and"
+  * "toes"
 
 copy = {...other}
 
@@ -550,13 +635,13 @@ merge = {...a, ...b}
 <YueDisplay>
 <pre>
 parts =
-        * "shoulders"
-        * "knees"
+  * "shoulders"
+  * "knees"
 lyrics =
-        * "head"
-        * ...parts
-        * "and"
-        * "toes"
+  * "head"
+  * ...parts
+  * "and"
+  * "toes"
 
 copy = {...other}
 
@@ -566,11 +651,28 @@ merge = {...a, ...b}
 </pre>
 </YueDisplay>
 
+### Table Reversed Indexing
+
+You can use the **#** operator to get the last elements of a table.
+
+```moonscript
+last = data.items[#]
+second_last = data.items[#-1]
+data.items[#] = 1
+```
+<YueDisplay>
+<pre>
+last = data.items[#]
+second_last = data.items[#-1]
+data.items[#] = 1
+</pre>
+</YueDisplay>
+
 ### Metatable
 
 The **<>** operator can be used as a shortcut for metatable manipulation.
 
-* **Metatable Creation**  
+* **Metatable Creation**
 Create normal table with empty bracekets **<>** or metamethod key which is surrounded by **<>**.
 
 ```moonscript
@@ -606,7 +708,7 @@ close _ = &lt;close&gt;: -> print "out of scope"
 </pre>
 </YueDisplay>
 
-* **Metatable Accessing**  
+* **Metatable Accessing**
 Accessing metatable with **<>** or metamethod name surrounded by **<>** or writing some expression in **<>**.
 
 ```moonscript
@@ -630,7 +732,7 @@ print tb.item
 </pre>
 </YueDisplay>
 
-* **Metatable Destructure**  
+* **Metatable Destructure**
 Destruct metatable with metamethod key surrounded by **<>**.
 
 ```moonscript
@@ -732,34 +834,45 @@ a ??= false
 
 ### Implicit Object
 
-You can write a list of implicit structures that starts with the symbol **\*** inside a table block. If you are creating implicit object, the fields of the object must be with the same indent.
+You can write a list of implicit structures that starts with the symbol **\*** or **-** inside a table block. If you are creating implicit object, the fields of the object must be with the same indent.
+
 ```moonscript
+-- assignment with implicit object
 list =
   * 1
   * 2
   * 3
 
+-- function call with implicit object
 func
   * 1
   * 2
   * 3
 
+-- return with implicit object
+f = ->
+  return
+    * 1
+    * 2
+    * 3
+
+-- table with implicit object
 tb =
   name: "abc"
 
   values:
-    * "a"
-    * "b"
-    * "c"
+    - "a"
+    - "b"
+    - "c"
 
   objects:
-    * name: "a"
+    - name: "a"
       value: 1
       func: => @value + 1
       tb:
         fieldA: 1
 
-    * name: "b"
+    - name: "b"
       value: 2
       func: => @value + 2
       tb: { }
@@ -767,32 +880,42 @@ tb =
 ```
 <YueDisplay>
 <pre>
+-- assignment with implicit object
 list =
   * 1
   * 2
   * 3
 
+-- function call with implicit object
 func
   * 1
   * 2
   * 3
 
+-- return with implicit object
+f = ->
+  return
+    * 1
+    * 2
+    * 3
+
+-- table with implicit object
 tb =
   name: "abc"
 
   values:
-    * "a"
-    * "b"
-    * "c"
+    - "a"
+    - "b"
+    - "c"
 
   objects:
-    * name: "a"
+    - name: "a"
       value: 1
       func: => @value + 1
       tb:
         fieldA: 1
 
-    * name: "b"
+    - name: "b"
       value: 2
       func: => @value + 2
       tb: { }
@@ -856,11 +979,67 @@ do
 </pre>
 </YueDisplay>
 
+### Import Global
+
+You can import specific globals into local variables with `import`. When importing a chain of global variable accessings, the last field will be assigned to the local variable.
+
+```moonscript
+do
+  import tostring
+  import table.concat
+  print concat ["a", tostring 1]
+```
+<YueDisplay>
+<pre>
+do
+  import tostring
+  import table.concat
+  print concat ["a", tostring 1]
+</pre>
+</YueDisplay>
+
+#### Automatic Import
+
+You can place `import global` at the top of a block to automatically import all names that have not been explicitly declared or assigned in the current scope as globals. These implicit imports are treated as local consts that reference the corresponding globals at the position of the statement.
+
+Names that are explicitly declared as globals in the same scope will not be imported, so you can still assign to them.
+
+```moonscript
+do
+  import global
+  print "hello"
+  math.random 3
+  -- print = nil -- error: imported globals are const
+
+do
+  -- explicit global variable will not be imported
+  import global
+  global FLAG
+  print FLAG
+  FLAG = 123
+```
+<YueDisplay>
+<pre>
+do
+  import global
+  print "hello"
+  math.random 3
+  -- print = nil -- error: imported globals are const
+
+do
+  -- explicit global variable will not be imported
+  import global
+  global FLAG
+  print FLAG
+  FLAG = 123
+</pre>
+</YueDisplay>
+
 ### Export
 
 The export statement offers a concise way to define modules.
 
-* **Named Export**  
+* **Named Export**
 Named export will define a local variable as well as adding a field in the exported table.
 
 ```moonscript
@@ -924,7 +1103,7 @@ export["a-b-c"] = 123
 </pre>
 </YueDisplay>
 
-* **Unnamed Export**  
+* **Unnamed Export**
 Unnamed export will add the target item into the array part of the exported table.
 
 ```moonscript
@@ -954,7 +1133,7 @@ export with tmp
 </pre>
 </YueDisplay>
 
-* **Default Export**  
+* **Default Export**
 Using the **default** keyword in export statement to replace the exported table with any thing.
 
 ```moonscript
@@ -1202,7 +1381,7 @@ If the destructuring statement is complicated, feel free to spread it out over a
 </pre>
 </YueDisplay>
 
-It’s common to extract values from at table and assign them the local variables that have the same name as the key. In order to avoid repetition we can use the **:** prefix operator:
+It's common to extract values from at table and assign them the local variables that have the same name as the key. In order to avoid repetition we can use the **:** prefix operator:
 
 ```moonscript
 {:concat, :insert} = table
@@ -1246,6 +1425,52 @@ You can use `_` as placeholder when doing a list destructuring:
 </pre>
 </YueDisplay>
 
+### Range Destructuring
+
+You can use the spread operator `...` in list destructuring to capture a range of values. This is useful when you want to extract specific elements from the beginning and end of a list while collecting the rest in between.
+
+```moonscript
+orders = ["first", "second", "third", "fourth", "last"]
+[first, ...bulk, last] = orders
+print first  -- prints: first
+print bulk   -- prints: {"second", "third", "fourth"}
+print last   -- prints: last
+```
+<YueDisplay>
+<pre>
+orders = ["first", "second", "third", "fourth", "last"]
+[first, ...bulk, last] = orders
+print first  -- prints: first
+print bulk   -- prints: {"second", "third", "fourth"}
+print last   -- prints: last
+</pre>
+</YueDisplay>
+
+The spread operator can be used in different positions to capture different ranges, and you can use `_` as a placeholder for the values you don't want to capture:
+
+```moonscript
+-- Capture everything after first element
+[first, ...rest] = orders
+
+-- Capture everything before last element
+[...start, last] = orders
+
+-- Capture things except the middle elements
+[first, ..._, last] = orders
+```
+<YueDisplay>
+<pre>
+-- Capture everything after first element
+[first, ...rest] = orders
+
+-- Capture everything before last element
+[...start, last] = orders
+
+-- Capture things except the middle elements
+[first, ..._, last] = orders
+</pre>
+</YueDisplay>
+
 ### Destructuring In Other Places
 
 Destructuring can also show up in places where an assignment implicitly takes place. An example of this is a for loop:
@@ -1363,6 +1588,19 @@ print ok, count, first
 
 YueScript is a whitespace significant language. You have to write some code block in the same indent with space **' '** or tab **'\t'** like function body, value list and some control blocks. And expressions containing different whitespaces might mean different things. Tab is treated like 4 space, but it's better not mix the use of spaces and tabs.
 
+### Statement Separator
+
+A statement normally ends at a line break. You can also use a semicolon `;` to explicitly terminate a statement, which allows writing multiple statements on the same line:
+
+```moonscript
+a = 1; b = 2; print a + b
+```
+<YueDisplay>
+<pre>
+a = 1; b = 2; print a + b
+</pre>
+</YueDisplay>
+
 ### Multiline Chaining
 
 You can write multi-line chaining function calls with a same indent.
@@ -1475,6 +1713,47 @@ catch err
 </pre>
 </YueDisplay>
 
+### Try?
+
+`try?` is a simplified use for error handling syntax that omit the boolean status from the `try` statement, and it will return the result from the try block when success, return nil instead of error object otherwise.
+
+```moonscript
+a, b, c = try? func!
+
+-- with nil coalescing operator
+a = (try? func!) ?? "default"
+
+-- as function argument
+f try? func!
+
+-- with catch block
+f try?
+  print 123
+  func!
+catch e
+  print e
+  e
+```
+<YueDisplay>
+<pre>
+a, b, c = try? func!
+
+-- with nil coalescing operator
+a = (try? func!) ?? "default"
+
+-- as function argument
+f try? func!
+
+-- with catch block
+f try?
+  print 123
+  func!
+catch e
+  print e
+  e
+</pre>
+</YueDisplay>
+
 ## Attributes
 
 Syntax support for Lua 5.4 attributes. And you can still use both the `const` and `close` declaration and get constant check and scoped callback working when targeting Lua versions below 5.4.
@@ -1503,6 +1782,19 @@ const {:a, :b, c, d} = tb
 </pre>
 </YueDisplay>
 
+You can also declare a global variable to be `const`.
+
+```moonscript
+global const Constant = 123
+-- Constant = 1
+```
+<YueDisplay>
+<pre>
+global const Constant = 123
+-- Constant = 1
+</pre>
+</YueDisplay>
+
 ## Literals
 
 All of the primitive literals in Lua can be used. This applies to numbers, strings, booleans, and **nil**.
@@ -1535,12 +1827,73 @@ You can use underscores in a number literal to increase readability.
 ```moonscript
 integer = 1_000_000
 hex = 0xEF_BB_BF
+binary = 0B10011
 ```
 <YueDisplay>
 
 <pre>
 integer = 1_000_000
 hex = 0xEF_BB_BF
+binary = 0B10011
+</pre>
+</YueDisplay>
+
+### YAML Multiline String
+
+The `|` prefix introduces a YAML-style multiline string literal:
+
+```moonscript
+str = |
+  key: value
+  list:
+    - item1
+    - #{expr}
+```
+<YueDisplay>
+<pre>
+str = |
+  key: value
+  list:
+    - item1
+    - #{expr}
+</pre>
+</YueDisplay>
+
+This allows writing structured multiline text conveniently. All line breaks and indentation are preserved relative to the first non-empty line, and expressions inside `#{...}` are interpolated automatically as `tostring(expr)`.
+
+YAML Multiline String automatically detects the common leading whitespace prefix (minimum indentation across all non-empty lines) and removes it from all lines. This makes it easy to indent your code visually without affecting the resulting string content.
+
+```moonscript
+fn = ->
+  str = |
+    foo:
+      bar: baz
+  return str
+```
+<YueDisplay>
+<pre>
+fn = ->
+  str = |
+    foo:
+      bar: baz
+  return str
+</pre>
+</YueDisplay>
+
+Internal indentation is preserved relative to the removed common prefix, allowing clean nested structures.
+
+All special characters like quotes (`"`) and backslashes (`\`) in the YAMLMultiline block are automatically escaped so that the generated Lua string is syntactically valid and behaves as expected.
+
+```moonscript
+str = |
+  path: "C:\Program Files\App"
+  note: 'He said: "#{Hello}!"'
+```
+<YueDisplay>
+<pre>
+str = |
+  path: "C:\Program Files\App"
+  note: 'He said: "#{Hello}!"'
 </pre>
 </YueDisplay>
 
@@ -1861,6 +2214,138 @@ if func 1, 2, 3,
 </pre>
 </YueDisplay>
 
+### Parameter Destructuring
+
+YueScript now supports destructuring function parameters when the argument is an object. Two forms of destructuring table literals are available:
+
+* **Curly-brace wrapped literals/object parameters**, allowing optional default values when fields are missing (e.g., `{:a, :b}`, `{a: a1 = 123}`).
+
+* **Unwrapped simple table syntax**, starting with a sequence of key-value or shorthand bindings and continuing until another expression terminates it (e.g., `:a, b: b1, :c`). This form extracts multiple fields from the same object.
+
+```moonscript
+f1 = (:a, :b, :c) ->
+  print a, b, c
+
+f1 a: 1, b: "2", c: {}
+
+f2 = ({a: a1 = 123, :b = 'abc'}, c = {}) ->
+  print a1, b, c
+
+arg1 = {a: 0}
+f2 arg1, arg2
+```
+<YueDisplay>
+<pre>
+f1 = (:a, :b, :c) ->
+  print a, b, c
+
+f1 a: 1, b: "2", c: {}
+
+f2 = ({a: a1 = 123, :b = 'abc'}, c = {}) ->
+print a1, b, c
+
+arg1 = {a: 0}
+f2 arg1, arg2
+</pre>
+</YueDisplay>
+
+### Prefixed Return Expression
+
+When working with deeply nested function bodies, it can be tedious to maintain readability and consistency of the return value. To address this, YueScript introduces the **Prefixed Return Expression** syntax. Its form is as follows:
+
+```moon
+findFirstEven = (list): nil ->
+  for item in *list
+    if type(item) == "table"
+      for sub in *item
+        if sub % 2 == 0
+          return sub
+```
+<YueDisplay>
+<pre>
+findFirstEven = (list): nil ->
+  for item in *list
+    if type(item) == "table"
+      for sub in *item
+        if sub % 2 == 0
+          return sub
+</pre>
+</YueDisplay>
+
+This is equivalent to:
+
+```moon
+findFirstEven = (list) ->
+  for item in *list
+    if type(item) == "table"
+      for sub in *item
+        if sub % 2 == 0
+          return sub
+  nil
+```
+<YueDisplay>
+<pre>
+findFirstEven = (list) ->
+  for item in *list
+    if type(item) == "table"
+      for sub in *item
+        if sub % 2 == 0
+          return sub
+  nil
+</pre>
+</YueDisplay>
+
+The only difference is that you can move the final return expression before the `->` or `=>` token to indicate the function’s implicit return value as the last statement. This way, even in functions with multiple nested loops or conditional branches, you no longer need to write a trailing return expression at the end of the function body, making the logic structure more straightforward and easier to follow.
+
+### Named Varargs
+
+You can use the `(...t) ->` syntax to automatically store varargs into a named table. This table will contain all passed arguments (including `nil` values), and the `n` field of the table will store the actual number of arguments passed (including `nil` values).
+
+```moonscript
+f = (...t) ->
+  print "argument count:", t.n
+  print "table length:", #t
+  for i = 1, t.n
+    print t[i]
+
+f 1, 2, 3
+f "a", "b", "c", "d"
+f!
+
+-- Handling cases with nil values
+process = (...args) ->
+  sum = 0
+  for i = 1, args.n
+    if args[i] != nil and type(args[i]) == "number"
+      sum += args[i]
+  sum
+
+process 1, nil, 3, nil, 5
+```
+<YueDisplay>
+<pre>
+f = (...t) ->
+  print "argument count:", t.n
+  print "table length:", #t
+  for i = 1, t.n
+    print t[i]
+
+f 1, 2, 3
+f "a", "b", "c", "d"
+f!
+
+-- Handling cases with nil values
+process = (...args) ->
+  sum = 0
+  for i = 1, args.n
+    if args[i] != nil and type(args[i]) == "number"
+      sum += args[i]
+  sum
+
+process 1, nil, 3, nil, 5
+</pre>
+</YueDisplay>
+
 ## Backcalls
 
 Backcalls are used for unnesting callbacks. They are defined using arrows pointed to the left as the last parameter by default filling in a function call. All the syntax is mostly the same as regular arrow functions except that it is just pointing the other way and the function body does not require indent.
@@ -1902,22 +2387,22 @@ x * 2
 </pre>
 </YueDisplay>
 
-If you wish to have further code after your backcalls, you can set them aside with a do statement.
+If you wish to have further code after your backcalls, you can set them aside with a do statement. And the parentheses can be omitted with non-fat arrow functions.
 
 ```moonscript
 result, msg = do
-  (data) <- readAsync "filename.txt"
+  data <- readAsync "filename.txt"
   print data
-  (info) <- processAsync data
+  info <- processAsync data
   check info
 print result, msg
 ```
 <YueDisplay>
 <pre>
 result, msg = do
-  (data) <- readAsync "filename.txt"
+  data <- readAsync "filename.txt"
   print data
-  (info) <- processAsync data
+  info <- processAsync data
   check info
 print result, msg
 </pre>
@@ -2115,6 +2600,27 @@ doubled = [item * 2 for item in *items]
 </pre>
 </YueDisplay>
 
+In list comprehensions, you can also use the spread operator `...` to flatten nested lists, achieving a flat map effect:
+
+```moonscript
+data =
+  a: [1, 2, 3]
+  b: [4, 5, 6]
+
+flat = [...v for k,v in pairs data]
+-- flat is now [1, 2, 3, 4, 5, 6]
+```
+<YueDisplay>
+<pre>
+data =
+  a: [1, 2, 3]
+  b: [4, 5, 6]
+
+flat = [...v for k,v in pairs data]
+-- flat is now [1, 2, 3, 4, 5, 6]
+</pre>
+</YueDisplay>
+
 The for and when clauses can be chained as much as desired. The only requirement is that a comprehension has at least one for clause.
 
 Using multiple for clauses is the same as using nested loops:
@@ -2248,6 +2754,45 @@ slice = [item for item in *items[,,2]]
 </pre>
 </YueDisplay>
 
+Both the minimum and maximum bounds can be negative, which means that the bounds are counted from the end of the table.
+
+```moonscript
+-- take the last 4 items
+slice = [item for item in *items[-4,-1]]
+```
+<YueDisplay>
+<pre>
+-- take the last 4 items
+slice = [item for item in *items[-4,-1]]
+</pre>
+</YueDisplay>
+
+The step size can also be negative, which means that the items are taken in reverse order.
+
+```moonscript
+reverse_slice = [item for item in *items[-1,1,-1]]
+```
+<YueDisplay>
+<pre>
+reverse_slice = [item for item in *items[-1,1,-1]]
+</pre>
+</YueDisplay>
+
+#### Slicing Expression
+
+Slicing can also be used as an expression. This is useful for getting a sub-list of a table.
+
+```moonscript
+-- take the 2nd and 4th items as a new list
+sub_list = items[2, 4]
+```
+<YueDisplay>
+<pre>
+-- take the 2nd and 4th items as a new list
+sub_list = items[2, 4]
+</pre>
+</YueDisplay>
+
 ## For Loop
 
 There are two for loop forms, just like in Lua. A numeric one and a generic one:
@@ -2324,6 +2869,23 @@ doubled_evens = for i = 1, 20
 </pre>
 </YueDisplay>
 
+In addition, for loops support break with a return value, allowing the loop itself to be used as an expression that exits early with a meaningful result.
+
+For example, to find the first number greater than 10:
+
+```moonscript
+first_large = for n in *numbers
+  break n if n > 10
+```
+<YueDisplay>
+<pre>
+first_large = for n in *numbers
+  break n if n > 10
+</pre>
+</YueDisplay>
+
+This break-with-value syntax enables concise and expressive search or early-exit patterns directly within loop expressions.
+
 You can also filter values by combining the for loop expression with the continue statement.
 
 For loops at the end of a function body are not accumulated into a table for a return value (Instead the function will return nil). Either an explicit return statement can be used, or the loop can be converted into a list comprehension.
@@ -2345,7 +2907,7 @@ print func_b! -- prints table object
 </pre>
 </YueDisplay>
 
-This is done to avoid the needless creation of tables for functions that don’t need to return the results of the loop.
+This is done to avoid the needless creation of tables for functions that don't need to return the results of the loop.
 
 ## Repeat Loop
 
@@ -2624,28 +3186,26 @@ reader\parse_line! until reader\eof!
 
 ## Switch
 
-The switch statement is shorthand for writing a series of if statements that check against the same value. Note that the value is only evaluated once. Like if statements, switches can have an else block to handle no matches. Comparison is done with the == operator.
+The switch statement is shorthand for writing a series of if statements that check against the same value. Note that the value is only evaluated once. Like if statements, switches can have an else block to handle no matches. Comparison is done with the == operator. In switch statement, you can also use assignment expression to store temporary variable value.
 
 ```moonscript
-name = "Dan"
-switch name
+switch name := "Dan"
   when "Robert"
     print "You are Robert"
   when "Dan", "Daniel"
     print "Your name, it's Dan"
   else
-    print "I don't know about your name"
+    print "I don't know about you with name #{name}"
 ```
 <YueDisplay>
 <pre>
-name = "Dan"
-switch name
+switch name := "Dan"
   when "Robert"
     print "You are Robert"
   when "Dan", "Daniel"
     print "Your name, it's Dan"
   else
-    print "I don't know about your name"
+    print "I don't know about you with name #{name}"
 </pre>
 </YueDisplay>
 
@@ -2676,7 +3236,7 @@ next_number = switch b
 </pre>
 </YueDisplay>
 
-We can use the then keyword to write a switch’s when block on a single line. No extra keyword is needed to write the else block on a single line.
+We can use the then keyword to write a switch's when block on a single line. No extra keyword is needed to write the else block on a single line.
 
 ```moonscript
 msg = switch math.random(1, 5)
@@ -2722,7 +3282,7 @@ else
 </pre>
 </YueDisplay>
 
-It is worth noting the order of the case comparison expression. The case’s expression is on the left hand side. This can be useful if the case’s expression wants to overwrite how the comparison is done by defining an eq metamethod.
+It is worth noting the order of the case comparison expression. The case's expression is on the left hand side. This can be useful if the case's expression wants to overwrite how the comparison is done by defining an eq metamethod.
 
 ### Table Matching
 
@@ -2782,6 +3342,123 @@ switch item
 </pre>
 </YueDisplay>
 
+You can also match against array elements, table fields, and even nested structures with array or table literals.
+
+Match against array elements.
+
+```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 has a default value
+    print "1, 2, #{b}"
+```
+<YueDisplay>
+<pre>
+switch tb
+  when [1, 2, 3]
+    print "1, 2, 3"
+  when [1, b, 3]
+    print "1, #{b}, 3"
+  when [1, 2, b = 3] -- b has a default value
+    print "1, 2, #{b}"
+</pre>
+</YueDisplay>
+
+Match against table fields with destructuring.
+
+```moonscript
+switch tb
+  when success: true, :result
+    print "success", result
+  when success: false
+    print "failed", result
+  else
+    print "invalid"
+```
+<YueDisplay>
+<pre>
+switch tb
+  when success: true, :result
+    print "success", result
+  when success: false
+    print "failed", result
+  else
+    print "invalid"
+</pre>
+</YueDisplay>
+
+Match against nested table structures.
+
+```moonscript
+switch tb
+  when data: {type: "success", :content}
+    print "success", content
+  when data: {type: "error", :content}
+    print "failed", content
+  else
+    print "invalid"
+```
+<YueDisplay>
+<pre>
+switch tb
+  when data: {type: "success", :content}
+    print "success", content
+  when data: {type: "error", :content}
+    print "failed", content
+  else
+    print "invalid"
+</pre>
+</YueDisplay>
+
+Match against array of tables.
+
+```moonscript
+switch tb
+  when [
+      {a: 1, b: 2}
+      {a: 3, b: 4}
+      {a: 5, b: 6}
+      fourth
+    ]
+    print "matched", fourth
+```
+<YueDisplay>
+<pre>
+switch tb
+  when [
+      {a: 1, b: 2}
+      {a: 3, b: 4}
+      {a: 5, b: 6}
+      fourth
+    ]
+    print "matched", fourth
+</pre>
+</YueDisplay>
+
+Match against a list and capture a range of elements.
+
+```moonscript
+segments = ["admin", "users", "logs", "view"]
+switch segments
+  when [...groups, resource, action]
+    print "Group:", groups -- prints: {"admin", "users"}
+    print "Resource:", resource -- prints: "logs"
+    print "Action:", action -- prints: "view"
+```
+<YueDisplay>
+<pre>
+segments = ["admin", "users", "logs", "view"]
+switch segments
+  when [...groups, resource, action]
+    print "Group:", groups -- prints: {"admin", "users"}
+    print "Resource:", resource -- prints: "logs"
+    print "Action:", action -- prints: "view"
+</pre>
+</YueDisplay>
+
 ## Object Oriented Programming
 
 In these examples, the generated Lua code may appear overwhelming. It is best to focus on the meaning of the YueScript code at first, then look into the Lua code if you wish to know the implementation details.
@@ -2913,7 +3590,7 @@ class BackPack extends Inventory
 
 Here we extend our Inventory class, and limit the amount of items it can carry.
 
-In this example, we don’t define a constructor on the subclass, so the parent class' constructor is called when we make a new instance. If we did define a constructor then we can use the super method to call the parent constructor.
+In this example, we don't define a constructor on the subclass, so the parent class' constructor is called when we make a new instance. If we did define a constructor then we can use the super method to call the parent constructor.
 
 Whenever a class inherits from another, it sends a message to the parent class by calling the method __inherited on the parent class if it exists. The function receives two arguments, the class that is being inherited and the child class.
 
@@ -3000,13 +3677,13 @@ print BackPack.size -- prints 10
 
 The class object is what we create when we use a class statement. The class object is stored in a variable of the same name of the class.
 
-The class object can be called like a function in order to create new instances. That’s how we created instances of classes in the examples above.
+The class object can be called like a function in order to create new instances. That's how we created instances of classes in the examples above.
 
 A class is made up of two tables. The class table itself, and the base table. The base is used as the metatable for all the instances. All properties listed in the class declaration are placed in the base.
 
-The class object’s metatable reads properties from the base if they don’t exist in the class object. This means we can access functions and properties directly from the class.
+The class object's metatable reads properties from the base if they don't exist in the class object. This means we can access functions and properties directly from the class.
 
-It is important to note that assigning to the class object does not assign into the base, so it’s not a valid way to add new methods to instances. Instead the base must explicitly be changed. See the __base field below.
+It is important to note that assigning to the class object does not assign into the base, so it's not a valid way to add new methods to instances. Instead the base must explicitly be changed. See the __base field below.
 
 The class object has a couple special properties:
 
@@ -3079,7 +3756,7 @@ print Counter.count -- prints 2
 </pre>
 </YueDisplay>
 
-The calling semantics of @@ are similar to @. Calling a @@ name will pass the class in as the first argument using Lua’s colon syntax.
+The calling semantics of @@ are similar to @. Calling a @@ name will pass the class in as the first argument using Lua's colon syntax.
 
 ```moonscript
 @@hello 1,2,3,4
@@ -3094,7 +3771,7 @@ The calling semantics of @@ are similar to @. Calling a @@ name will pass the cl
 
 In the body of a class declaration, we can have normal expressions in addition to key/value pairs. In this context, self is equal to the class object.
 
-Here is an alternative way to create a class variable compared to what’s described above:
+Here is an alternative way to create a class variable compared to what's described above:
 
 ```moonscript
 class Things
@@ -3360,19 +4037,19 @@ In this usage, with can be seen as a special form of the K combinator.
 The expression in the with statement can also be an assignment, if you want to give a name to the expression.
 
 ```moonscript
-with str = "Hello"
+with str := "Hello"
   print "original:", str
   print "upper:", \upper!
 ```
 <YueDisplay>
 <pre>
-with str = "Hello"
+with str := "Hello"
   print "original:", str
   print "upper:", \upper!
 </pre>
 </YueDisplay>
 
-Accessing special keys with `[]` in a `with` statement.
+You can access special keys with `[]` in a `with` statement.
 
 ```moonscript
 with tb
@@ -3395,6 +4072,18 @@ with tb
 </pre>
 </YueDisplay>
 
+`with?` is an enhanced version of `with` syntax, which introduces an existential check to safely access objects that may be nil without explicit null checks.
+
+```moonscript
+with? obj
+  print obj.name
+```
+<YueDisplay>
+<pre>
+with? obj
+  print obj.name
+</pre>
+</YueDisplay>
 
 ## Do
 
@@ -3415,7 +4104,7 @@ print var -- nil here
 </pre>
 </YueDisplay>
 
-YueScript’s **do** can also be used an expression . Allowing you to combine multiple lines into one. The result of the do expression is the last statement in its body.
+YueScript's **do** can also be used an expression . Allowing you to combine multiple lines into one. The result of the do expression is the last statement in its body.
 
 ```moonscript
 counter = do
@@ -3541,7 +4230,7 @@ print i -- will print 0
 </pre>
 </YueDisplay>
 
-In my_func, we've overwritten the value of i mistakenly. In this example it is quite obvious, but consider a large, or foreign code base where it isn’t clear what names have already been declared.
+In my_func, we've overwritten the value of i mistakenly. In this example it is quite obvious, but consider a large, or foreign code base where it isn't clear what names have already been declared.
 
 It would be helpful to say which variables from the enclosing scope we intend on change, in order to prevent us from changing others by accident.
 
@@ -3657,9 +4346,9 @@ The YueScript compiling function. It compiles the YueScript code to Lua code.
 **Signature:**
 ```lua
 to_lua: function(code: string, config?: Config):
-                --[[codes]] string | nil,
-                --[[error]] string | nil,
-                --[[globals]] {{string, integer, integer}} | nil
+    --[[codes]] string | nil,
+    --[[error]] string | nil,
+    --[[globals]] {{string, integer, integer}} | nil
 ```
 
 **Parameters:**
@@ -3782,8 +4471,8 @@ Loads YueScript code from a string into a function.
 **Signature:**
 ```lua
 loadstring: function(input: string, chunkname: string, env: table, config?: Config):
-                --[[loaded function]] nil | function(...: any): (any...),
-                --[[error]] string | nil
+    --[[loaded function]] nil | function(...: any): (any...),
+    --[[error]] string | nil
 ```
 
 **Parameters:**
@@ -3813,8 +4502,8 @@ Loads YueScript code from a string into a function.
 **Signature:**
 ```lua
 loadstring: function(input: string, chunkname: string, config?: Config):
-                --[[loaded function]] nil | function(...: any): (any...),
-                --[[error]] string | nil
+    --[[loaded function]] nil | function(...: any): (any...),
+    --[[error]] string | nil
 ```
 
 **Parameters:**
@@ -3843,8 +4532,8 @@ Loads YueScript code from a string into a function.
 **Signature:**
 ```lua
 loadstring: function(input: string, config?: Config):
-                --[[loaded function]] nil | function(...: any): (any...),
-                --[[error]] string | nil
+    --[[loaded function]] nil | function(...: any): (any...),
+    --[[error]] string | nil
 ```
 
 **Parameters:**
@@ -3872,8 +4561,8 @@ Loads YueScript code from a file into a function.
 **Signature:**
 ```lua
 loadfile: function(filename: string, env: table, config?: Config):
-                nil | function(...: any): (any...),
-                string | nil
+    nil | function(...: any): (any...),
+    string | nil
 ```
 
 **Parameters:**
@@ -3902,8 +4591,8 @@ Loads YueScript code from a file into a function.
 **Signature:**
 ```lua
 loadfile: function(filename: string, config?: Config):
-                nil | function(...: any): (any...),
-                string | nil
+    nil | function(...: any): (any...),
+    string | nil
 ```
 
 **Parameters:**
@@ -4158,9 +4847,9 @@ Converts the code to the AST.
 
 **Signature:**
 ```lua
-to_ast: function(code: string, flattenLevel?: number, astName?: string):
-                --[[AST]] AST | nil,
-                --[[error]] nil | string
+to_ast: function(code: string, flattenLevel?: number, astName?: string, reserveComment?: boolean):
+    --[[AST]] AST | nil,
+    --[[error]] nil | string
 ```
 
 **Parameters:**
@@ -4170,6 +4859,7 @@ to_ast: function(code: string, flattenLevel?: number, astName?: string):
 | code | string | The code. |
 | flattenLevel | integer | [Optional] The flatten level. Higher level means more flattening. Default is 0. Maximum is 2. |
 | astName | string | [Optional] The AST name. Default is "File". |
+| reserveComment | boolean | [Optional] Whether to reserve the original comments. Default is false. |
 
 **Returns:**
 
@@ -4178,6 +4868,33 @@ to_ast: function(code: string, flattenLevel?: number, astName?: string):
 | AST \| nil | The AST, or nil if the conversion failed. |
 | string \| nil | The error message, or nil if the conversion succeeded. |
 
+#### format
+
+**Type:** Function.
+
+**Description:**
+
+Formats the YueScript code.
+
+**Signature:**
+```lua
+format: function(code: string, tabSize?: number, reserveComment?: boolean): string
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| code | string | The code. |
+| tabSize | integer | [Optional] The tab size. Default is 4. |
+| reserveComment | boolean | [Optional] Whether to reserve the original comments. Default is true. |
+
+**Returns:**
+
+| Return Type | Description |
+| --- | --- |
+| string | The formatted code. |
+
 #### __call
 
 **Type:** Metamethod.
@@ -4249,6 +4966,19 @@ Whether the compiler should reserve the original line number in the compiled cod
 reserve_line_number: boolean
 ```
 
+#### reserve_comment
+
+**Type:** Field.
+
+**Description:**
+
+Whether the compiler should reserve the original comments in the compiled code.
+
+**Signature:**
+```lua
+reserve_comment: boolean
+```
+
 #### space_over_tab
 
 **Type:** Field.
@@ -4299,11 +5029,11 @@ The target Lua version enumeration.
 **Signature:**
 ```lua
 enum LuaTarget
-        "5.1"
-        "5.2"
-        "5.3"
-        "5.4"
-        "5.5"
+  "5.1"
+  "5.2"
+  "5.3"
+  "5.4"
+  "5.5"
 end
 ```
 
@@ -4380,7 +5110,7 @@ simplified: boolean
 
 ## Licence: MIT
 
-Copyright (c) 2017-2025 Li Jin \<dragon-fly@qq.com\>
+Copyright (c) 2017-2026 Li Jin \<dragon-fly@qq.com\>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
diff --git a/doc/docs/zh/README.md b/doc/docs/zh/README.md
index f5c9811..05b2069 100755
--- a/doc/docs/zh/README.md
+++ b/doc/docs/zh/README.md
@@ -3,6 +3,6 @@ home: true
 heroImage: /image/yuescript.svg
 actionText: 快速上手 →
 actionLink: /zh/doc/
-footer: MIT Licensed | Copyright © 2017-2025 Li Jin
+footer: MIT Licensed | Copyright © 2017-2026 Li Jin
 ---
 
diff --git a/doc/docs/zh/doc/README.md b/doc/docs/zh/doc/README.md
index 754566c..43713fe 100755
--- a/doc/docs/zh/doc/README.md
+++ b/doc/docs/zh/doc/README.md
@@ -9,26 +9,36 @@ title: 参考手册
 
 ## 介绍
 
-月之脚本（YueScript）是一种动态语言，可以编译为Lua。它是[MoonScript](https://github.com/leafo/moonscript)的方言。用月之脚本编写的代码既有表现力又非常简洁。它适合编写一些更易于维护的代码，并在嵌入 Lua 的环境中运行，如游戏或网站服务器。
+月之脚本（YueScript）是一种动态语言，可以编译为 Lua。它是 [MoonScript](https://github.com/leafo/moonscript) 的方言。用月之脚本编写的代码既有表现力又非常简洁。它适合编写一些更易于维护的代码，并在嵌入 Lua 的环境中运行，如游戏或网站服务器。
 
 Yue（月）是中文中“月亮”的名称。
 
 ### 月之脚本概览
 ```moonscript
 -- 导入语法
-import "yue" as :p, :to_lua
+import p, to_lua from "yue"
 
 -- 隐式对象
 inventory =
   equipment:
-    * "sword"
-    * "shield"
+    - "sword"
+    - "shield"
   items:
-    * name: "potion"
+    - name: "potion"
       count: 10
-    * name: "bread"
+    - name: "bread"
       count: 3
 
+-- 列表推导
+map = (arr, action) ->
+  [action item for item in *arr]
+
+filter = (arr, cond) ->
+  [item for item in *arr when cond item]
+
+reduce = (arr, init, action): init ->
+  init = action init, item for item in *arr
+
 -- 管道操作符
 [1, 2, 3]
   |> map (x) -> x * 2
@@ -51,19 +61,29 @@ export 🌛 = "月之脚本"
 <YueDisplay>
 <pre>
 -- 导入语法
-import "yue" as :p, :to_lua
+import p, to_lua from "yue"
 
 -- 隐式对象
 inventory =
   equipment:
-    * "sword"
-    * "shield"
+    - "sword"
+    - "shield"
   items:
-    * name: "potion"
+    - name: "potion"
       count: 10
-    * name: "bread"
+    - name: "bread"
       count: 3
 
+-- 列表推导
+map = (arr, action) ->
+  [action item for item in *arr]
+
+filter = (arr, cond) ->
+  [item for item in *arr when cond item]
+
+reduce = (arr, init, action): init ->
+  init = action init, item for item in *arr
+
 -- 管道操作符
 [1, 2, 3]
   |> map (x) -> x * 2
@@ -89,7 +109,7 @@ export 🌛 = "月之脚本"
 
 * **Lua 模块**
 
-&emsp;安装 [luarocks](https://luarocks.org)，一个Lua模块的包管理器。然后作为Lua模块和可执行文件安装它：
+&emsp;安装 [luarocks](https://luarocks.org)，一个 Lua 模块的包管理器。然后作为 Lua 模块和可执行文件安装它：
 
 ```
 > luarocks install yuescript
@@ -122,7 +142,7 @@ export 🌛 = "月之脚本"
 
 * **下载预编译的二进制程序**
 
-&emsp;您可以下载预编译的二进制程序，包括兼容不同 Lua 版本的二进制可执行文件和库文件。
+&emsp;你可以下载预编译的二进制程序，包括兼容不同 Lua 版本的二进制可执行文件和库文件。
 
 &emsp;在[这里](https://github.com/IppClub/YueScript/releases)下载预编译的二进制程序。
 
@@ -130,16 +150,16 @@ export 🌛 = "月之脚本"
 
 ### Lua 模块
 
-在Lua中使用月之脚本模块：
+在 Lua 中使用月之脚本模块：
 
-* **用法 1**  
-在Lua中引入 "你的脚本入口文件.yue"。
+* **用法 1**
+在 Lua 中引入 "你的脚本入口文件.yue"。
 ```Lua
 require("yue")("你的脚本入口文件")
 ```
-当你在同一路径下把 "你的脚本入口文件.yue" 编译成了 "你的脚本入口文件.lua" 时，仍然可以使用这个代码加载 .lua 代码文件。在其余的月之脚本文件中，只需正常使用 **require** 或 **import**进行脚本引用即可。错误消息中的代码行号也会被正确处理。
+当你在同一路径下把 "你的脚本入口文件.yue" 编译成了 "你的脚本入口文件.lua" 时，仍然可以使用这个代码加载 .lua 代码文件。在其余的月之脚本文件中，只需正常使用 **require** 或 **import** 进行脚本引用即可。错误消息中的代码行号也会被正确处理。
 
-* **用法 2**  
+* **用法 2**
 手动引入月之脚本模块并重写错误消息来帮助调试。
 ```lua
 local yue = require("yue")
@@ -151,8 +171,8 @@ end, function(err)
 end)
 ```
 
-* **用法 3**  
-在Lua中使用月之脚本编译器功能。
+* **用法 3**
+在 Lua 中使用月之脚本编译器功能。
 ```lua
 local yue = require("yue")
 local codes, err, globals = yue.to_lua([[
@@ -333,7 +353,7 @@ end
 
 ### 导出宏
 
-宏函数可以从一个模块中导出，并在另一个模块中导入。您必须将导出的宏函数放在一个单独的文件中使用，而且只有宏定义、宏导入和宏展开可以放入这个宏导出模块中。
+宏函数可以从一个模块中导出，并在另一个模块中导入。你必须将导出的宏函数放在一个单独的文件中使用，而且只有宏定义、宏导入和宏展开可以放入这个宏导出模块中。
 ```moonscript
 -- 文件: utils.yue
 export macro map = (items, action) -> "[#{action} for _ in *#{items}]"
@@ -387,16 +407,16 @@ print $LINE -- 获取当前代码行数：2
 
 ```moonscript
 macro Enum = (...) ->
-        items = {...}
-        itemSet = {item, true for item in *items}
-        (item) ->
-                error "got \"#{item}\", expecting one of #{table.concat items, ', '}" unless itemSet[item]
-                "\"#{item}\""
+  items = {...}
+  itemSet = {item, true for item in *items}
+  (item) ->
+    error "got \"#{item}\", expecting one of #{table.concat items, ', '}" unless itemSet[item]
+    "\"#{item}\""
 
 macro BodyType = $Enum(
-        Static
-        Dynamic
-        Kinematic
+  Static
+  Dynamic
+  Kinematic
 )
 
 print "有效的枚举类型:", $BodyType Static
@@ -405,16 +425,16 @@ print "有效的枚举类型:", $BodyType Static
 <YueDisplay>
 <pre>
 macro Enum = (...) ->
-        items = {...}
-        itemSet = {item, true for item in *items}
-        (item) ->
-                error "got \"#{item}\", expecting one of #{table.concat items, ', '}" unless itemSet[item]
-                "\"#{item}\""
+  items = {...}
+  itemSet = {item, true for item in *items}
+  (item) ->
+    error "got \"#{item}\", expecting one of #{table.concat items, ', '}" unless itemSet[item]
+    "\"#{item}\""
 
 macro BodyType = $Enum(
-        Static
-        Dynamic
-        Kinematic
+  Static
+  Dynamic
+  Kinematic
 )
 
 print "有效的枚举类型:", $BodyType Static
@@ -422,9 +442,57 @@ print "有效的枚举类型:", $BodyType Static
 </pre>
 </YueDisplay>
 
+### 宏参数检查
+
+可以直接在参数列表中声明期望的 AST 节点类型，并在编译时检查传入的宏参数是否符合预期。
+
+```moonscript
+macro printNumAndStr = (num `Num, str `String) -> |
+  print(
+    #{num}
+    #{str}
+  )
+
+$printNumAndStr 123, "hello"
+```
+<YueDisplay>
+<pre>
+macro printNumAndStr = (num `Num, str `String) -> |
+  print(
+    #{num}
+    #{str}
+  )
+
+$printNumAndStr 123, "hello"
+</pre>
+</YueDisplay>
+
+如果需要做更加灵活的参数检查操作，可以使用内置的 `$is_ast` 宏函数在合适的位置进行手动检查。
+
+```moonscript
+macro printNumAndStr = (num, str) ->
+  error "expected Num as first argument" unless $is_ast Num, num
+  error "expected String as second argument" unless $is_ast String, str
+  "print(#{num}, #{str})"
+
+$printNumAndStr 123, "hello"
+```
+<YueDisplay>
+<pre>
+macro printNumAndStr = (num, str) ->
+  error "expected Num as first argument" unless $is_ast Num, num
+  error "expected String as second argument" unless $is_ast String, str
+  "print(#{num}, #{str})"
+
+$printNumAndStr 123, "hello"
+</pre>
+</YueDisplay>
+
+更多关于可用 AST 节点的详细信息，请参考 [yue_parser.cpp](https://github.com/IppClub/YueScript/blob/main/src/yuescript/yue_parser.cpp) 中大写的规则定义。
+
 ## 操作符
 
-Lua的所有二元和一元操作符在月之脚本中都是可用的。此外，**!=** 符号是 **~=** 的别名，而 **\\** 或 **::** 均可用于编写链式函数调用，如写作 `tb\func!` 或 `tb::func!`。此外月之脚本还提供了一些其他特殊的操作符，以编写更具表达力的代码。
+Lua 的所有二元和一元操作符在月之脚本中都是可用的。此外，**!=** 符号是 **~=** 的别名，而 **\\** 或 **::** 均可用于编写链式函数调用，如写作 `tb\func!` 或 `tb::func!`。此外月之脚本还提供了一些其他特殊的操作符，以编写更具表达力的代码。
 
 ```moonscript
 tb\func! if tb ~= nil
@@ -439,7 +507,7 @@ tb::func! if tb != nil
 
 ### 链式比较
 
-您可以在月之脚本中进行比较表达式的链式书写：
+你可以在月之脚本中进行比较表达式的链式书写：
 
 ```moonscript
 print 1 < 2 <= 2 < 3 == 3 > 2 >= 1 == 1 < 3 != 5
@@ -464,56 +532,56 @@ print 1 <= a <= 10
 
 ```moonscript
 v = (x) ->
-        print x
-        x
+  print x
+  x
 
 print v(1) < v(2) <= v(3)
 --[[
-        输出：
-        2
-        1
-        3
-        true
+  输出：
+  2
+  1
+  3
+  true
 ]]
 
 print v(1) > v(2) <= v(3)
 --[[
-        输出：
-        2
-        1
-        false
+  输出：
+  2
+  1
+  false
 ]]
 ```
 <YueDisplay>
 <pre>
 v = (x) ->
-        print x
-        x
+  print x
+  x
 
 print v(1) < v(2) <= v(3)
 --[[
-        输出：
-        2
-        1
-        3
-        true
+  输出：
+  2
+  1
+  3
+  true
 ]]
 
 print v(1) > v(2) <= v(3)
 --[[
-        输出：
-        2
-        1
-        false
+  输出：
+  2
+  1
+  false
 ]]
 </pre>
 </YueDisplay>
 
-在上面的例子里，中间的表达式`v(2)`仅被计算一次，如果把表达式写成`v(1) < v(2) and v(2) <= v(3)`的方式，中间的`v(2)`才会被计算两次。在链式比较中，求值的顺序往往是未定义的。所以强烈建议不要在链式比较中使用具有副作用（比如做打印操作）的表达式。如果需要使用有副作用的函数，应明确使用短路 `and` 运算符来做连接。
+在上面的例子里，中间的表达式 `v(2)` 仅被计算一次，如果把表达式写成 `v(1) < v(2) and v(2) <= v(3)` 的方式，中间的 `v(2)` 才会被计算两次。在链式比较中，求值的顺序往往是未定义的。所以强烈建议不要在链式比较中使用具有副作用（比如做打印操作）的表达式。如果需要使用有副作用的函数，应明确使用短路 `and` 运算符来做连接。
 
 ### 表追加
 
-**[] =** 操作符用于向Lua表的最后插入值。
+**[] =** 操作符用于向 Lua 表的最后插入值。
 
 ```moonscript
 tab = []
@@ -526,19 +594,36 @@ tab[] = "Value"
 </pre>
 </YueDisplay>
 
+你还可以使用展开操作符 `...` 来将一个列表中的所有元素追加到另一个列表中：
+
+```moonscript
+tbA = [1, 2, 3]
+tbB = [4, 5, 6]
+tbA[] = ...tbB
+-- tbA 现在为 [1, 2, 3, 4, 5, 6]
+```
+<YueDisplay>
+<pre>
+tbA = [1, 2, 3]
+tbB = [4, 5, 6]
+tbA[] = ...tbB
+-- tbA 现在为 [1, 2, 3, 4, 5, 6]
+</pre>
+</YueDisplay>
+
 ### 表扩展
 
-您可以使用前置 `...` 操作符在Lua表中插入数组表或哈希表。
+你可以使用前置 `...` 操作符在 Lua 表中插入数组表或哈希表。
 
 ```moonscript
 parts =
-        * "shoulders"
-        * "knees"
+  * "shoulders"
+  * "knees"
 lyrics =
-        * "head"
-        * ...parts
-        * "and"
-        * "toes"
+  * "head"
+  * ...parts
+  * "and"
+  * "toes"
 
 copy = {...other}
 
@@ -549,13 +634,13 @@ merge = {...a, ...b}
 <YueDisplay>
 <pre>
 parts =
-        * "shoulders"
-        * "knees"
+  * "shoulders"
+  * "knees"
 lyrics =
-        * "head"
-        * ...parts
-        * "and"
-        * "toes"
+  * "head"
+  * ...parts
+  * "and"
+  * "toes"
 
 copy = {...other}
 
@@ -565,12 +650,29 @@ merge = {...a, ...b}
 </pre>
 </YueDisplay>
 
+### 表反向索引
+
+你可以使用 **#** 操作符来反向索引表中的元素。
+
+```moonscript
+last = data.items[#]
+second_last = data.items[#-1]
+data.items[#] = 1
+```
+<YueDisplay>
+<pre>
+last = data.items[#]
+second_last = data.items[#-1]
+data.items[#] = 1
+</pre>
+</YueDisplay>
+
 ### 元表
 
 **<>** 操作符可提供元表操作的快捷方式。
 
-* **元表创建**  
-使用空括号 **<>** 或被 **<>** 包围的元方法键创建普通的Lua表。
+* **元表创建**
+使用空括号 **<>** 或被 **<>** 包围的元方法键创建普通的 Lua 表。
 
 ```moonscript
 mt = {}
@@ -605,7 +707,7 @@ close _ = &lt;close&gt;: -> print "超出范围"
 </pre>
 </YueDisplay>
 
-* **元表访问**  
+* **元表访问**
 使用 **<>** 或被 **<>** 包围的元方法名或在 **<>** 中编写某些表达式来访问元表。
 
 ```moonscript
@@ -629,7 +731,7 @@ print tb.item
 </pre>
 </YueDisplay>
 
-* **元表解构**  
+* **元表解构**
 使用被 **<>** 包围的元方法键解构元表。
 
 ```moonscript
@@ -680,7 +782,7 @@ with? io.open "test.txt", "w"
 
 ### 管道
 
-与其使用一系列嵌套的函数调用，您还可以考虑使用运算符 **|>** 来传递值。
+与其使用一系列嵌套的函数调用，你还可以考虑使用运算符 **|>** 来传递值。
 
 ```moonscript
 "你好" |> print
@@ -712,7 +814,7 @@ readFile "example.txt"
 
 ### 空值合并
 
-如果其左操作数不是**nil**，则nil合并运算符 **??** 返回其左操作数的值；否则，它将计算右操作数并返回其结果。如果左操作数计算结果为非nil的值，**??** 运算符将不再计算其右操作数。
+如果其左操作数不是 **nil**，则nil合并运算符 **??** 返回其左操作数的值；否则，它将计算右操作数并返回其结果。如果左操作数计算结果为非 nil 的值，**??** 运算符将不再计算其右操作数。
 ```moonscript
 local a, b, c, d
 a = b ?? c ?? d
@@ -731,67 +833,87 @@ a ??= false
 
 ### 隐式对象
 
-您可以在表格块内使用符号 **\*** 开始编写一系列隐式结构。如果您正在创建隐式对象，对象的字段必须具有相同的缩进。
+你可以在表格块内使用符号 **\*** 或是 **-** 开始编写一系列隐式结构。如果你正在创建隐式对象，对象的字段必须具有相同的缩进。
+
 ```moonscript
+-- 赋值时使用隐式对象
 list =
   * 1
   * 2
   * 3
 
+-- 函数调用时使用隐式对象
 func
   * 1
   * 2
   * 3
 
+-- 返回时使用隐式对象
+f = ->
+  return
+    * 1
+    * 2
+    * 3
+
+-- 表格时使用隐式对象
 tb =
   name: "abc"
 
   values:
-    * "a"
-    * "b"
-    * "c"
+    - "a"
+    - "b"
+    - "c"
 
   objects:
-    * name: "a"
+    - name: "a"
       value: 1
       func: => @value + 1
       tb:
         fieldA: 1
 
-    * name: "b"
+    - name: "b"
       value: 2
       func: => @value + 2
       tb: { }
-
 ```
 <YueDisplay>
 <pre>
+-- 赋值时使用隐式对象
 list =
   * 1
   * 2
   * 3
 
+-- 函数调用时使用隐式对象
 func
   * 1
   * 2
   * 3
 
+-- 返回时使用隐式对象
+f = ->
+  return
+    * 1
+    * 2
+    * 3
+
+-- 表格时使用隐式对象
 tb =
   name: "abc"
 
   values:
-    * "a"
-    * "b"
-    * "c"
+    - "a"
+    - "b"
+    - "c"
 
   objects:
-    * name: "a"
+    - name: "a"
       value: 1
       func: => @value + 1
       tb:
         fieldA: 1
 
-    * name: "b"
+    - name: "b"
       value: 2
       func: => @value + 2
       tb: { }
@@ -855,11 +977,67 @@ do
 </pre>
 </YueDisplay>
 
+### 导入全局变量
+
+你可以使用 `import` 将指定的全局变量导入到本地变量中。当导入一系列对全局变量的链式访问时，最后一个访问的字段将被赋值给本地变量。
+
+```moonscript
+do
+  import tostring
+  import table.concat
+  print concat ["a", tostring 1]
+```
+<YueDisplay>
+<pre>
+do
+  import tostring
+  import table.concat
+  print concat ["a", tostring 1]
+</pre>
+</YueDisplay>
+
+#### 自动导入
+
+在一个代码块的顶部写 `import global`，会将当前作用域中尚未显式声明或赋值过的变量名，自动导入为本地常量，并在该语句的位置绑定到同名的全局变量。
+
+但是在同一作用域中被显式声明为全局的变量不会被自动导入，因此可以继续进行赋值操作。
+
+```moonscript
+do
+  import global
+  print "hello"
+  math.random 3
+  -- print = nil -- 报错：自动导入的全局变量为常量
+
+do
+  -- 被显式声明为全局的变量不会被自动导入
+  import global
+  global FLAG
+  print FLAG
+  FLAG = 123
+```
+<YueDisplay>
+<pre>
+do
+  import global
+  print "hello"
+  math.random 3
+  -- print = nil -- 报错：自动导入的全局变量是常量
+
+do
+  -- 被显式声明为全局的变量不会被自动导入
+  import global
+  global FLAG
+  print FLAG
+  FLAG = 123
+</pre>
+</YueDisplay>
+
 ### 导出
 
 导出语句提供了一种简洁的方式来定义当前的模块。
 
-* **命名导出**  
+* **命名导出**
 带命名的导出将定义一个局部变量，并在导出的表中添加一个同名的字段。
 
 ```moonscript
@@ -923,7 +1101,7 @@ export["a-b-c"] = 123
 </pre>
 </YueDisplay>
 
-* **未命名导出**  
+* **未命名导出**
 未命名导出会将要导出的目标项目添加到导出表的数组部分。
 
 ```moonscript
@@ -953,7 +1131,7 @@ export with tmp
 </pre>
 </YueDisplay>
 
-* **默认导出**  
+* **默认导出**
 在导出语句中使用 **default** 关键字，来替换导出的表为一个目标的对象。
 
 ```moonscript
@@ -971,7 +1149,7 @@ export default ->
 
 ## 赋值
 
-月之脚本中定义的变量是动态类型的，并默认为局部变量。但你可以通过**local**和**global**声明来改变声明变量的作用范围。
+月之脚本中定义的变量是动态类型的，并默认为局部变量。但你可以通过 **local** 和 **global** 声明来改变声明变量的作用范围。
 
 ```moonscript
 hello = "world"
@@ -1100,9 +1278,9 @@ do
 
 ## 解构赋值
 
-解构赋值是一种快速从Lua表中按名称或基于数组中的位置提取值的方法。
+解构赋值是一种快速从 Lua 表中按名称或基于数组中的位置提取值的方法。
 
-通常当你看到一个字面量的Lua表，比如{1,2,3}，它位于赋值的右侧，因为它是一个值。解构赋值语句的写法就是交换了字面量Lua表的角色，并将其放在赋值语句的左侧。
+通常当你看到一个字面量的 Lua 表，比如 `{1,2,3}`，它位于赋值的右侧，因为它是一个值。解构赋值语句的写法就是交换了字面量 Lua 表的角色，并将其放在赋值语句的左侧。
 
 最好是通过示例来解释。以下是如何从表格中解包前两个值的方法：
 
@@ -1201,7 +1379,7 @@ print first, second, color
 </pre>
 </YueDisplay>
 
-有时候我们会需要从Lua表中提取值并将它们赋给与键同名的局部变量。为了避免编写重复代码，我们可以使用 **:** 前缀操作符：
+有时候我们会需要从 Lua 表中提取值并将它们赋给与键同名的局部变量。为了避免编写重复代码，我们可以使用 **:** 前缀操作符：
 
 ```moonscript
 {:concat, :insert} = table
@@ -1223,7 +1401,7 @@ print first, second, color
 </pre>
 </YueDisplay>
 
-在进行解构时，您可以指定默认值，如：
+在进行解构时，你可以指定默认值，如：
 
 ```moonscript
 {:name = "nameless", :job = "jobless"} = person
@@ -1234,7 +1412,7 @@ print first, second, color
 </pre>
 </YueDisplay>
 
-在进行列表解构时，您可以使用`_`作为占位符：
+在进行列表解构时，你可以使用`_`作为占位符：
 
 ```moonscript
 [_, two, _, four] = items
@@ -1245,9 +1423,55 @@ print first, second, color
 </pre>
 </YueDisplay>
 
-### 在其�����方的解构
+### �����解构
 
-解构也可以出现在其它隐式进行赋值的地方。一个例子是用在for循环：
+你可以使用展开运算符 `...` 在列表解构中来捕获一个范围的值到子列表中。这在当你想要从列表的开头和结尾提取特定元素，同时收集中间的元素时非常有用。
+
+```moonscript
+orders = ["first", "second", "third", "fourth", "last"]
+[first, ...bulk, last] = orders
+print first  -- 打印: first
+print bulk   -- 打印: {"second", "third", "fourth"}
+print last   -- 打印: last
+```
+<YueDisplay>
+<pre>
+orders = ["first", "second", "third", "fourth", "last"]
+[first, ...bulk, last] = orders
+print first  -- 打印: first
+print bulk   -- 打印: {"second", "third", "fourth"}
+print last   -- 打印: last
+</pre>
+</YueDisplay>
+
+展开运算符可以用在不同的位置来捕获不同的范围，并且你可以使用 `_` 作为占位符来表示你想跳过对应范围的捕获：
+
+```moonscript
+-- 捕获第一个元素之后的所有元素
+[first, ...rest] = orders
+
+-- 捕获最后一个元素之前的所有元素
+[...start, last] = orders
+
+-- 跳过中间的元素，只捕获第一个和最后一个元素
+[first, ..._, last] = orders
+```
+<YueDisplay>
+<pre>
+-- 捕获第一个元素之后的所有元素
+[first, ...rest] = orders
+
+-- 捕获最后一个元素之前的所有元素
+[...start, last] = orders
+
+-- 跳过中间的元素，只捕获第一个和最后一个元素
+[first, ..._, last] = orders
+</pre>
+</YueDisplay>
+
+### 在其它地方的解构赋值
+
+解构赋值也可以出现在其它隐式进行赋值的地方。一个例子是用在 for 循环中：
 
 ```moonscript
 tuples = [
@@ -1270,7 +1494,7 @@ for [left, right] in *tuples
 </pre>
 </YueDisplay>
 
-我们知道数组表中的每个元素都是一个两项的元组，所以我们可以直接在for语句的名称子句中使用解构来解包它。
+我们知道数组表中的每个元素都是一个两项的元组，所以我们可以直接在 for 语句的名称子句中使用解构来解包它。
 
 ## If 赋值
 
@@ -1322,7 +1546,7 @@ print "好的"
 
 ### While 赋值
 
-您可以在 while 循环中同样使用赋值来获取循环条件的值。
+你可以在 while 循环中同样使用赋值来获取循环条件的值。
 ```moonscript
 while byte := stream\read_one!
   -- 对 byte 做一些操作
@@ -1338,7 +1562,7 @@ while byte := stream\read_one!
 
 ## 可变参数赋值
 
-您可以将函数返回的结果赋值给一个可变参数符号 `...`。然后使用Lua的方式访问其内容。
+你可以将函数返回的结果赋值给一个可变参数符号 `...`。然后使用 Lua 的方式访问其内容。
 ```moonscript
 list = [1, 2, 3, 4, 5]
 fn = (ok) -> ok, table.unpack list
@@ -1360,7 +1584,20 @@ print ok, count, first
 
 ## 空白
 
-月之脚本是一个对空白敏感的语言。您必须在相同的缩进中使用空格 **' '** 或制表符 **'\t'** 来编写一些代码块，如函数体、值列表和一些控制块。包含不同空白的表达式可能意味着不同的事情。制表符被视为4个空格，但最好不要混合使用空格和制表符。
+月之脚本是一个对空白敏感的语言。你必须在相同的缩进中使用空格 **' '** 或制表符 **'\t'** 来编写一些代码块，如函数体、值列表和一些控制块。包含不同空白的表达式可能意味着不同的事情。制表符被视为4个空格，但最好不要混合使用空格和制表符。
+
+### 语句分隔符
+
+一条语句通常以换行结束。你也可以使用分号 `;` 显式结束一条语句，从而在同一行中编写多条语句：
+
+```moonscript
+a = 1; b = 2; print a + b
+```
+<YueDisplay>
+<pre>
+a = 1; b = 2; print a + b
+</pre>
+</YueDisplay>
 
 ### 多行链式调用
 
@@ -1415,7 +1652,7 @@ func --[[端口]] 3000, --[[ip]] "192.168.1.1"
 
 ## 错误处理
 
-用于统一进行Lua错误处理的便捷语法。
+用于统一进行 Lua 错误处理的便捷语法。
 
 ```moonscript
 try
@@ -1474,9 +1711,50 @@ catch err
 </pre>
 </YueDisplay>
 
+### 错误处理简化
+
+`try?` 是 `try` 的功能简化语法，它不再返回 `try` 语句的布尔状态，并在成功时直接返回 `try` 代码块的结果，失败时返回 `nil` 值而非错误对象。
+
+```moonscript
+a, b, c = try? func!
+
+-- 与空值合并运算符一起使用
+a = (try? func!) ?? "default"
+
+-- 作为函数参数
+f try? func!
+
+-- 带 catch 块的 try!
+f try?
+  print 123
+  func!
+catch e
+  print e
+  e
+```
+<YueDisplay>
+<pre>
+a, b, c = try? func!
+
+-- 与空值合并运算符一起使用
+a = (try? func!) ?? "default"
+
+-- 作为函数参数
+f try? func!
+
+-- 带 catch 块的 try!
+f try?
+  print 123
+  func!
+catch e
+  print e
+  e
+</pre>
+</YueDisplay>
+
 ## 属性
 
-月之脚本现在提供了Lua 5.4新增的叫做属性的语法支持。在月之脚本编译到的Lua目标版本低于5.4时，你仍然可以同时使用`const`和`close`的属性声明语法，并获得常量检查和作用域回调的功能。
+月之脚本现在提供了 Lua 5.4 新增的叫做属性的语法支持。在月之脚本编译到的 Lua 目标版本低于 5.4 时，你仍然可以同时使用`const` 和 `close` 的属性声明语法，并获得常量检查和作用域回调的功能。
 
 ```moonscript
 const a = 123
@@ -1502,11 +1780,24 @@ const {:a, :b, c, d} = tb
 </pre>
 </YueDisplay>
 
+你也可以声明全局变量为常量。
+
+```moonscript
+global const Constant = 123
+-- Constant = 1
+```
+<YueDisplay>
+<pre>
+global const Constant = 123
+-- Constant = 1
+</pre>
+</YueDisplay>
+
 ## 字面量
 
-Lua中的所有基本字面量都可以在月之脚本中使用。包括数字、字符串、布尔值和**nil**。
+Lua 中的所有基本字面量都可以在月之脚本中使用。包括数字、字符串、布尔值和 **nil**。
 
-但与Lua不同的是，单引号和双引号字符串内部允许有换行：
+但与 Lua 不同的是，单引号和双引号字符串内部允许有换行：
 
 ```moonscript
 some_string = "这是一个字符串
@@ -1529,17 +1820,78 @@ print "我有#{math.random! * 100}%的把握。"
 
 ### 数字字面量
 
-您可以在数字字面量中使用下划线来增加可读性。
+你可以在数字字面量中使用下划线来增加可读性。
 
 ```moonscript
 integer = 1_000_000
 hex = 0xEF_BB_BF
+binary = 0B10011
 ```
 <YueDisplay>
 
 <pre>
 integer = 1_000_000
 hex = 0xEF_BB_BF
+binary = 0B10011
+</pre>
+</YueDisplay>
+
+### YAML 风格字符串
+
+使用 `|` 前缀标记一个多行 YAML 风格字符串：
+
+```moonscript
+str = |
+  key: value
+  list:
+    - item1
+    - #{expr}
+```
+<YueDisplay>
+<pre>
+str = |
+  key: value
+  list:
+    - item1
+    - #{expr}
+</pre>
+</YueDisplay>
+
+其效果类似于原生 Lua 的多行拼接，所有文本（含换行）将被保留下来，并支持 `#{...}` 语法，通过 `tostring(expr)` 插入表达式结果。
+
+YAML 风格的多行字符串会自动检测首行后最小的公共缩进，并从所有行中删除该前缀空白字符。这让你可以在代码中对齐文本，但输出字符串不会带多余缩进。
+
+```moonscript
+fn = ->
+  str = |
+    foo:
+      bar: baz
+  return str
+```
+<YueDisplay>
+<pre>
+fn = ->
+  str = |
+    foo:
+      bar: baz
+  return str
+</pre>
+</YueDisplay>
+
+输出字符串中的 foo: 对齐到行首，不会带有函数缩进空格。保留内部缩进的相对结构，适合书写结构化嵌套样式的内容。
+
+支持自动处理字符中的引号、反斜杠等特殊符号，无需手动转义：
+
+```moonscript
+str = |
+  path: "C:\Program Files\App"
+  note: 'He said: "#{Hello}!"'
+```
+<YueDisplay>
+<pre>
+str = |
+  path: "C:\Program Files\App"
+  note: 'He said: "#{Hello}!"'
 </pre>
 </YueDisplay>
 
@@ -1644,7 +1996,7 @@ print "数字的和是", sum 10, 20
 </pre>
 </YueDisplay>
 
-如果您需要做显式返回，可以使用return关键字：
+如果你需要做显式返回，可以使用 return 关键字：
 
 ```moonscript
 sum = (x, y) -> return x + y
@@ -1670,7 +2022,7 @@ a, b = mystery 10, 20
 
 ### 粗箭头
 
-因为在Lua中调用方法时，经常习惯将对象作为第一个参数传入，所以月之脚本提供了一种特殊的语法来创建自动包含self参数的函数。
+因为在 Lua 中调用方法时，经常习惯将对象作为第一个参数传入，所以月之脚本提供了一种特殊的语法来创建自动包含 self 参数的函数。
 
 ```moonscript
 func = (num) => @value + num
@@ -1683,7 +2035,7 @@ func = (num) => @value + num
 
 ### 参数默认值
 
-可以为函数的参数提供默认值。如果参数的值为nil，则确定该参数为空。任何具有默认值的nil参数在函数体运行之前都会被替换。
+可以为函数的参数提供默认值。如果参数的值为 nil，则确定该参数为空。任何具有默认值的 nil 参数在函数体运行之前都会被替换。
 
 ```moonscript
 my_function = (name = "某物", height = 100) ->
@@ -1755,7 +2107,7 @@ my_func 5, 6, 7,
 </pre>
 </YueDisplay>
 
-因为Lua表也使用逗号作为分隔符，这种缩进语法有助于让值成为参数列表的一部分，而不是Lua表的一部分。
+因为 Lua 表也使用逗号作为分隔符，这种缩进语法有助于让值成为参数列表的一部分，而不是 Lua 表的一部分。
 
 ```moonscript
 x = [
@@ -1822,6 +2174,138 @@ if func 1, 2, 3,
 </pre>
 </YueDisplay>
 
+### 参数解构
+
+月之脚本支持在函数形参位置对传入对象进行解构。适用两类解构表子面量：
+
+- 使用 {} 包裹的字面量/对象形参，支持提供获得空字段时的默认值（例如 {:a, :b}、{a: a1 = 123}）。
+
+- 无 {} 包裹、以键值/简写键序列开头，直至遇到其它表达式终止（例如 :a, b: b1, :c），表示从同一个对象中解构多个字段。
+
+```moonscript
+f1 = (:a, :b, :c) ->
+  print a, b, c
+
+f1 a: 1, b: "2", c: {}
+
+f2 = ({a: a1 = 123, :b = 'abc'}, c = {}) ->
+  print a1, b, c
+
+arg1 = {a: 0}
+f2 arg1, arg2
+```
+<YueDisplay>
+<pre>
+f1 = (:a, :b, :c) ->
+  print a, b, c
+
+f1 a: 1, b: "2", c: {}
+
+f2 = ({a: a1 = 123, :b = 'abc'}, c = {}) ->
+  print a1, b, c
+
+arg1 = {a: 0}
+f2 arg1, arg2
+</pre>
+</YueDisplay>
+
+### 前置返回表达式
+
+在深度嵌套的函数体中，为了提升返回值的可读性及编写便利性，我们新增了 “前置返回表达式” 语法。其形式如下：
+
+```moon
+findFirstEven = (list): nil ->
+  for item in *list
+    if type(item) == "table"
+      for sub in *item
+        if sub % 2 == 0
+          return sub
+```
+<YueDisplay>
+<pre>
+findFirstEven = (list): nil ->
+  for item in *list
+    if type(item) == "table"
+      for sub in *item
+        if sub % 2 == 0
+          return sub
+</pre>
+</YueDisplay>
+
+这个写法等价于：
+
+```moon
+findFirstEven = (list) ->
+  for item in *list
+    if type(item) == "table"
+      for sub in *item
+        if sub % 2 == 0
+          return sub
+  nil
+```
+<YueDisplay>
+<pre>
+findFirstEven = (list) ->
+  for item in *list
+    if type(item) == "table"
+      for sub in *item
+        if sub % 2 == 0
+          return sub
+  nil
+</pre>
+</YueDisplay>
+
+唯一的区别在于：你可以将函数的返回值表达式提前写在 `->` 或 `=>` 前，用以指示该函数应隐式返回该表达式的值。这样即使在多层循环或条件判断的场景下，也无需编写尾行悬挂的返回表达式，逻辑结构会更加直观清晰。
+
+### 命名变长参数
+
+你可以使用 `(...t) ->` 语法来将变长参数自动存储到一个命名表中。这个表会包含所有传入的参数（包括 `nil` 值），并且会在表的 `n` 字段中存储实际传入的参数个数（包括 `nil` 值在内的个数）。
+
+```moonscript
+f = (...t) ->
+  print "参数个数:", t.n
+  print "表长度:", #t
+  for i = 1, t.n
+    print t[i]
+
+f 1, 2, 3
+f "a", "b", "c", "d"
+f!
+
+-- 处理包含 nil 的情况
+process = (...args) ->
+  sum = 0
+  for i = 1, args.n
+    if args[i] != nil and type(args[i]) == "number"
+      sum += args[i]
+  sum
+
+process 1, nil, 3, nil, 5
+```
+<YueDisplay>
+<pre>
+f = (...t) ->
+  print "参数个数:", t.n
+  print "表长度:", #t
+  for i = 1, t.n
+    print t[i]
+
+f 1, 2, 3
+f "a", "b", "c", "d"
+f!
+
+-- 处理包含 nil 的情况
+process = (...args) ->
+  sum = 0
+  for i = 1, args.n
+    if args[i] != nil and type(args[i]) == "number"
+      sum += args[i]
+  sum
+
+process 1, nil, 3, nil, 5
+</pre>
+</YueDisplay>
+
 ## 反向回调
 
 反向回调用于减少函数回调的嵌套。它们使用指向左侧的箭头，并且默认会被定义为传入后续函数调用的最后一个参数。它的语法大部分与常规箭头函数相同，只是它指向另一方向，并且后续的函数体不需要进行缩进。
@@ -1850,7 +2334,7 @@ print @value
 </pre>
 </YueDisplay>
 
-您可以通过一个占位符指定回调函数的传参位置。
+你可以通过一个占位符指定回调函数的传参位置。
 
 ```moonscript
 (x) <- map _, [1, 2, 3]
@@ -1863,22 +2347,22 @@ x * 2
 </pre>
 </YueDisplay>
 
-如果您希望在反向回调处理后继续编写更多其它的代码，您可以使用do语句将不归属反向回调的代码分开。
+如果你希望在反向回调处理后继续编写更多其它的代码，可以使用 do 语句将不属于反向回调的代码分隔开。对于非粗箭头函数的反向回调，回调返回值的括号也是可以省略的。
 
 ```moonscript
 result, msg = do
-  (data) <- readAsync "文件名.txt"
+  data <- readAsync "文件名.txt"
   print data
-  (info) <- processAsync data
+  info <- processAsync data
   check info
 print result, msg
 ```
 <YueDisplay>
 <pre>
 result, msg = do
-  (data) <- readAsync "文件名.txt"
+  data <- readAsync "文件名.txt"
   print data
-  (info) <- processAsync data
+  info <- processAsync data
   check info
 print result, msg
 </pre>
@@ -1886,7 +2370,7 @@ print result, msg
 
 ## 表格字面量
 
-和Lua一样，表格可以通过花括号进行定义。
+和 Lua 一样，表格可以通过花括号进行定义。
 
 ```moonscript
 some_values = [1, 2, 3, 4]
@@ -1969,7 +2453,7 @@ y = type: "狗", legs: 4, tails: 1
 </pre>
 </YueDisplay>
 
-表格字面量的键可以使用Lua语言的关键字，而无需转义：
+表格字面量的键可以使用 Lua 语言的关键字，而无需转义：
 
 ```moonscript
 tbl = {
@@ -2005,7 +2489,7 @@ print_table :hair, :height
 </pre>
 </YueDisplay>
 
-如果你希望表中字段的键是某个表达式的结果，那么可以用 **[ ]** 包裹它，就像在Lua中一样。如果键中有任何特殊字符，也可以直接使用字符串字面量作为键，省略方括号。
+如果你希望表中字段的键是某个表达式的结果，那么可以用 **[ ]** 包裹它，就像在 Lua 中一样。如果键中有任何特殊字符，也可以直接使用字符串字面量作为键，省略方括号。
 
 ```moonscript
 t = {
@@ -2022,7 +2506,7 @@ t = {
 </pre>
 </YueDisplay>
 
-Lua的表同时具有数组部分和哈希部分，但有时候你会希望在书写Lua表时，对Lua表做数组和哈希不同用法的语义区分。然后你可以用 **[ ]** 而不是 **{ }** 来编写表示数组的 Lua 表，并且不允许在数组 Lua 表中写入任何键值对。
+Lua 的表同时具有数组部分和哈希部分，但有时候你会希望在书写 Lua 表时，对 Lua 表做数组和哈希不同用法的语义区分。然后你可以用 **[ ]** 而不是 **{ }** 来编写表示数组的 Lua 表，并且不允许在数组 Lua 表中写入任何键值对。
 
 ```moonscript
 some_values = [ 1, 2, 3, 4 ]
@@ -2037,11 +2521,11 @@ list_with_one_element = [ 1, ]
 
 ## 推导式
 
-推导式为我们提供了一种便捷的语法，通过遍历现有对象并对其值应用表达式来构造出新的表格。月之脚本有两种推导式：列表推导式和表格推导式。它们最终都是产生Lua表格；列表推导式将值累积到类似数组的表格中，而表格推导式允许您在每次遍历时设置新表格的键和值。
+推导式为我们提供了一种便捷的语法，通过遍历现有对象并对其值应用表达式来构造出新的表格。月之脚本有两种推导式：列表推导式和表格推导式。它们最终都是产生 Lua 表格；列表推导式将值累积到类似数组的表格中，而表格推导式允许你在每次遍历时设置新表格的键和值。
 
 ### 列表推导式
 
-以下操作创建了一个items表的副本，但所有包含的值都翻倍了。
+以下操作创建了一个 items 表的副本，但所有包含的值都翻倍了。
 
 ```moonscript
 items = [1, 2, 3, 4]
@@ -2054,7 +2538,7 @@ doubled = [item * 2 for i, item in ipairs items]
 </pre>
 </YueDisplay>
 
-可以使用when子句筛选新表中包含的项目：
+可以使用 `when` 子句筛选新表中包含的项目：
 
 ```moonscript
 slice = [item for i, item in ipairs items when i > 1 and i < 3]
@@ -2065,7 +2549,7 @@ slice = [item for i, item in ipairs items when i > 1 and i < 3]
 </pre>
 </YueDisplay>
 
-因为我们常常需要迭代数值索引表的值，所以引入了 **\*** 操作符来做语法简化。doubled示例可以重写为：
+因为我们常常需要迭代数值索引表的值，所以引入了 **\*** 操作符来做语法简化。doubled 示例可以重写为：
 
 ```moonscript
 doubled = [item * 2 for item in *items]
@@ -2076,9 +2560,30 @@ doubled = [item * 2 for item in *items]
 </pre>
 </YueDisplay>
 
-for和when子句可以根据需要进行链式操作。唯一的要求是推导式中至少要有一个for子句。
+在列表推导式中，你还可以使用展开操作符 `...` 来实现对列表嵌套层级进行扁平化的处理：
+
+```moonscript
+data =
+  a: [1, 2, 3]
+  b: [4, 5, 6]
+
+flat = [...v for k,v in pairs data]
+-- flat 现在为 [1, 2, 3, 4, 5, 6]
+```
+<YueDisplay>
+<pre>
+data =
+  a: [1, 2, 3]
+  b: [4, 5, 6]
+
+flat = [...v for k,v in pairs data]
+-- flat 现在为 [1, 2, 3, 4, 5, 6]
+</pre>
+</YueDisplay>
+
+for 和 when 子句可以根据需要进行链式操作。唯一的要求是推导式中至少要有一个 for 子句。
 
-使用多个for子句与使用多重循环的效果相同：
+使用多个 for 子句与使用多重循环的效果相同：
 
 ```moonscript
 x_coords = [4, 5, 6, 7]
@@ -2097,7 +2602,7 @@ for y in *y_coords]
 </pre>
 </YueDisplay>
 
-在推导式中也可以使用简单的数值for循环：
+在推导式中也可以使用简单的数值 for 循环：
 
 ```moonscript
 evens = [i for i = 1, 100 when i % 2 == 0]
@@ -2112,7 +2617,7 @@ evens = [i for i = 1, 100 when i % 2 == 0]
 
 表格推导式和列表推导式的语法非常相似，只是要使用 **{** 和 **}** 并从每次迭代中取两个值。
 
-以下示例生成了表格thing的副本：
+以下示例生成了表格 thing 的副本：
 
 ```moonscript
 thing = {
@@ -2174,9 +2679,9 @@ tbl = {unpack tuple for tuple in *tuples}
 
 ### 切片
 
-当使用 **\*** 操作符时，月之脚本还提供了一种特殊的语法来限制要遍历的列表范围。这个语法也相当于在for循环中设置迭代边界和步长。
+当使用 **\*** 操作符时，月之脚本还提供了一种特殊的语法来限制要遍历的列表范围。这个语法也相当于在 for 循环中设置迭代边界和步长。
 
-下面的案例中，我们在切片中设置最小和最大边界，取索引在1到5之间（包括1和5）的所有项目：
+下面的案例中，我们在切片中设置最小和最大边界，取索引在 1 到 5 之间（包括 1 和 5）的所有项目：
 
 ```moonscript
 slice = [item for item in *items[1, 5]]
@@ -2198,7 +2703,7 @@ slice = [item for item in *items[2,]]
 </pre>
 </YueDisplay>
 
-如果省略了最小边界，便默认会设置为1。这里我们只提供一个步长，并留下其他边界为空。这样会使得代码取出所有奇数索引的项目：(1, 3, 5, …)
+如果省略了最小边界，便默认会设置为 1。这里我们只提供一个步长，并留下其他边界为空。这样会使得代码取出所有奇数索引的项目：(1, 3, 5, …)
 
 ```moonscript
 slice = [item for item in *items[,,2]]
@@ -2210,9 +2715,48 @@ slice = [item for item in *items[,,2]]
 </pre>
 </YueDisplay>
 
+最小和最大边界都可以是负数，使用负数意味着边界是从表的末尾开始计算的。
+
+```moonscript
+-- 取最后4个元素
+slice = [item for item in *items[-4,-1]]
+```
+<YueDisplay>
+<pre>
+-- 取最后4个元素
+slice = [item for item in *items[-4,-1]]
+</pre>
+</YueDisplay>
+
+切片的步长也可以是负数，这意味着元素会以相反的顺序被取出。
+
+```moonscript
+reverse_slice = [item for item in *items[-1,1,-1]]
+```
+<YueDisplay>
+<pre>
+reverse_slice = [item for item in *items[-1,1,-1]]
+</pre>
+</YueDisplay>
+
+#### 切片表达式
+
+切片也可以作为表达式来使用。可以用于获取一个表包含的子列表。
+
+```moonscript
+-- 取第2和第4个元素作为新的列表
+sub_list = items[2, 4]
+```
+<YueDisplay>
+<pre>
+-- 取第2和第4个元素作为新的列表
+sub_list = items[2, 4]
+</pre>
+</YueDisplay>
+
 ## for 循环
 
-Lua中有两种for循环形式，数字型和通用型：
+Lua 中有两种 for 循环形式，数字型和通用型：
 
 ```moonscript
 for i = 10, 20
@@ -2265,7 +2809,7 @@ for j = 1, 10, 3 do print j
 </pre>
 </YueDisplay>
 
-for循环也可以用作表达式。for循环主体中的最后一条语句会被强制转换为一个返回值的表达式，并会将表达式计算结果的值追加到一个作为结果的数组表中。
+for 循环也可以用作表达式。for 循环主体中的最后一条语句会被强制转换为一个返回值的表达式，并会将表达式计算结果的值追加到一个作为结果的数组表中。
 
 将每个偶数加倍：
 
@@ -2286,9 +2830,24 @@ doubled_evens = for i = 1, 20
 </pre>
 </YueDisplay>
 
-您还可以结合for循环表达式与continue语句来过滤值。
+此外，for 循环还支持带返回值的 break 语句，这样循环本身就可以作为一个表达式，在满足条件时提前退出并返回有意义的结果。
+
+例如，查找第一个大于 10 的数字：
+
+```moonscript
+first_large = for n in *numbers
+  break n if n > 10
+```
+<YueDisplay>
+<pre>
+first_large = for n in *numbers
+  break n if n > 10
+</pre>
+</YueDisplay>
+
+你还可以结合 for 循环表达式与 continue 语句来过滤值。
 
-注意出现在函数体末尾的for循环，不会被当作是一个表达式，并将循环结果累积到一个列表中作为返回值（相反，函数将返回nil）。如果要函数末尾的循环转换为列表表达式，可以使用返回语句加for循环表达式。
+注意出现在函数体末尾的 for 循环，不会被当作是一个表达式并将循环结果累积到一个列表中作为返回值（相反，函数将返回 nil）。如果要函数末尾的循环转换为列表表达式，可以显式地使用返回语句加 for 循环表达式。
 
 ```moonscript
 func_a = -> for i = 1, 10 do print i
@@ -2311,7 +2870,7 @@ print func_b! -- 打印 table 对象
 
 ## repeat 循环
 
-repeat循环是从Lua语言中搬过来的相似语法：
+repeat 循环是从 Lua 语言中搬过来的相似语法：
 
 ```moonscript
 i = 10
@@ -2332,7 +2891,7 @@ until i == 0
 
 ## while 循环
 
-在月之脚本中的while循环有四种写法：
+在月之脚本中的 while 循环有四种写法：
 
 ```moonscript
 i = 10
@@ -2371,7 +2930,7 @@ until running == false do my_function!
 </pre>
 </YueDisplay>
 
-像for循环的语法一样，while循环也可以作为一个表达式使用。为了使函数返回while循环的累积列表值，必须明确使用返回语句返回while循环表达式。
+像 for 循环的语法一样，while 循环也可以作为一个表达式使用。为了使函数返回 while 循环的累积列表值，必须明确使用返回语句返回 while 循环表达式。
 
 ## 继续
 
@@ -2489,13 +3048,14 @@ print message -- 打印: 我很高
 </pre>
 </YueDisplay>
 
-if的反义词是unless（相当于if not，如果 vs 除非）：
+if 的反义词是 unless（相当于 if not，正如“如果”对应“除非”）：
 
 ```moonscript
 unless os.date("%A") == "Monday"
   print "今天不是星期一！"
 ```
 <YueDisplay>
+
 <pre>
 unless os.date("%A") == "Monday"
   print "今天不是星期一！"
@@ -2513,7 +3073,7 @@ print "你真幸运！" unless math.random! > 0.1
 
 ### 范围表达式
 
-您可以使用范围表达式来编写进行范围检查的代码。
+你可以使用范围表达式来编写进行范围检查的代码。
 
 ```moonscript
 a = 5
@@ -2547,7 +3107,7 @@ print "你很幸运!" unless math.random! > 0.1
 
 ## 代码行修饰符
 
-为了方便编写代码，循环语句和if语句可以应用于单行代码语句的末尾：
+为了方便编写代码，循环语句和 if 语句可以应用于单行代码语句的末尾：
 
 ```moonscript
 print "你好，世界" if name == "Rob"
@@ -2558,7 +3118,7 @@ print "你好，世界" if name == "Rob"
 </pre>
 </YueDisplay>
 
-修饰for循环的示例：
+修饰 for 循环的示例：
 
 ```moonscript
 print "项目: ", item for item in *items
@@ -2569,7 +3129,7 @@ print "项目: ", item for item in *items
 </pre>
 </YueDisplay>
 
-修饰while循环的示例：
+修饰 while 循环的示例：
 
 ```moonscript
 game\update! while game\isRunning!
@@ -2586,34 +3146,32 @@ reader\parse_line! until reader\eof!
 
 ## switch 语句
 
-switch语句是为了简化检查一系列相同值的if语句而提供的简写语法。要注意用于比较检查的目标值只会计算一次。和if语句一样，switch语句在最后可以接一个else代码块来处理没有匹配的情况。在生成的Lua代码中，进行比较是使用==操作符完成的。
+switch 语句是为了简化检查一系列相同值的if语句而提供的简写语法。要注意用于比较检查的目标值只会计算一次。和 if 语句一样，switch 语句在最后可以接一个 else 代码块来处理没有匹配的情况。在生成的 Lua 代码中，进行比较是使用 == 操作符完成的。switch 语句中也可以使用赋值表达式来储存临时变量值。
 
 ```moonscript
-name = "Dan"
-switch name
+switch name := "Dan"
   when "Robert"
     print "你是Robert"
   when "Dan", "Daniel"
     print "你的名字是Dan"
   else
-    print "我不知道你的名字"
+    print "我不认识你，你的名字是#{name}"
 ```
 <YueDisplay>
 <pre>
-name = "Dan"
-switch name
+switch name := "Dan"
   when "Robert"
     print "你是Robert"
   when "Dan", "Daniel"
     print "你的名字是Dan"
   else
-    print "我不知道你的名字"
+    print "我不认识你，你的名字是#{name}"
 </pre>
 </YueDisplay>
 
-switch语句的when子句中可以通过使用逗号分隔的列表来匹配多个值。
+switch 语句的 when 子句中可以通过使用逗号分隔的列表来匹配多个值。
 
-switch语句也可以作为表达式使用，下面我们可以将switch语句返回的结果分配给一个变量：
+switch 语句也可以作为表达式使用，下面我们可以将 switch 语句返回的结果分配给一个变量：
 
 ```moonscript
 b = 1
@@ -2638,7 +3196,7 @@ next_number = switch b
 </pre>
 </YueDisplay>
 
-我们可以使用then关键字在when子句的同一行上编写处理代码。else代码块的后续代码中要写在同一行上不需要额外的关键字。
+我们可以使用 then 关键字在 when 子句的同一行上编写处理代码。else 代码块的后续代码中要写在同一行上不需要额外的关键字。
 
 ```moonscript
 msg = switch math.random(1, 5)
@@ -2655,7 +3213,7 @@ msg = switch math.random(1, 5)
 </pre>
 </YueDisplay>
 
-如果在编写switch语句时希望少写一个缩进，那么你可以把第一个when子句放在switch开始语句的第一行，然后后续的子语句就都可以都少写一个缩进。
+如果在编写 switch 语句时希望少写一个缩进，那么你可以把第一个 when 子句放在 switch 开始语句的第一行，然后后续的子语句就都可以都少写一个缩进。
 
 ```moonscript
 switch math.random(1, 5)
@@ -2684,11 +3242,11 @@ else
 </pre>
 </YueDisplay>
 
-值得注意的是，在生成Lua代码时，我们要做检查的目标变量会放在==表达式的右侧。当您希望给when子句的比较对象定义一个\_\_eq元方法来重载判断逻辑时，可能会有用。
+值得注意的是，在生成 Lua 代码时，我们要做检查的目标变量会放在 == 表达式的右侧。当你希望给 when 子句的比较对象定义一个 \_\_eq 元方法来重载判断逻辑时，可能会有用。
 
 ### 表格匹配
 
-在switch的when子句中，如果期待检查目标是一个表格，且可以通过特定的结构进行解构并获得非nil值，那么你可以尝试使用表格匹配的语法。
+在 switch 的 when 子句中，如果期待检查目标是一个表格，且可以通过特定的结构进行解构并获得非 nil 值，那么你可以尝试使用表格匹配的语法。
 
 ```moonscript
 items =
@@ -2744,9 +3302,126 @@ switch item
 </pre>
 </YueDisplay>
 
+你也可以匹配数组元素、表格字段，甚至使用数组或表格字面量来匹配嵌套的结构。
+
+匹配数组元素。
+
+```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}"
+```
+<YueDisplay>
+<pre>
+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}"
+</pre>
+</YueDisplay>
+
+匹配表格字段。
+
+```moonscript
+switch tb
+  when success: true, :result
+    print "成功", result
+  when success: false
+    print "失败", result
+  else
+    print "无效值"
+```
+<YueDisplay>
+<pre>
+switch tb
+  when success: true, :result
+    print "成功", result
+  when success: false
+    print "失败", result
+  else
+    print "无效值"
+</pre>
+</YueDisplay>
+
+匹配嵌套的表格结构。
+
+```moonscript
+switch tb
+  when data: {type: "success", :content}
+    print "成功", content
+  when data: {type: "error", :content}
+    print "失败", content
+  else
+    print "无效值"
+```
+<YueDisplay>
+<pre>
+switch tb
+  when data: {type: "success", :content}
+    print "成功", content
+  when data: {type: "error", :content}
+    print "失败", content
+  else
+    print "无效值"
+</pre>
+</YueDisplay>
+
+匹配表格数组。
+
+```moonscript
+switch tb
+  when [
+      {a: 1, b: 2}
+      {a: 3, b: 4}
+      {a: 5, b: 6}
+      fourth
+    ]
+    print "匹配成功", fourth
+```
+<YueDisplay>
+<pre>
+switch tb
+  when [
+      {a: 1, b: 2}
+      {a: 3, b: 4}
+      {a: 5, b: 6}
+      fourth
+    ]
+    print "匹配成功", fourth
+</pre>
+</YueDisplay>
+
+匹配一个列表并捕获特定范围内的元素。
+
+```moonscript
+segments = ["admin", "users", "logs", "view"]
+switch segments
+  when [...groups, resource, action]
+    print "Group:", groups -- 打印: {"admin", "users"}
+    print "Resource:", resource -- 打印: "logs"
+    print "Action:", action -- 打印: "view"
+```
+<YueDisplay>
+<pre>
+segments = ["admin", "users", "logs", "view"]
+switch segments
+  when [...groups, resource, action]
+    print "Group:", groups -- 打印: {"admin", "users"}
+    print "Resource:", resource -- 打印: "logs"
+    print "Action:", action -- 打印: "view"
+</pre>
+</YueDisplay>
+
 ## 面向对象编程
 
-在以下的示例中，月之脚本生成的Lua代码可能看起来会很复杂。所以最好主要关注月之脚本代码层面的意义，然后如果您想知道关于面向对象功能的实现细节，再查看Lua代码。
+在以下的示例中，月之脚本生成的 Lua 代码可能看起来会很复杂。所以最好主要关注月之脚本代码层面的意义，然后如果你想知道关于面向对象功能的实现细节，再查看 Lua 代码。
 
 一个简单的类：
 
@@ -2775,11 +3450,11 @@ class Inventory
 </pre>
 </YueDisplay>
 
-在月之脚本中采用面向对象的编程方式时，通常会使用类声明语句结合Lua表格字面量来做类定义。这个类的定义包含了它的所有方法和属性。在这种结构中，键名为“new”的成员扮演了一个重要的角色，是作为构造函数来使用。
+在月之脚本中采用面向对象的编程方式时，通常会使用类声明语句结合 Lua 表格字面量来做类定义。这个类的定义包含了它的所有方法和属性。在这种结构中，键名为 “new” 的成员扮演了一个重要的角色，是作为构造函数来使用。
 
-值得注意的是，类中的方法都采用了粗箭头函数语法。当在类的实例上调用方法时，该实例会自动作为第一个参数被传入，因此粗箭头函数用于生成一个名为“self”的参数。
+值得注意的是，类中的方法都采用了粗箭头函数语法。当在类的实例上调用方法时，该实例会自动作为第一个参数被传入，因此粗箭头函数用于生成一个名为 “self” 的参数。
 
-此外，“@”前缀在变量名上起到了简化作用，代表“self”。例如，`@items` 就等同于 `self.items`。
+此外，“@” 前缀在变量名上起到了简化作用，代表 “self”。例如，`@items` 就等同于 `self.items`。
 
 为了创建类的一个新实例，可以将类名当作一个函数来调用，这样就可以生成并返回一个新的实例。
 
@@ -2801,7 +3476,7 @@ inv\add_item "pants"
 
 需要特别注意的是，类的所有属性在其实例之间是共享的。这对于函数类型的成员属性通常不会造成问题，但对于其他类型的属性，可能会导致意外的结果。
 
-例如，在下面的示例中，clothes属性在所有实例之间共享。因此，对这个属性在一个实例中的修改，将会影响到其他所有实例。
+例如，在下面的示例中，clothes 属性在所有实例之间共享。因此，对这个属性在一个实例中的修改，将会影响到其他所有实例。
 
 ```moonscript
 class Person
@@ -2853,7 +3528,7 @@ class Person
 
 ### 继承
 
-`extends`关键字可以在类声明中使用，以继承另一个类的属性和方法。
+`extends` 关键字可以在类声明中使用，以继承另一个类的属性和方法。
 
 ```moonscript
 class BackPack extends Inventory
@@ -2873,11 +3548,11 @@ class BackPack extends Inventory
 </YueDisplay>
 
 
-在这一部分，我们对月之脚本中的`Inventory`类进行了扩展，加入了对可以携带物品数量的限制。
+在这一部分，我们对月之脚本中的 `Inventory` 类进行了扩展，加入了对可以携带物品数量的限制。
 
-在这个特定的例子中，子类并没有定义自己的构造函数。因此，当创建一个新的实例时，系统会默认调用父类的构造函数。但如果我们在子类中定义了构造函数，我们可以利用`super`方法来调用并执行父类的构造函数。
+在这个特定的例子中，子类并没有定义自己的构造函数。因此，当创建一个新的实例时，系统会默认调用父类的构造函数。但如果我们在子类中定义了构造函数，我们可以利用 `super` 方法来调用并执行父类的构造函数。
 
-此外，当一个类继承自另一个类时，它会尝试调用父类上的`__inherited`方法（如果这个方法存在的话），以此来向父类发送通知。这个`__inherited`函数接受两个参数：被继承的父类和继承的子类。
+此外，当一个类继承自另一个类时，它会尝试调用父类上的 `__inherited` 方法（如果这个方法存在的话），以此来向父类发送通知。这个 `__inherited` 函数接受两个参数：被继承的父类和继承的子类。
 
 ```moonscript
 class Shelf
@@ -2900,15 +3575,15 @@ class Cupboard extends Shelf
 
 ### super 关键字
 
-`super`是一个特别的关键字，它有两种不同的使用方式：既可以当作一个对象来看待，也可以像调用函数那样使用。它仅在类的内部使用时具有特殊的功能。
+`super` 是一个特别的关键字，它有两种不同的使用方式：既可以当作一个对象来看待，也可以像调用函数那样使用。它仅在类的内部使用时具有特殊的功能。
 
-当`super`被作为一个函数调用时，它将调用父类中与之同名的函数。此时，当前的`self`会自动作为第一个参数传递，正如上面提到的继承示例所展示的那样。
+当 `super` 被作为一个函数调用时，它将调用父类中与之同名的函数。此时，当前的 `self` 会自动作为第一个参数传递，正如上面提到的继承示例所展示的那样。
 
-在将`super`当作普通值使用时，它实际上是对父类对象的引用。通过这种方式，我们可以访问父类中可能被子类覆盖的值，就像访问任何普通对象一样。
+在将 `super` 当作普通值使用时，它实际上是对父类对象的引用。通过这种方式，我们可以访问父类中可能被子类覆盖的值，就像访问任何普通对象一样。
 
-此外，当使用`\`操作符与`super`一起使用时，`self`将被插入为第一个参数，而不是使用`super`本身的值。而在使用`.`操作符来检索函数时，则会返回父类中的原始函数。
+此外，当使用 `\` 操作符与 `super` 一起使用时，`self`将被插入为第一个参数，而不是使用 `super` 本身的值。而在使用`.`操作符来检索函数时，则会返回父类中的原始函数。
 
-下面是一些使用`super`的不同方法的示例：
+下面是一些使用 `super` 的不同方法的示例：
 
 ```moonscript
 class MyClass extends ParentClass
@@ -2967,9 +3642,9 @@ print BackPack.size -- 打印 10
 
 如果在类对象的元表中找不到某个属性，系统会从基表中检索该属性。这就意味着我们可以直接从类本身访问到其方法和属性。
 
-需要特别注意的是，对类对象的赋值并不会影响到基表，因此这不是向实例添加新方法的正确方式。相反，需要直接修改基表。关于这点，可以参考下面的“__base”字段。
+需要特别注意的是，对类对象的赋值并不会影响到基表，因此这不是向实例添加新方法的正确方式。相反，需要直接修改基表。关于这点，可以参考下面的 “__base” 字段。
 
-此外，类对象包含几个特殊的属性：当类被声明时，类的名称会作为一个字符串存储在类对象的“__name”字段中。
+此外，类对象包含几个特殊的属性：当类被声明时，类的名称会作为一个字符串存储在类对象的 “__name” 字段中。
 
 ```moonscript
 print BackPack.__name -- 打印 Backpack
@@ -3051,7 +3726,7 @@ print Counter.count -- 输出 2
 
 ### 类声明语句
 
-在类声明的主体中，除了键/值对外，我们还可以编写普通的表达式。在这种类声明体中的普通代码的上下文中，self等于类对象，而不是实例对象。
+在类声明的主体中，除了键/值对外，我们还可以编写普通的表达式。在这种类声明体中的普通代码的上下文中，self 等于类对象，而不是实例对象。
 
 以下是创建类变量的另一种方法：
 
@@ -3091,9 +3766,9 @@ class MoreThings
 
 ### @ 和 @@ 值
 
-当@和@@前缀在一个名字前时，它们分别代表在self和self.\_\_class中访问的那个名字。
+当 @ 和 @@ 前缀在一个名字前时，它们分别代表在 self 和 self.\_\_class 中访问的那个名字。
 
-如果它们单独使用，它们是self和self.\_\_class的别名。
+如果它们单独使用，它们是 self 和 self.\_\_class 的别名。
 
 ```moonscript
 assert @ == self
@@ -3106,7 +3781,7 @@ assert @@ == self.__class
 </pre>
 </YueDisplay>
 
-例如，使用@@从实例方法快速创建同一类的新实例的方法：
+例如，使用 @@ 从实例方法快速创建同一类的新实例的方法：
 
 ```moonscript
 some_instance_method = (...) => @@ ...
@@ -3184,7 +3859,7 @@ x = class Bucket
 
 ### 匿名类
 
-声明类时可以省略名称。如果类的表达式不在赋值语句中，\_\_name属性将为nil。如果出现在赋值语句中，赋值操作左侧的名称将代替nil。
+声明类时可以省略名称。如果类的表达式不在赋值语句中，\_\_name 属性将为 nil。如果出现在赋值语句中，赋值操作左侧的名称将代替 nil。
 
 ```moonscript
 BigBucket = class extends Bucket
@@ -3214,7 +3889,7 @@ x = class
 
 ### 类混合
 
-您可以通过使用 `using` 关键字来实现类混合。这意味着您可以从一个普通 Lua 表格或已定义的类对象中，复制函数到您创建的新类中。当您使用普通 Lua 表格进行类混合时，您有机会用自己的实现来重写类的索引方法（例如元方法 `__index`）。然而，当您从一个类对象做混合时，需要注意的是该类对象的元方法将不会被复制到新类。
+你可以通过使用 `using` 关键字来实现类混合。这意味着你可以从一个普通 Lua 表格或已定义的类对象中，复制函数到你创建的新类中。当你使用普通 Lua 表格进行类混合时，你有机会用自己的实现来重写类的索引方法（例如元方法 `__index`）。然而，当你从一个类对象做混合时，需要注意的是该类对象的元方法将不会被复制到新类。
 
 ```moonscript
 MyIndex = __index: var: 1
@@ -3255,11 +3930,11 @@ assert y.__class.__parent ~= X -- X 不是 Y 的父类
 
 ## with 语句
 
-在编写Lua代码时，我们在创建对象后的常见操作是立即调用这个对象一系列操作函数并设置一系列属性。
+在编写 Lua 代码时，我们在创建对象后的常见操作是立即调用这个对象一系列操作函数并设置一系列属性。
 
 这导致在代码中多次重复引用对象的名称，增加了不必要的文本噪音。一个常见的解决方案是在创建对象时，在构造函数传入一个表，该表包含要覆盖设置的键和值的集合。这样做的缺点是该对象的构造函数必须支持这种初始化形式。
 
-with块有助于简化编写这样的代码。在with块内，我们可以使用以.或\开头的特殊语句，这些语句代表我们正在使用的对象的操作。
+with 块有助于简化编写这样的代码。在 with 块内，我们可以使用以 . 或 \ 开头的特殊语句，这些语句代表我们正在使用的对象的操作。
 
 例如，我们可以这样处理一个新创建的对象：
 
@@ -3280,7 +3955,7 @@ with Person!
 </pre>
 </YueDisplay>
 
-with语句也可以用作一个表达式，并返回它的代码块正在处理的对象。
+with 语句也可以用作一个表达式，并返回它的代码块正在处理的对象。
 
 ```moonscript
 file = with File "favorite_foods.txt"
@@ -3314,24 +3989,24 @@ me = create_person "Leaf", [dad, mother, sister]
 </pre>
 </YueDisplay>
 
-在此用法中，with可以被视为K组合子（k-combinator）的一种特殊形式。
+在此用法中，with 可以被视为K组合子（k-combinator）的一种特殊形式。
 
-如果������给表达式另外起一个名称的话，with语句中的表达式也可以是一个赋值语句。
+如果你想给表达式另外起一个名称的话，with 语句中的表达式也可以是一个赋值语句。
 
 ```moonscript
-with str = "你好"
+with str := "你好"
   print "原始:", str
   print "大写:", \upper!
 ```
 <YueDisplay>
 <pre>
-with str = "你好"
+with str := "你好"
   print "原始:", str
   print "大写:", \upper!
 </pre>
 </YueDisplay>
 
-在with语句中可������用`[]`访问特殊键。
+你���以��� `with` 语句中使用 `[]` 访问特殊键。
 
 ```moonscript
 with tb
@@ -3354,9 +4029,22 @@ with tb
 </pre>
 </YueDisplay>
 
+`with?` 是 `with` 语法的一个增强版本，引入了存在性检查，用于在不显式判空的情况下安全访问可能为 nil 的对象。
+
+```moonscript
+with? obj
+  print obj.name
+```
+<YueDisplay>
+<pre>
+with? obj
+  print obj.name
+</pre>
+</YueDisplay>
+
 ## do 语句
 
-当用作语句时，do语句的作用就像在Lua中差不多。
+当用作语句时，do 语句的作用就像在 Lua 中差不多。
 
 ```moonscript
 do
@@ -3373,7 +4061,7 @@ print var -- 这里是nil
 </pre>
 </YueDisplay>
 
-月之脚本的 **do** 也可以用作表达式。允许您将多行代码的处理合并为一个表达式，并将do语句代码块的最后一个语句作为表达式返回的结果。
+月之脚本的 **do** 也可以用作表达式。允许你将多行代码的处理合并为一个表达式，并将 do 语句代码块的最后一个语句作为表达式返回的结果。
 
 ```moonscript
 counter = do
@@ -3557,7 +4245,7 @@ print i, k -- 这些已经被更新
 
 ## 月之脚本语言库
 
-使用`require("yue")`来访问。
+使用 `require("yue")` 来访问。
 
 ### yue
 
@@ -3615,9 +4303,9 @@ yue_compiled: {string: string}
 **签名：**
 ```lua
 to_lua: function(code: string, config?: Config):
-                --[[codes]] string | nil,
-                --[[error]] string | nil,
-                --[[globals]] {{string, integer, integer}} | nil
+    --[[codes]] string | nil,
+    --[[error]] string | nil,
+    --[[globals]] {{string, integer, integer}} | nil
 ```
 
 **参数：**
@@ -3740,8 +4428,8 @@ remove_loader: function(): boolean
 **签名：**
 ```lua
 loadstring: function(input: string, chunkname: string, env: table, config?: Config):
-                --[[loaded function]] nil | function(...: any): (any...),
-                --[[error]] string | nil
+    --[[loaded function]] nil | function(...: any): (any...),
+    --[[error]] string | nil
 ```
 
 **参数：**
@@ -3771,8 +4459,8 @@ loadstring: function(input: string, chunkname: string, env: table, config?: Conf
 **签名：**
 ```lua
 loadstring: function(input: string, chunkname: string, config?: Config):
-                --[[loaded function]] nil | function(...: any): (any...),
-                --[[error]] string | nil
+    --[[loaded function]] nil | function(...: any): (any...),
+    --[[error]] string | nil
 ```
 
 **参数：**
@@ -3801,8 +4489,8 @@ loadstring: function(input: string, chunkname: string, config?: Config):
 **签名：**
 ```lua
 loadstring: function(input: string, config?: Config):
-                --[[loaded function]] nil | function(...: any): (any...),
-                --[[error]] string | nil
+    --[[loaded function]] nil | function(...: any): (any...),
+    --[[error]] string | nil
 ```
 
 **参数：**
@@ -3830,8 +4518,8 @@ loadstring: function(input: string, config?: Config):
 **签名：**
 ```lua
 loadfile: function(filename: string, env: table, config?: Config):
-                nil | function(...: any): (any...),
-                string | nil
+    nil | function(...: any): (any...),
+    string | nil
 ```
 
 **参数：**
@@ -3860,8 +4548,8 @@ loadfile: function(filename: string, env: table, config?: Config):
 **签名：**
 ```lua
 loadfile: function(filename: string, config?: Config):
-                nil | function(...: any): (any...),
-                string | nil
+    nil | function(...: any): (any...),
+    string | nil
 ```
 
 **参数：**
@@ -4116,9 +4804,9 @@ type AST = {string, integer, integer, any}
 
 **签名：**
 ```lua
-to_ast: function(code: string, flattenLevel?: number, astName?: string):
-                --[[AST]] AST | nil,
-                --[[error]] nil | string
+to_ast: function(code: string, flattenLevel?: number, astName?: string, reserveComment?: boolean):
+    --[[AST]] AST | nil,
+    --[[error]] nil | string
 ```
 
 **参数：**
@@ -4127,6 +4815,42 @@ to_ast: function(code: string, flattenLevel?: number, astName?: string):
 | --- | --- | --- |
 | code | string | 代码。 |
 | flattenLevel | integer | [可选] 扁平化级别。级别越高，会消除更多的 AST 结构的嵌套。默认为 0。最大为 2。 |
+| astName | string | [可选] AST 名称。默认为 "File"。 |
+| reserveComment | boolean | [可选] 是否保留原始注释。默认为 false。 |
+
+**返回值：**
+
+| 返回类型 | 描述 |
+| --- | --- |
+| AST \| nil | AST，如果转换失败则为 nil。 |
+| string \| nil | 错误消息，如果转换成功则为 nil。 |
+
+#### format
+
+**类型：** 函数。
+
+**描述：**
+
+格式化 YueScript 代码。
+
+**签名：**
+```lua
+format: function(code: string, tabSize?: number, reserveComment?: boolean): string
+```
+
+**参数：**
+
+| 参数名 | 类型 | 描述 |
+| --- | --- | --- |
+| code | string | 代码。 |
+| tabSize | integer | [可选] 制表符大小。默认为 4。 |
+| reserveComment | boolean | [可选] 是否保留原始注释。默认为 true。 |
+
+**返回值：**
+
+| 返回类型 | 描述 |
+| --- | --- |
+| string | 格式化后的代码。 |
 
 #### __call
 
@@ -4199,6 +4923,19 @@ implicit_return_root: boolean
 reserve_line_number: boolean
 ```
 
+#### reserve_comment
+
+**类型：** 成员变量。
+
+**描述：**
+
+编译器是否应该在编译后的代码中保留原始注释。
+
+**签名：**
+```lua
+reserve_comment: boolean
+```
+
 #### space_over_tab
 
 **类型：** 成员变量。
@@ -4249,11 +4986,11 @@ line_offset: integer
 **签名：**
 ```lua
 enum LuaTarget
-        "5.1"
-        "5.2"
-        "5.3"
-        "5.4"
-        "5.5"
+  "5.1"
+  "5.2"
+  "5.3"
+  "5.4"
+  "5.5"
 end
 ```
 
@@ -4332,8 +5069,8 @@ simplified: boolean
 
 版权 (c) 2017-2025 李瑾  \<dragon-fly@qq.com\>
 
-特此免费授予任何获得本软件副本和相关文档文件（下称“软件”）的人不受限制地处置该软件的权利，包括不受限制地使用、复制、修改、合并、发布、分发、转授许可和/或出售该软件副本，以及再授权被配发了本软件的人如上的权利，须在下列条件下：  
-上述版权声明和本许可声明应包含在该软件的所有副本或实质成分中。  
+特此免费授予任何获得本软件副本和相关文档文件（下称“软件”）的人不受限制地处置该软件的权利，包括不受限制地使用、复制、修改、合并、发布、分发、转授许可和/或出售该软件副本，以及再授权被配发了本软件的人如上的权利，须在下列条件下：
+上述版权声明和本许可声明应包含在该软件的所有副本或实质成分中。
 本软件是“如此”提供的，没有任何形式的明示或暗示的保证，包括但不限于对适销性、特定用途的适用性和不侵权的保证。在任何情况下，作者或版权持有人都不对任何索赔、损害或其他责任负责，无论这些追责来自合同、侵权或其它行为中，还是产生于、源于或有关于本软件以及本软件的使用或其它处置。
 
 <CompilerModal />