@mirascript/help 0.1.40

package/src/keyword/in.md

@@ -0,0 +1,44 @@
+---
+token: 'in'
+---
+
+`in` 用于“包含/存在”判断，以及 `for` 循环。
+
+---
+
+对于 `array` 类型，`in` 用于判断某个元素是否在数组中存在：
+
+```mira
+fn is_spring(month) {
+  month in [3, 4, 5]
+}
+```
+
+---
+
+对于 `record` / `module` / `extern` 类型，`in` 用于判断某个键是否在容器中存在：
+
+```mira
+let record = (a: 1, b: 2, c: 3);
+let a_exists = 'a' in record; // true
+```
+
+---
+
+也可与 `global` 关键字结合使用，判断全局变量是否存在：
+
+```mira
+if 'my_global' in global {
+  my_global += 1;
+}
+```
+
+---
+
+同时，`for` 循环也使用 `in`：
+
+```mira
+for i in 1..3 {
+  // i: 1, 2, 3
+}
+```

package/src/keyword/inf.md

@@ -0,0 +1,10 @@
+---
+token: 'inf'
+---
+
+`inf` 是正无穷大的 `number` 常量。
+
+```mira
+inf > 1e100; // true
+-inf < 0;    // true
+```

package/src/keyword/is.md

@@ -0,0 +1,11 @@
+---
+token: 'is'
+---
+
+`is` 用于模式匹配：`value is pattern`，结果为 `boolean`。
+
+```mira
+1 is 1;        // true
+1 is > 0;      // true
+(a: 1) is (a: x); // true（并绑定 x）
+```

package/src/keyword/let.md

@@ -0,0 +1,11 @@
+---
+token: 'let'
+---
+
+`let` 用于声明局部变量。
+
+```mira
+let x = 1;
+let y = x + 2;
+let mut z = y * 3;
+```

package/src/keyword/loop.md

@@ -0,0 +1,13 @@
+---
+token: 'loop'
+---
+
+`loop` 创建一个无限循环，通常配合 `break` 退出。
+
+```mira
+let mut i = 0;
+loop {
+  i += 1;
+  if i >= 3 { break; }
+}
+```

package/src/keyword/match.md

@@ -0,0 +1,18 @@
+---
+token: 'match'
+---
+
+`match` 表达式对一个值进行分支匹配，由多个 `case` 组成。
+
+```mira
+fn classify {
+  match it {
+    case (0, 0) { "Origin" }
+    case (x, 0) if x > 0 { "Positive X-Axis (x=$x)" }
+    case (x, 0) if x < 0 { "Negative X-Axis (x=$x)" }
+    case (0, y) { "Y-Axis (y=$y)" }
+    case (x, y) { "Somewhere else (x=$x, y=$y)" }
+    case _ { "Not a point" }
+  }
+}
+```

package/src/keyword/mod.md

@@ -0,0 +1,6 @@
+---
+token: 'mod'
+reserved: true
+---
+
+`mod` 是保留关键字。

package/src/keyword/mut.md

@@ -0,0 +1,25 @@
+---
+token: 'mut'
+---
+
+`mut` 用于声明可变变量。
+
+---
+
+使用 `let` 语句时声明一个可变变量：
+
+```mira
+let mut x = 1;
+x += 2;
+// x == 3
+```
+
+---
+
+在模式匹配中声明一个可变绑定：
+
+```mira
+let (mut a, b) = (1, 2);
+a += 10;
+// b += 10; // 这行代码会报错，因为 b 是不可变的
+```

package/src/keyword/nan.md

@@ -0,0 +1,10 @@
+---
+token: 'nan'
+---
+
+`nan` 是一个特殊的 `number` 值（Not a Number）。它与任何值都不相等（包括它自己）。
+
+```mira
+nan == nan; // false
+nan =~ nan; // false
+```

package/src/keyword/nil.md

@@ -0,0 +1,11 @@
+---
+token: 'nil'
+---
+
+`nil` 表示“空值”。当访问不存在的字段、对 `nil` 进行空安全链式调用等场景时，结果也会是 `nil`。
+
+```mira
+let x = nil;
+let y = x ?? 0;     // 0
+let z = x.anything; // nil（空安全访问）
+```

package/src/keyword/not.md

@@ -0,0 +1,26 @@
+---
+token: 'not'
+---
+
+`not` 用于在模式匹配中取反一个模式，也可以作为 `!` 运算符的替代写法。
+
+---
+
+逻辑非模式：
+
+```mira
+fn is_not_weekend(day) {
+  day is not 6 and not 7
+}
+```
+
+---
+
+逻辑非运算符：
+
+```mira
+fn is_minor(age) {
+  // 等同于 !(age >= 18)
+  not (age >= 18)
+}
+```

package/src/keyword/op.md

@@ -0,0 +1,6 @@
+---
+token: 'op'
+reserved: true
+---
+
+`op` 是保留关键字。

package/src/keyword/or.md

