update docs

Author: myfreess

docs/RuleSpec.md

@@ -124,6 +124,65 @@ For example, two different imported names that refer to the same definition are
 still different unless their parsed source spelling matches or a metavariable
 captures them.
 
+### Let Shapes With Omitted Bodies
+
+An ordinary `let` shape without an explicit body is a let-header pattern. For
+example, this shape matches the binding pattern and right-hand side, but does
+not constrain the candidate body:
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp)
+```
+
+It can match candidates such as:
+
+```moonbit
+let item = load()
+```
+
+```moonbit
+let item = load(); use(item)
+```
+
+```moonbit
+let item = load(); { trace(item); item }
+```
+
+This exception exists because the MoonBit parser represents `let item = load()`
+as an `Expr::Let` whose body is a synthesized unit expression. When that
+synthesized unit appears in the pattern shape, the matcher treats it as "body
+omitted in the pattern" instead of requiring the candidate body to be the same
+unit node.
+
+Write an explicit body when the body matters:
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp); use($(name:id))
+```
+
+To capture whichever body the candidate has, write a body metavar explicitly:
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp); $(body:exp)
+```
+
+To require a unit body, write an explicit `()` body:
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp); ()
+```
+
+This matches an explicit unit body. It is not the same as the omitted-body
+shape above, which intentionally ignores the candidate body. Omitted-body-only
+matching is not currently expressible as a structural shape.
+
+This shortcut applies only to ordinary `let` expressions. `let mut`, local
+function definitions, and `letrec` shapes use normal structural matching.
+
 ## Metavariables
 
 Identifiers and labels in a shape are literal by default. A name becomes a

docs/RuleSpec_CN.md

@@ -100,6 +100,62 @@ shape 是结构性的：
 
 扫描器不会对 shape 做类型检查，也不会按语义解析名称。例如，两个不同的导入名称即使指向同一定义，仍然是不同的；除非它们解析后的源码拼写一致，或被元变量捕获。
 
+### 省略 body 的 let shape
+
+没有显式 body 的普通 `let` shape 是 let-header pattern。例如，下面的 shape
+会匹配绑定 pattern 和右侧表达式，但不会约束候选表达式的 body：
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp)
+```
+
+它可以匹配下面这些候选形式：
+
+```moonbit
+let item = load()
+```
+
+```moonbit
+let item = load(); use(item)
+```
+
+```moonbit
+let item = load(); { trace(item); item }
+```
+
+这个例外来自 MoonBit parser 的表示方式：`let item = load()` 会被表示为
+`Expr::Let`，其 body 是一个合成的 unit 表达式。当 pattern shape 中出现这个合成
+unit 时，matcher 会把它视为“pattern 省略了 body”，而不是要求候选 body
+也必须是同一个 unit node。
+
+如果 body 重要，请显式写出 body：
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp); use($(name:id))
+```
+
+如果候选 body 可以是任意表达式，但你想捕获它，请显式写 body 元变量：
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp); $(body:exp)
+```
+
+如果期望 body 是 unit，请显式写 `()` body：
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp); ()
+```
+
+这会匹配显式 unit body。它不同于上面的省略 body shape；省略 body 的形式会有意忽略候选 body。当前结构 shape
+无法表达“只匹配语法上省略 body 的 let”。
+
+这个快捷匹配只适用于普通 `let` 表达式。`let mut`、局部函数定义和
+`letrec` shape 使用普通结构匹配。
+
 ## 元变量
 
 shape 中的标识符和标签默认都是字面量。只有在 `shape` 内使用内联元变量语法时，一个名称才会成为元变量；下面描述的内置通配符除外。

docs/WritingRules.md

@@ -148,6 +148,57 @@ patterns:
 file or a fragment that only makes sense at module scope, rule compilation will
 fail.
 
+### 1.1. Decide whether a `let` body matters
+
+An ordinary `let` shape with no explicit body matches only the let header. This
+is useful when the binding itself is the interesting part:
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp)
+```
+
+That shape can match all of these candidate forms because the body is ignored:
+
+```moonbit
+let item = load()
+```
+
+```moonbit
+let item = load(); use(item)
+```
+
+```moonbit
+let item = load(); { trace(item); item }
+```
+
+If the body matters, write it in the shape:
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp); use($(name:id))
+```
+
+If the body can be anything but you want to capture it, add an explicit body
+metavar:
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp); $(body:exp)
+```
+
+If you expect the body to be unit, write the unit body explicitly:
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp); ()
+```
+
+Do not use `let $(name:id) = $(value:exp)` when you mean "the body is empty" or
+"the body is `()`"; the omitted-body form intentionally ignores whatever body
+the candidate has. Matching only syntactically omitted let bodies is not
+currently expressible as a structural shape.
+
 ### 2. Mark metavars inline in `shape`
 
 Names in `shape` are literal by default, even if they look like placeholders.

docs/WritingRules_CN.md

@@ -87,6 +87,54 @@ patterns:
 
 `shape` 会作为单个 MoonBit 表达式片段解析。如果你粘贴整个文件，或只在模块作用域才有意义的片段，规则编译会失败。
 
