1 files changed, 511 insertions, 63 deletions

diff --git a/doc/docs/doc/README.md b/doc/docs/doc/README.md
index c4518bf..f0d67a5 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
@@ -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.
@@ -566,11 +634,26 @@ 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]
+```
+<YueDisplay>
+<pre>
+last = data.items[#]
+second_last = 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 +689,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 +713,7 @@ print tb.item
 </pre>
 </YueDisplay>
 
-* **Metatable Destructure**  
+* **Metatable Destructure**
 Destruct metatable with metamethod key surrounded by **<>**.
 
 ```moonscript
@@ -732,34 +815,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 +861,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: { }
@@ -860,7 +964,7 @@ do
 
 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 +1028,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 +1058,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 +1306,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 +1350,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:
@@ -1475,6 +1625,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 +1694,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 +1739,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>
 
@@ -1902,22 +2167,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>
@@ -2248,6 +2513,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 +2628,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 +2666,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 +2945,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 +2995,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 +3041,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 +3101,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 +3349,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 +3436,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 +3515,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 +3530,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 +3796,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 +3831,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 +3863,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 +3989,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.