@@ -0,0 +1,26 @@
+---
+token: 'or'
+---
+
+`or` 用于在模式匹配中组合多个模式，也可以作为 `||` 运算符的替代写法。
+
+---
+
+逻辑或模式：
+
+```mira
+fn is_weekend(day) {
+  day is 6 or 7
+}
+```
+
+---
+
+逻辑或运算符：
+
+```mira
+fn is_superuser(role) {
+  // 等同于 role == "admin" || role == "superuser"
+  role == "admin" or role == "superuser"
+}
+```

package/src/keyword/perform.md

@@ -0,0 +1,6 @@
+---
+token: 'perform'
+reserved: true
+---
+
+`perform` 是保留关键字。

package/src/keyword/pub.md

@@ -0,0 +1,6 @@
+---
+token: 'pub'
+reserved: true
+---
+
+`pub` 是保留关键字。

package/src/keyword/resume.md

@@ -0,0 +1,6 @@
+---
+token: 'resume'
+reserved: true
+---
+
+`resume` 是保留关键字。

package/src/keyword/return.md

@@ -0,0 +1,12 @@
+---
+token: 'return'
+---
+
+`return` 用于从函数中返回值。
+
+```mira
+fn abs {
+  if it < 0 { return -it; }
+  return it;
+}
+```

package/src/keyword/true.md

@@ -0,0 +1,5 @@
+---
+token: 'true'
+---
+
+`true` 是布尔字面量，表示逻辑真。

package/src/keyword/try.md

@@ -0,0 +1,6 @@
+---
+token: 'try'
+reserved: true
+---
+
+`try` 是保留关键字。

package/src/keyword/type.md

@@ -0,0 +1,10 @@
+---
+token: 'type'
+---
+
+`type` 用于获得值的类型名字符串。
+
+```mira
+type(1);       // "number"
+nil::type();   // "nil"（扩展调用写法）
+```

package/src/keyword/underscore.md

@@ -0,0 +1,16 @@
+---
+token: '_'
+---
+
+`_` 是弃元关键字，用于在模式匹配中匹配并忽略任意值。
+
+```mira
+let (_, y) = (1, 2); // y == 2
+
+fn head {
+  match it {
+    case [x, ..] { x }
+    case _ { nil }
+  }
+}
+```

package/src/keyword/use.md

@@ -0,0 +1,6 @@
+---
+token: 'use'
+reserved: true
+---
+
+`use` 是保留关键字。

package/src/keyword/where.md

@@ -0,0 +1,6 @@
+---
+token: 'where'
+reserved: true
+---
+
+`where` 是保留关键字。

package/src/keyword/while.md

@@ -0,0 +1,12 @@
+---
+token: 'while'
+---
+
+`while` 循环在条件为 `true` 时重复执行循环体。
+
+```mira
+let mut i = 0;
+while i < 3 {
+  i += 1;
+}
+```

package/src/operator/arrow.md

@@ -0,0 +1,6 @@
+---
+token: '->'
+reserved: true
+---
+
+`->` 用于在文档中标记函数的返回值类型，在 MiraScript 代码中不使用。

package/src/operator/assign.md

@@ -0,0 +1,23 @@
+---
+token: '='
+---
+
+`=` 用于赋值。
+
+---
+
+声明时初始化：
+
+```mira
+let x = 1;
+const @y = 2;
+```
+
+---
+
+对可变变量/可写字段赋值：
+
+```mira
+let mut x = 1;
+x = x + 1;
+```

package/src/operator/asterisk.md

@@ -0,0 +1,9 @@
+---
+token: '*'
+---
+
+`*` 用于乘法。
+
+```mira
+2 * 3; // 6
+```

package/src/operator/asterisk_assign.md

@@ -0,0 +1,11 @@
+---
+token: '*='
+---
+
+`*=` 是复合赋值，`x *= y` 等价于 `x = x * y`。
+
+```mira
+let mut x = 2;
+x *= 3;
+// x == 6
+```

package/src/operator/brace.md

@@ -0,0 +1,26 @@
+---
+token: ['{', '}']
+---
+
+`{ }` 用于表达式块或 JSON 风格记录字面量。
+
+---
+
+表达式块：
+
+```mira
+let x = { 1 + 2 };
+```
+
+---
+
+在 JSON 风格记录字面量中，键名必须使用引号括起来：
+
+```mira
+let obj = { "x": 1, "y": 2, "n": nil };
+```
+
+注意：
+
+- JSON 风格记录字面量不能为空，要声明一个空记录，请用 `()`；
+- 键和值仍为 MiraScript 表达式，因此需要使用 `nil` 来表示空值，而不是 `null`。

package/src/operator/bracket.md

@@ -0,0 +1,32 @@
+---
+token: ['[', ']']
+---
+
+`[ ]` 用于数组字面量、索引访问与切片。
+
+---
+
+数组字面量：
+
+```mira
+let arr = [1, 2, 3];
+```
+
+---
+
+索引访问：
+
+```mira
+let first = arr[0];
+let last = arr[-1];
+let value = record["key"];
+```
+
+---
+
+数组切片：
+
+```mira
+let subarr1 = arr[0..1];   // 取前两个元素
+let subarr2 = arr[..<-1];  // 取到倒数第一个元素（不含）
+```