+### 1.1. 判断 `let` body 是否重要
+
+没有显式 body 的普通 `let` shape 只匹配 let header。当你只关心绑定本身时，这很有用：
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp)
+```
+
+因为 body 会被忽略，这个 shape 可以匹配下面所有候选形式：
+
+```moonbit
+let item = load()
+```
+
+```moonbit
+let item = load(); use(item)
+```
+
+```moonbit
+let item = load(); { trace(item); item }
+```
+
+如果 body 重要，请把它写进 shape：
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp); use($(name:id))
+```
+
+如果 body 可以是任意表达式，但你想捕获它，请显式添加 body 元变量：
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp); $(body:exp)
+```
+
+如果你期望 body 是 unit，请显式写 unit body：
+
+```yaml
+patterns:
+  - shape: let $(name:id) = $(value:exp); ()
+```
+
+当你的意思是“body 为空”或“body 是 `()`”时，不要写
+`let $(name:id) = $(value:exp)`；省略 body 的形式会有意忽略候选表达式的任意 body。当前结构 shape
+无法表达“只匹配语法上省略 body 的 let”。
+
 ### 2. 在 `shape` 中内联标记元变量
 
 `shape` 中的名称默认都是字面量，即使它们看起来像占位符。

docs/rule_spec.mbt

@@ -128,6 +128,65 @@ let _embed_rulespec_md : String =
   #|still different unless their parsed source spelling matches or a metavariable
   #|captures them.
   #|
+  #|### Let Shapes With Omitted Bodies
+  #|
+  #|An ordinary `let` shape without an explicit body is a let-header pattern. For
+  #|example, this shape matches the binding pattern and right-hand side, but does
+  #|not constrain the candidate body:
+  #|
+  #|```yaml
+  #|patterns:
+  #|  - shape: let $(name:id) = $(value:exp)
+  #|```
+  #|
+  #|It can match candidates such as:
+  #|
+  #|```moonbit
+  #|let item = load()
+  #|```
+  #|
+  #|```moonbit
+  #|let item = load(); use(item)
+  #|```
+  #|
+  #|```moonbit
+  #|let item = load(); { trace(item); item }
+  #|```
+  #|
+  #|This exception exists because the MoonBit parser represents `let item = load()`
+  #|as an `Expr::Let` whose body is a synthesized unit expression. When that
+  #|synthesized unit appears in the pattern shape, the matcher treats it as "body
+  #|omitted in the pattern" instead of requiring the candidate body to be the same
+  #|unit node.
+  #|
+  #|Write an explicit body when the body matters:
+  #|
+  #|```yaml
+  #|patterns:
+  #|  - shape: let $(name:id) = $(value:exp); use($(name:id))
+  #|```
+  #|
+  #|To capture whichever body the candidate has, write a body metavar explicitly:
+  #|
+  #|```yaml
+  #|patterns:
+  #|  - shape: let $(name:id) = $(value:exp); $(body:exp)
+  #|```
+  #|
+  #|To require a unit body, write an explicit `()` body:
+  #|
+  #|```yaml
+  #|patterns:
+  #|  - shape: let $(name:id) = $(value:exp); ()
+  #|```
+  #|
+  #|This matches an explicit unit body. It is not the same as the omitted-body
+  #|shape above, which intentionally ignores the candidate body. Omitted-body-only
+  #|matching is not currently expressible as a structural shape.
+  #|
+  #|This shortcut applies only to ordinary `let` expressions. `let mut`, local
+  #|function definitions, and `letrec` shapes use normal structural matching.
+  #|
   #|## Metavariables
   #|
   #|Identifiers and labels in a shape are literal by default. A name becomes a

docs/writing_rules.mbt

@@ -152,6 +152,57 @@ let _embed_writingrules_md : String =
   #|file or a fragment that only makes sense at module scope, rule compilation will
   #|fail.
   #|
+  #|### 1.1. Decide whether a `let` body matters
+  #|
+  #|An ordinary `let` shape with no explicit body matches only the let header. This
+  #|is useful when the binding itself is the interesting part:
+  #|
+  #|```yaml
+  #|patterns:
+  #|  - shape: let $(name:id) = $(value:exp)
+  #|```
+  #|
+  #|That shape can match all of these candidate forms because the body is ignored:
+  #|
+  #|```moonbit
+  #|let item = load()
+  #|```
+  #|
+  #|```moonbit
+  #|let item = load(); use(item)
+  #|```
+  #|
+  #|```moonbit
+  #|let item = load(); { trace(item); item }
+  #|```
+  #|
+  #|If the body matters, write it in the shape:
+  #|
+  #|```yaml
+  #|patterns:
+  #|  - shape: let $(name:id) = $(value:exp); use($(name:id))
+  #|```
+  #|
+  #|If the body can be anything but you want to capture it, add an explicit body
+  #|metavar:
+  #|
+  #|```yaml
+  #|patterns:
+  #|  - shape: let $(name:id) = $(value:exp); $(body:exp)
+  #|```
+  #|
+  #|If you expect the body to be unit, write the unit body explicitly:
+  #|
+  #|```yaml
+  #|patterns:
+  #|  - shape: let $(name:id) = $(value:exp); ()
+  #|```
+  #|
+  #|Do not use `let $(name:id) = $(value:exp)` when you mean "the body is empty" or
+  #|"the body is `()`"; the omitted-body form intentionally ignores whatever body
+  #|the candidate has. Matching only syntactically omitted let bodies is not
+  #|currently expressible as a structural shape.
+  #|
   #|### 2. Mark metavars inline in `shape`
   #|
   #|Names in `shape` are literal by default, even if they look like placeholders.