From a9d28cb615d2bdc09d2482d5262951f2afc8d6e1 Mon Sep 17 00:00:00 2001
From: Li Jin <dragon-fly@qq.com>
Date: Mon, 26 May 2025 15:52:07 +0800
Subject: Added doc for `with?` syntax.

---
 doc/docs/doc/README.md             | 14 +++++++++++++-
 doc/docs/zh/doc/README.md          | 15 ++++++++++++++-
 spec/inputs/with.yue               |  5 +++++
 spec/outputs/codes_from_doc.lua    |  8 ++++++++
 spec/outputs/codes_from_doc_zh.lua |  8 ++++++++
 spec/outputs/with.lua              | 16 ++++++++++++++++
 6 files changed, 64 insertions(+), 2 deletions(-)

diff --git a/doc/docs/doc/README.md b/doc/docs/doc/README.md
index 7e9b454..a970baa 100755
--- a/doc/docs/doc/README.md
+++ b/doc/docs/doc/README.md
@@ -3538,7 +3538,7 @@ with str := "Hello"
 </pre>
 </YueDisplay>
 
-Accessing special keys with `[]` in a `with` statement.
+You can access special keys with `[]` in a `with` statement.
 
 ```moonscript
 with tb
@@ -3561,6 +3561,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
 
diff --git a/doc/docs/zh/doc/README.md b/doc/docs/zh/doc/README.md
index da90fa6..2d4af18 100755
--- a/doc/docs/zh/doc/README.md
+++ b/doc/docs/zh/doc/README.md
@@ -3494,7 +3494,7 @@ with str := "你好"
 </pre>
 </YueDisplay>
 
-在with语句中可以使用`[]`访问特殊键。
+你可以在 `with` 语句中使用 `[]` 访问特殊键。
 
 ```moonscript
 with tb
@@ -3517,6 +3517,19 @@ 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中差不多。
diff --git a/spec/inputs/with.yue b/spec/inputs/with.yue
index c1cf3e3..2256833 100644
--- a/spec/inputs/with.yue
+++ b/spec/inputs/with.yue
@@ -165,4 +165,9 @@ do
 		break with? tb
 			break 1
 
+do
+	a = for i = 1, 100
+	  with? x := tb[i]
+		 break x if .id := 1
+
 nil
diff --git a/spec/outputs/codes_from_doc.lua b/spec/outputs/codes_from_doc.lua
index d857dec..55be7df 100644
--- a/spec/outputs/codes_from_doc.lua
+++ b/spec/outputs/codes_from_doc.lua
@@ -2147,6 +2147,10 @@ do
 	_with_1["key-name"] = value
 end
 _with_0[#_with_0 + 1] = "abc"
+local _with_0 = obj
+if _with_0 ~= nil then
+	print(obj.name)
+end
 do
 	local var = "hello"
 	print(var)
@@ -4363,6 +4367,10 @@ do
 	_with_1["key-name"] = value
 end
 _with_0[#_with_0 + 1] = "abc"
+local _with_0 = obj
+if _with_0 ~= nil then
+	print(obj.name)
+end
 do
 	local var = "hello"
 	print(var)
diff --git a/spec/outputs/codes_from_doc_zh.lua b/spec/outputs/codes_from_doc_zh.lua
index ecab077..399f8c1 100644
--- a/spec/outputs/codes_from_doc_zh.lua
+++ b/spec/outputs/codes_from_doc_zh.lua
@@ -2141,6 +2141,10 @@ do
 	_with_1["key-name"] = value
 end
 _with_0[#_with_0 + 1] = "abc"
+local _with_0 = obj
+if _with_0 ~= nil then
+	print(obj.name)
+end
 do
 	local var = "hello"
 	print(var)
@@ -4351,6 +4355,10 @@ do
 	_with_1["key-name"] = value
 end
 _with_0[#_with_0 + 1] = "abc"
+local _with_0 = obj
+if _with_0 ~= nil then
+	print(obj.name)
+end
 do
 	local var = "hello"
 	print(var)
diff --git a/spec/outputs/with.lua b/spec/outputs/with.lua
index 867d1b5..338d51f 100644
--- a/spec/outputs/with.lua
+++ b/spec/outputs/with.lua
@@ -234,4 +234,20 @@ do
 	end
 	a = _accum_0
 end
+do
+	local a
+	local _accum_0
+	for i = 1, 100 do
+		local x = tb[i]
+		if x ~= nil then
+			local _des_0 = 1
+			if _des_0 then
+				x.id = _des_0
+				_accum_0 = x
+				break
+			end
+		end
+	end
+	a = _accum_0
+end
 return nil
-- 
cgit v1.2.3-55-g6feb