package/src/operator/caret.md

@@ -0,0 +1,10 @@
+---
+token: '^'
+---
+
+`^` 用于乘方，结合性为从右到左。
+
+```mira
+2 ^ 3;     // 8
+2 ^ 3 ^ 2; // 2^(3^2)
+```

package/src/operator/caret_assign.md

@@ -0,0 +1,11 @@
+---
+token: '^='
+---
+
+`^=` 是复合赋值，`x ^= y` 等价于 `x = x ^ y`。
+
+```mira
+let mut x = 2;
+x ^= 3;
+// x == 8
+```

package/src/operator/colon.md

@@ -0,0 +1,29 @@
+---
+token: ':'
+---
+
+`:` 用于记录字面量、条件表达式和插值格式。
+
+---
+
+在记录字面量中，`:` 用于分隔字段名和字段值。
+
+```mira
+let r = (x: 1, y: 2);
+```
+
+---
+
+在条件表达式中，`:` 用于分隔条件的不同分支。
+
+```mira
+let status = score >= 60 ? "及格" : "不及格";
+```
+
+---
+
+在插值格式中，`:` 用于指定格式化选项。在指定格式化选项时，必须使用圆括号 `$(expr:format)`。
+
+```mira
+debug_print("π 的值约为 $(PI:.2)"); // 输出: π 的值约为 3.14
+```

package/src/operator/colon_colon.md

@@ -0,0 +1,10 @@
+---
+token: '::'
+---
+
+`::` 用于扩展调用。
+
+```mira
+"Hello"::chars()::join("");
+// 相当于 join(chars("Hello"), "");
+```

package/src/operator/comma.md

@@ -0,0 +1,13 @@
+---
+token: ','
+---
+
+`,` 用于分隔参数、数组元素、记录字段等。
+
+```mira
+let arr = [1, 2, 3];
+let r = (a: 1, b: 2);
+
+fn f(a, b, c) { a + b + c }
+f(1, 2, 3);
+```

package/src/operator/dot.md

@@ -0,0 +1,15 @@
+---
+token: '.'
+---
+
+`.` 用于成员访问。
+
+```mira
+let r = (a: 1);
+r.a; // 1
+r.b; // nil
+
+let arr = [10, 20];
+arr.0; // 10
+arr.2; // nil
+```

package/src/operator/equal.md

@@ -0,0 +1,43 @@
+---
+token: '=='
+---
+
+使用 `==` 运算符可以比较两个值是否严格相等。
+
+---
+
+对于原始值，如果它们的类型和值都相同，则认为它们相等。
+
+```mira
+5 == 5;            // true
+"hello" == "hello"; // true
+true == true;      // true
+5 == "5";         // false
+```
+
+特别地，对于 `number` 类型的值 `nan`，它与任何值都不相等，包括它自己。
+
+```mira
+nan == nan; // false
+```
+
+---
+
+对于 `array` 和 `record`，只有他们的元素和属性都相等时，才认为它们相等。
+
+```mira
+[1, 2, 3] == [1, 2, 3]; // true
+(a: 1, b: 2) == (a: 1, b: 2); // true
+[1, 2, 3] == [1, 2, 4]; // false
+```
+
+---
+
+对于 `function` `module` 和 `extern`，只有它们引用的是同一个对象时，才认为它们相等。
+
+```mira
+let fn1 = fn() { return 1; };
+let fn2 = fn() { return 1; };
+fn1 == fn1; // true
+fn1 == fn2; // false
+```

package/src/operator/exclamation.md

@@ -0,0 +1,23 @@
+---
+token: '!'
+---
+
+`!` 既可以作为前缀逻辑非，也可以作为后缀非空断言。
+
+---
+
+逻辑非：
+
+```mira
+!x // x 必须是 boolean
+```
+
+---
+
+非空断言：
+
+```mira
+
+let x = nil;
+x!; // panic
+```

package/src/operator/greater.md

@@ -0,0 +1,10 @@
+---
+token: '>'
+---
+
+`>` 用于“大于”比较。
+
+```mira
+2 > 1;     // true
+"b" > "a"; // true
+```

package/src/operator/greater_equal.md

@@ -0,0 +1,9 @@
+---
+token: '>='
+---
+
+`>=` 用于“大于等于”比较。
+
+```mira
+2 >= 2; // true
+```

package/src/operator/half_open_range.md

@@ -0,0 +1,12 @@
+---
+token: '..<'
+---
+
+`..<` 表示右开区间范围，包含起点，不包含终点。
+
+```mira
+[1..<3]; // [1, 2]
+
+let arr = [10, 20, 30, 40];
+arr[1..<3]; // [20, 30]
+```

package/src/operator/less.md

@@ -0,0 +1,9 @@
+---
+token: '<'
+---
+
+`<` 用于“小于”比较。
+
+```mira
+1 < 2; // true
+```

package/src/operator/less_equal.md

@@ -0,0 +1,9 @@
+---
+token: '<='
+---
+
+`<=` 用于“小于等于”比较。
+
+```mira
+2 <= 2; // true
+```