@mirascript/help 0.1.40

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+/* Generated by scripts/build.js. Do not edit manually. */
+
+export declare const KEYWORDS: {
+  readonly "and": string;
+  readonly "break": string;
+  readonly "case": string;
+  readonly "const": string;
+  readonly "continue": string;
+  readonly "else": string;
+  readonly "false": string;
+  readonly "fn": string;
+  readonly "for": string;
+  readonly "global": string;
+  readonly "if": string;
+  readonly "in": string;
+  readonly "inf": string;
+  readonly "is": string;
+  readonly "let": string;
+  readonly "loop": string;
+  readonly "match": string;
+  readonly "mut": string;
+  readonly "nan": string;
+  readonly "nil": string;
+  readonly "not": string;
+  readonly "or": string;
+  readonly "return": string;
+  readonly "true": string;
+  readonly "type": string;
+  readonly "_": string;
+  readonly "while": string;
+};
+export declare const OPERATORS: {
+  readonly "=": string;
+  readonly "*": string;
+  readonly "*=": string;
+  readonly "{": string;
+  readonly "}": string;
+  readonly "[": string;
+  readonly "]": string;
+  readonly "^": string;
+  readonly "^=": string;
+  readonly ":": string;
+  readonly "::": string;
+  readonly ",": string;
+  readonly ".": string;
+  readonly "==": string;
+  readonly "!": string;
+  readonly ">": string;
+  readonly ">=": string;
+  readonly "..<": string;
+  readonly "<": string;
+  readonly "<=": string;
+  readonly "&&": string;
+  readonly "&&=": string;
+  readonly "||": string;
+  readonly "||=": string;
+  readonly "-": string;
+  readonly "-=": string;
+  readonly "!=": string;
+  readonly "??": string;
+  readonly "??=": string;
+  readonly "(": string;
+  readonly ")": string;
+  readonly "%": string;
+  readonly "%=": string;
+  readonly "+": string;
+  readonly "+=": string;
+  readonly "?": string;
+  readonly "?:": string;
+  readonly ";": string;
+  readonly "/": string;
+  readonly "/=": string;
+  readonly "..": string;
+  readonly "=~": string;
+  readonly "!~": string;
+};
+
+export type Keyword = keyof typeof KEYWORDS;
+export type Operator = keyof typeof OPERATORS;

package/dist/index.js

@@ -0,0 +1,78 @@
+/* Generated by scripts/build.js. Do not edit manually. */
+
+export const KEYWORDS = Object.freeze({
+  __proto__: null,
+  "and": "`and` 用于在模式匹配中组合多个模式，也可以作为 `&&` 运算符的替代写法。\n\n---\n\n逻辑与模式：\n\n```mira\nfn is_month(month) {\n  month is >= 1 and <= 12\n}\n```\n\n---\n\n逻辑与运算符：\n\n```mira\nfn is_adult(age) {\n  // 等同于 age >= 18 && age <= 65\n  age >= 18 and age <= 65\n}\n```\n",
+  "break": "`break` 用于提前退出 `for` / `while` / `loop`。\n\n---\n\n基本用法\n\n```mira\nlet mut i = 0;\nloop {\n  i += 1;\n  break;\n}\n```\n\n---\n\n从循环中返回一个值\n\n```mira\nlet mut i = 0;\nlet result = loop {\n  i += 1;\n  if i == 10 {\n    break i * 2;\n  }\n};\n// result 的值是 20\n```\n",
+  "case": "`case` 是 `match` 表达式中的分支。\n\n```mira\nfn age_group(age) {\n  match age {\n    case 0..12 { \"child\"}\n    case 13..19 { \"teenager\" }\n    case 20..64 { \"adult\" }\n    case _ { \"senior\" }\n  }\n}\n```\n",
+  "const": "`const` 用于声明常量。常量名必须以 `@` 开头。\n\n```mira\nconst @PI = 3.14159;\n// @PI = 0; // 错误：常量不可重新赋值\n```\n",
+  "continue": "`continue` 用于跳过本次循环剩余部分，进入下一次循环。\n\n```mira\nlet mut sum = 0;\nfor i in 1..5 {\n  if i % 2 == 0 { continue; }\n  sum += i;\n}\n// sum == 1 + 3 + 5\n```\n",
+  "else": "`else` 用于 `if` 表达式，也可用作 `while` 和 `for` 循环的可选分支。\n\n---\n\n作为 `if` 表达式的分支\n\n```mira\nlet x = if false { 1 } else { 2 }; // 2\n```\n\n---\n\n作为循环的可选分支\n\n```mira\nlet mut i = 0;\nlet result = while i < 5 {\n  i += 1;\n  if i == 6 {\n    // 使用 break 语句提前退出循环，并返回一个值\n    break i * 2;\n  }\n} else {\n  // 当循环正常结束时执行\n  100\n};\n// result 的值是 100\n```\n",
+  "false": "`false` 是布尔字面量，表示逻辑假。\n",
+  "fn": "使用 `fn` 关键字定义一个函数或函数表达式。\n\n---\n\n定义一个简单的函数：\n\n```mira\nfn add(a, b) {\n  return a + b;\n}\n```\n\n---\n\n定义一个变量，并使用函数表达式初始化：\n\n```mira\nlet multiply = fn(x, y) {\n  return x * y;\n};\n```\n\n---\n\n当函数只有一个参数时，可以省略括号，并用 `it` 引用该参数。\n\n```mira\nfn square {\n  return it * it;\n}\n```\n",
+  "for": "`for` 用于遍历可迭代对象。\n\n---\n\n遍历一个范围：\n\n```mira\nlet mut sum = 0;\nfor i in 1..3 { // 或者 1..<4\n  sum += i;\n}\n// sum == 6\n```\n\n---\n\n遍历一个数组：\n\n```mira\nlet arr = [10, 20, 30];\nlet mut sum = 0;\nfor value in arr {\n  sum += value;\n}\n// sum == 60\n```\n\n---\n\n遍历一个记录：\n\n```mira\nlet record = (a: 1, b: 2, c: 3);\nlet mut sum = 0;\nfor key in record {\n  sum += record[key];\n}\n// sum == 6\n```\n",
+  "global": "`global` 表示全局对象（全局命名空间）。通常用于读取全局变量或判断某个全局键是否存在。\n\n```mira\n// 访问全局变量\nglobal.some_name;\n\n// 动态访问全局变量\nglobal['some_name'];\n\n// 判断键是否存在\n'some_name' in global;\n```\n",
+  "if": "`if` 用于 `if` 表达式或 `match` 表达式的守卫条件。\n\n---\n\n`if` 表达式根据条件选择分支。条件必须是 `boolean`。\n\n```mira\nlet x = if 1 > 0 { \"pos\" } else { \"neg\" };\n```\n\n---\n\n使用 `else if` 添加多个条件分支：\n\n```mira\nlet x = if 1 > 2 {\n  \"greater\"\n} else if 1 == 2 {\n  \"equal\"\n} else {\n  \"less\"\n};\n```\n\n---\n\n在 `match` 表达式中使用 `if` 作为守卫条件：\n\n```mira\nlet num = 10;\nlet result = match num {\n  case n if n % 2 == 0 { \"even\" }\n  case n { \"odd\" }\n};\n// result 的值是 \"even\"\n```\n",
+  "in": "`in` 用于“包含/存在”判断，以及 `for` 循环。\n\n---\n\n对于 `array` 类型，`in` 用于判断某个元素是否在数组中存在：\n\n```mira\nfn is_spring(month) {\n  month in [3, 4, 5]\n}\n```\n\n---\n\n对于 `record` / `module` / `extern` 类型，`in` 用于判断某个键是否在容器中存在：\n\n```mira\nlet record = (a: 1, b: 2, c: 3);\nlet a_exists = 'a' in record; // true\n```\n\n---\n\n也可与 `global` 关键字结合使用，判断全局变量是否存在：\n\n```mira\nif 'my_global' in global {\n  my_global += 1;\n}\n```\n\n---\n\n同时，`for` 循环也使用 `in`：\n\n```mira\nfor i in 1..3 {\n  // i: 1, 2, 3\n}\n```\n",
+  "inf": "`inf` 是正无穷大的 `number` 常量。\n\n```mira\ninf > 1e100; // true\n-inf < 0;    // true\n```\n",
+  "is": "`is` 用于模式匹配：`value is pattern`，结果为 `boolean`。\n\n```mira\n1 is 1;        // true\n1 is > 0;      // true\n(a: 1) is (a: x); // true（并绑定 x）\n```\n",
+  "let": "`let` 用于声明局部变量。\n\n```mira\nlet x = 1;\nlet y = x + 2;\nlet mut z = y * 3;\n```\n",
+  "loop": "`loop` 创建一个无限循环，通常配合 `break` 退出。\n\n```mira\nlet mut i = 0;\nloop {\n  i += 1;\n  if i >= 3 { break; }\n}\n```\n",
+  "match": "`match` 表达式对一个值进行分支匹配，由多个 `case` 组成。\n\n```mira\nfn classify {\n  match it {\n    case (0, 0) { \"Origin\" }\n    case (x, 0) if x > 0 { \"Positive X-Axis (x=$x)\" }\n    case (x, 0) if x < 0 { \"Negative X-Axis (x=$x)\" }\n    case (0, y) { \"Y-Axis (y=$y)\" }\n    case (x, y) { \"Somewhere else (x=$x, y=$y)\" }\n    case _ { \"Not a point\" }\n  }\n}\n```\n",
+  "mut": "`mut` 用于声明可变变量。\n\n---\n\n使用 `let` 语句时声明一个可变变量：\n\n```mira\nlet mut x = 1;\nx += 2;\n// x == 3\n```\n\n---\n\n在模式匹配中声明一个可变绑定：\n\n```mira\nlet (mut a, b) = (1, 2);\na += 10;\n// b += 10; // 这行代码会报错，因为 b 是不可变的\n```\n",
+  "nan": "`nan` 是一个特殊的 `number` 值（Not a Number）。它与任何值都不相等（包括它自己）。\n\n```mira\nnan == nan; // false\nnan =~ nan; // false\n```\n",
+  "nil": "`nil` 表示“空值”。当访问不存在的字段、对 `nil` 进行空安全链式调用等场景时，结果也会是 `nil`。\n\n```mira\nlet x = nil;\nlet y = x ?? 0;     // 0\nlet z = x.anything; // nil（空安全访问）\n```\n",
+  "not": "`not` 用于在模式匹配中取反一个模式，也可以作为 `!` 运算符的替代写法。\n\n---\n\n逻辑非模式：\n\n```mira\nfn is_not_weekend(day) {\n  day is not 6 and not 7\n}\n```\n\n---\n\n逻辑非运算符：\n\n```mira\nfn is_minor(age) {\n  // 等同于 !(age >= 18)\n  not (age >= 18)\n}\n```\n",
+  "or": "`or` 用于在模式匹配中组合多个模式，也可以作为 `||` 运算符的替代写法。\n\n---\n\n逻辑或模式：\n\n```mira\nfn is_weekend(day) {\n  day is 6 or 7\n}\n```\n\n---\n\n逻辑或运算符：\n\n```mira\nfn is_superuser(role) {\n  // 等同于 role == \"admin\" || role == \"superuser\"\n  role == \"admin\" or role == \"superuser\"\n}\n```\n",
+  "return": "`return` 用于从函数中返回值。\n\n```mira\nfn abs {\n  if it < 0 { return -it; }\n  return it;\n}\n```\n",
+  "true": "`true` 是布尔字面量，表示逻辑真。\n",
+  "type": "`type` 用于获得值的类型名字符串。\n\n```mira\ntype(1);       // \"number\"\nnil::type();   // \"nil\"（扩展调用写法）\n```\n",
+  "_": "`_` 是弃元关键字，用于在模式匹配中匹配并忽略任意值。\n\n```mira\nlet (_, y) = (1, 2); // y == 2\n\nfn head {\n  match it {\n    case [x, ..] { x }\n    case _ { nil }\n  }\n}\n```\n",
+  "while": "`while` 循环在条件为 `true` 时重复执行循环体。\n\n```mira\nlet mut i = 0;\nwhile i < 3 {\n  i += 1;\n}\n```\n",
+});
+export const OPERATORS = Object.freeze({
+  __proto__: null,
+  "=": "`=` 用于赋值。\n\n---\n\n声明时初始化：\n\n```mira\nlet x = 1;\nconst @y = 2;\n```\n\n---\n\n对可变变量/可写字段赋值：\n\n```mira\nlet mut x = 1;\nx = x + 1;\n```\n",
+  "*": "`*` 用于乘法。\n\n```mira\n2 * 3; // 6\n```\n",
+  "*=": "`*=` 是复合赋值，`x *= y` 等价于 `x = x * y`。\n\n```mira\nlet mut x = 2;\nx *= 3;\n// x == 6\n```\n",
+  "{": "`{ }` 用于表达式块或 JSON 风格记录字面量。\n\n---\n\n表达式块：\n\n```mira\nlet x = { 1 + 2 };\n```\n\n---\n\n在 JSON 风格记录字面量中，键名必须使用引号括起来：\n\n```mira\nlet obj = { \"x\": 1, \"y\": 2, \"n\": nil };\n```\n\n注意：\n\n- JSON 风格记录字面量不能为空，要声明一个空记录，请用 `()`；\n- 键和值仍为 MiraScript 表达式，因此需要使用 `nil` 来表示空值，而不是 `null`。\n",
+  "}": "`{ }` 用于表达式块或 JSON 风格记录字面量。\n\n---\n\n表达式块：\n\n```mira\nlet x = { 1 + 2 };\n```\n\n---\n\n在 JSON 风格记录字面量中，键名必须使用引号括起来：\n\n```mira\nlet obj = { \"x\": 1, \"y\": 2, \"n\": nil };\n```\n\n注意：\n\n- JSON 风格记录字面量不能为空，要声明一个空记录，请用 `()`；\n- 键和值仍为 MiraScript 表达式，因此需要使用 `nil` 来表示空值，而不是 `null`。\n",
+  "[": "`[ ]` 用于数组字面量、索引访问与切片。\n\n---\n\n数组字面量：\n\n```mira\nlet arr = [1, 2, 3];\n```\n\n---\n\n索引访问：\n\n```mira\nlet first = arr[0];\nlet last = arr[-1];\nlet value = record[\"key\"];\n```\n\n---\n\n数组切片：\n\n```mira\nlet subarr1 = arr[0..1];   // 取前两个元素\nlet subarr2 = arr[..<-1];  // 取到倒数第一个元素（不含）\n```\n",
+  "]": "`[ ]` 用于数组字面量、索引访问与切片。\n\n---\n\n数组字面量：\n\n```mira\nlet arr = [1, 2, 3];\n```\n\n---\n\n索引访问：\n\n```mira\nlet first = arr[0];\nlet last = arr[-1];\nlet value = record[\"key\"];\n```\n\n---\n\n数组切片：\n\n```mira\nlet subarr1 = arr[0..1];   // 取前两个元素\nlet subarr2 = arr[..<-1];  // 取到倒数第一个元素（不含）\n```\n",
+  "^": "`^` 用于乘方，结合性为从右到左。\n\n```mira\n2 ^ 3;     // 8\n2 ^ 3 ^ 2; // 2^(3^2)\n```\n",
+  "^=": "`^=` 是复合赋值，`x ^= y` 等价于 `x = x ^ y`。\n\n```mira\nlet mut x = 2;\nx ^= 3;\n// x == 8\n```\n",
+  ":": "`:` 用于记录字面量、条件表达式和插值格式。\n\n---\n\n在记录字面量中，`:` 用于分隔字段名和字段值。\n\n```mira\nlet r = (x: 1, y: 2);\n```\n\n---\n\n在条件表达式中，`:` 用于分隔条件的不同分支。\n\n```mira\nlet status = score >= 60 ? \"及格\" : \"不及格\";\n```\n\n---\n\n在插值格式中，`:` 用于指定格式化选项。在指定格式化选项时，必须使用圆括号 `$(expr:format)`。\n\n```mira\ndebug_print(\"π 的值约为 $(PI:.2)\"); // 输出: π 的值约为 3.14\n```\n",
+  "::": "`::` 用于扩展调用。\n\n```mira\n\"Hello\"::chars()::join(\"\");\n// 相当于 join(chars(\"Hello\"), \"\");\n```\n",
+  ",": "`,` 用于分隔参数、数组元素、记录字段等。\n\n```mira\nlet arr = [1, 2, 3];\nlet r = (a: 1, b: 2);\n\nfn f(a, b, c) { a + b + c }\nf(1, 2, 3);\n```\n",
+  ".": "`.` 用于成员访问。\n\n```mira\nlet r = (a: 1);\nr.a; // 1\nr.b; // nil\n\nlet arr = [10, 20];\narr.0; // 10\narr.2; // nil\n```\n",
+  "==": "使用 `==` 运算符可以比较两个值是否严格相等。\n\n---\n\n对于原始值，如果它们的类型和值都相同，则认为它们相等。\n\n```mira\n5 == 5;            // true\n\"hello\" == \"hello\"; // true\ntrue == true;      // true\n5 == \"5\";         // false\n```\n\n特别地，对于 `number` 类型的值 `nan`，它与任何值都不相等，包括它自己。\n\n```mira\nnan == nan; // false\n```\n\n---\n\n对于 `array` 和 `record`，只有他们的元素和属性都相等时，才认为它们相等。\n\n```mira\n[1, 2, 3] == [1, 2, 3]; // true\n(a: 1, b: 2) == (a: 1, b: 2); // true\n[1, 2, 3] == [1, 2, 4]; // false\n```\n\n---\n\n对于 `function` `module` 和 `extern`，只有它们引用的是同一个对象时，才认为它们相等。\n\n```mira\nlet fn1 = fn() { return 1; };\nlet fn2 = fn() { return 1; };\nfn1 == fn1; // true\nfn1 == fn2; // false\n```\n",
+  "!": "`!` 既可以作为前缀逻辑非，也可以作为后缀非空断言。\n\n---\n\n逻辑非：\n\n```mira\n!x // x 必须是 boolean\n```\n\n---\n\n非空断言：\n\n```mira\n\nlet x = nil;\nx!; // panic\n```\n",
+  ">": "`>` 用于“大于”比较。\n\n```mira\n2 > 1;     // true\n\"b\" > \"a\"; // true\n```\n",
+  ">=": "`>=` 用于“大于等于”比较。\n\n```mira\n2 >= 2; // true\n```\n",
+  "..<": "`..<` 表示右开区间范围，包含起点，不包含终点。\n\n```mira\n[1..<3]; // [1, 2]\n\nlet arr = [10, 20, 30, 40];\narr[1..<3]; // [20, 30]\n```\n",
+  "<": "`<` 用于“小于”比较。\n\n```mira\n1 < 2; // true\n```\n",
+  "<=": "`<=` 用于“小于等于”比较。\n\n```mira\n2 <= 2; // true\n```\n",
+  "&&": "`&&` 是短路逻辑与，操作数必须是 `boolean`。\n\n```mira\nfalse && (1 / 0); // 右侧不会被求值\n```\n",
+  "&&=": "`&&=` 是短路复合赋值，只有当左侧为 `true` 时才会计算并赋值右侧。\n\n```mira\nlet mut b = true;\nb &&= false;\n// b == false\n```\n",
+  "||": "`||` 是短路逻辑或，操作数必须是 `boolean`。\n\n```mira\ntrue || (1 / 0); // 右侧不会被求值\n```\n",
+  "||=": "`||=` 是短路复合赋值，只有当左侧为 `false` 时才会计算并赋值右侧。\n\n```mira\nlet mut b = false;\nb ||= true;\n// b == true\n```\n",
+  "-": "`-` 用于减法（中缀）或一元负号（前缀）。\n\n```mira\n5 - 2; // 3\n-1;    // -1\n```\n",
+  "-=": "`-=` 是复合赋值，`x -= y` 等价于 `x = x - y`。\n\n```mira\nlet mut x = 3;\nx -= 1;\n// x == 2\n```\n",
+  "!=": "`!=` 判断两个值是否不相等，等价于 `!(x == y)`。\n\n```mira\n1 != 2; // true\n1 != 1; // false\n```\n",
+  "??": "`??` 是空合并，当左侧为 `nil` 时返回右侧，否则返回左侧。\n\n```mira\nnil ?? 1; // 1\n0 ?? 1;   // 0\n```\n",
+  "??=": "`??=` 是空合并复合赋值，仅当左侧为 `nil` 时才会赋值右侧。\n\n```mira\nlet mut n = nil;\nn ??= 5;\n// n == 5\n\nn ??= 10;\n// n 仍然是 5\n```\n",
+  "(": "`( )` 用于分组表达式、函数调用参数列表，以及记录字面量。\n\n---\n\n分组表达式，控制计算顺序：\n\n```mira\nlet result = (1 + 2) * 3; // 先计算 1 + 2，然后乘以 3\n```\n\n---\n\n函数声明和调用：\n\n```mira\nfn add(a, b) { a + b }\nlet sum = add(1, 2);\n```\n\n---\n\n记录字面量：\n\n```mira\nlet record = (a: 1, b: 2);\nlet empty = (); // 空记录\n```\n\n---\n\n对于省略键名的单元素记录，必须添加逗号以区别于分组表达式。\n\n```mira\nlet single = (1,)\n```\n",
+  ")": "`( )` 用于分组表达式、函数调用参数列表，以及记录字面量。\n\n---\n\n分组表达式，控制计算顺序：\n\n```mira\nlet result = (1 + 2) * 3; // 先计算 1 + 2，然后乘以 3\n```\n\n---\n\n函数声明和调用：\n\n```mira\nfn add(a, b) { a + b }\nlet sum = add(1, 2);\n```\n\n---\n\n记录字面量：\n\n```mira\nlet record = (a: 1, b: 2);\nlet empty = (); // 空记录\n```\n\n---\n\n对于省略键名的单元素记录，必须添加逗号以区别于分组表达式。\n\n```mira\nlet single = (1,)\n```\n",
+  "%": "`%` 用于取余。\n\n```mira\n5 % 2; // 1\n```\n",
+  "%=": "`%=` 是复合赋值：`x %= y` 等价于 `x = x % y`。\n\n```mira\nlet mut x = 5;\nx %= 2;\n// x == 1\n```\n",
+  "+": "`+` 用于加法（中缀）或一元正号（前缀）。\n\n```mira\n1 + 2; // 3\n+1;    // 1\n```\n",
+  "+=": "`+=` 是复合赋值，`x += y` 等价于 `x = x + y`。\n\n```mira\nlet mut x = 1;\nx += 2;\n// x == 3\n```\n",
+  "?": "`?` 用于条件表达式（三元表达式）：`cond ? thenExpr : elseExpr`。\n\n```mira\nfn sign { it > 0 ? 1 : it < 0 ? -1 : 0 }\n```\n",
+  "?:": "`?:` 用于记录字面量的“可选字段”，当值为 `nil` 时省略该字段。\n\n```mira\n(a?: 1, b?: nil); // (a: 1)\n\n// 省略不会删除已经通过展开引入的同名字段\n(..(a: 1), a?: nil); // (a: 1)\n```\n",
+  ";": "`;` 用于结束语句。MiraScript 以表达式为主，但在多语句块中常用 `;` 分隔。\n\n```mira\nlet sum = {\n  let x = 1;\n  let y = 2;\n  x + y\n};\n```\n",
+  "/": "`/` 用于除法。\n\n```mira\n6 / 3; // 2\n```\n",
+  "/=": "`/=` 是复合赋值，`x /= y` 等价于 `x = x / y`。\n\n```mira\nlet mut x = 6;\nx /= 3;\n// x == 2\n```\n",
+  "..": "`..` 表示闭区间范围，或在数组/记录字面量及函数调用中表示展开。\n\n---\n\n表示数组字面量、切片和循环的范围：\n\n```mira\nlet arr = [1..3]; // arr = [1, 2, 3]\nlet slice = arr[0..1]; // slice = [1, 2]\n\nfor i in 1..3 {\n  // i 依次为 1, 2, 3\n}\n```\n\n---\n\n展开数组/记录或函数调用：\n\n```mira\nlet arr = [1, ..[2, 3]]; // arr = [1, 2, 3]\nlet rec1 = (a: 1, ..(b: 2, c: 3)); // rec1 = (a: 1, b: 2, c: 3)\n// 同名键以最后一个为准\nlet rec2 = (..(1, 2), ..(3, 4, 5)); // rec2 = (0: 3, 1: 4, 2: 5)\n\nlet result = sum(..[1, 2, 3]); // 等同于 sum(1, 2, 3)\n```\n",
+  "=~": "`=~` 是“近似相等”，用于数值容差比较和字符串归一化比较。\n\n---\n\n对于 `number` 类型，当两个操作数的相对误差**或**绝对误差小于 `1e-15` 时，返回 `true`，否则返回 `false`。\n\n如果其中一个操作数为 `number` 类型，另一个操作数在比较前也会自动转换为 `number` 类型。\n\n```mira\n0.1 + 0.2 =~ 0.3; // true\n1 =~ \"1\";        // true\n```\n\n---\n\n对于 `string` 类型，`=~` 运算符进行大小写不敏感的[正规化（NFC）](https://unicode.org/reports/tr15/)比较。\n\n```mira\n\"café\" =~ \"CAFÉ\"; // true\n```\n",
+  "!~": "`!~` 是 `=~` 的否定形式（不近似相等）。\n\n```mira\n1 !~ 2;     // true\n\"a\" !~ \"A\"; // false\n```\n",
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@mirascript/help",
+  "version": "0.1.40",
+  "author": "CloudPSS",
+  "license": "MIT",
+  "description": "Help documentation for Mirascript core language.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "js-yaml": "^4.1.1"
+  },
+  "scripts": {
+    "build": "pnpm clean && node ./scripts/build.js",
+    "clean": "rimraf dist"
+  }
+}

package/scripts/build.js

@@ -0,0 +1,165 @@
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { load } from 'js-yaml';
+
+const packageRoot = path.resolve(import.meta.dirname, '..');
+const srcRoot = path.join(packageRoot, 'src');
+const distRoot = path.join(packageRoot, 'dist');
+
+/**
+ * Front-matter driven docs.
+ *
+ * Each markdown file under `src/keyword` and `src/operator` must have:
+ *
+ * ---
+ * token: "..."   # actual token used in source code
+ * ---
+ */
+
+/**
+ * Read a markdown file under `src/`.
+ * @param {string} relativePath
+ * @returns {Promise<string>}
+ */
+async function readMarkdown(relativePath) {
+    const fullPath = path.join(srcRoot, relativePath);
+    return readFile(fullPath, 'utf8');
+}
+
+const FRONT_MATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/;
+
+/**
+ * Extract front-matter and strip it from markdown.
+ * @param {string} markdown
+ * @param {string} relativePath
+ * @returns {{ attributes: Record<string, unknown>, body: string }}
+ */
+function splitFrontMatter(markdown, relativePath) {
+    const m = FRONT_MATTER_RE.exec(markdown);
+    if (!m) {
+        throw new Error(`Missing front-matter in ${relativePath}. Add token/order mapping.`);
+    }
+
+    const attributes = load(m[1]);
+    let body = markdown.slice(m[0].length);
+    // Trim leading newlines and tailing newlines
+    body = body.replace(/^\r?\n+/, '').replace(/\r?\n+$/, '') + '\n';
+    return { attributes, body };
+}
+
+/**
+ * Load docs under a folder like `keyword` or `operator`.
+ * @param {string} folder
+ * @returns {Promise<Array<[string, string]>>}
+ */
+async function loadDocsFromFolder(folder) {
+    const dirPath = path.join(srcRoot, folder);
+    const dirents = await readdir(dirPath, { withFileTypes: true });
+
+    /** @type {Array<{ token: string; order: number; body: string; file: string }>} */
+    const items = [];
+
+    /**
+     * Check and add an item.
+     * @param {{ token: string | string[]; body: string; reserved: boolean; file: string }} item
+     */
+    function putItem(item) {
+        if (Array.isArray(item.token)) {
+            for (const token of item.token) {
+                items.push({ token, body: item.body, reserved: item.reserved, file: item.file });
+            }
+            return;
+        }
+        if (typeof item.token != 'string' || !item.token.length) {
+            throw new TypeError(`Invalid front-matter field 'token' in ${item.file}`);
+        }
+        if (item.reserved) {
+            return; // skip reserved tokens
+        }
+        items.push(item);
+    }
+
+    for (const dirent of dirents) {
+        if (!dirent.isFile()) continue;
+        if (!dirent.name.endsWith('.md')) continue;
+
+        const relativePath = path.posix.join(folder, dirent.name);
+        const markdown = await readMarkdown(relativePath);
+        const { attributes, body } = splitFrontMatter(markdown, relativePath);
+        const { token, reserved } = attributes;
+        putItem({ token, body, reserved: Boolean(reserved), file: relativePath });
+    }
+
+    const seenToken = new Set();
+    /** @type {Array<[string, string]>} */
+    const entries = [];
+    for (const item of items) {
+        if (seenToken.has(item.token)) {
+            throw new Error(`Duplicate token '${item.token}' (found in ${item.file})`);
+        }
+        seenToken.add(item.token);
+        entries.push([item.token, item.body]);
+    }
+
+    return entries;
+}
+
+/**
+ * Render an object literal with string keys and raw markdown values.
+ * @param {Array<[string, string]>} entries
+ * @returns {string}
+ */
+function renderObjectLiteral(entries) {
+    const lines = entries.map(([k, v]) => `  ${JSON.stringify(k)}: ${JSON.stringify(v)},`);
+    lines.unshift('  __proto__: null,');
+    return `Object.freeze({\n${lines.join('\n')}\n})`;
+}
+
+/**
+ * Render a `.d.ts` object type with explicit string-literal keys.
+ * @param {Array<[string, string]>} entries
+ * @returns {string}
+ */
+function renderDtsObjectType(entries) {
+    const lines = entries.map(([k]) => `  readonly ${JSON.stringify(k)}: string;`);
+    return `{\n${lines.join('\n')}\n}`;
+}
+
+/**
+ * Build `dist/index.js` and `dist/index.d.ts`.
+ * @returns {Promise<void>}
+ */
+async function main() {
+    const keywordEntries = await loadDocsFromFolder('keyword');
+    const operatorEntries = await loadDocsFromFolder('operator');
+
+    await mkdir(distRoot, { recursive: true });
+
+    const js = [
+        '/* Generated by scripts/build.js. Do not edit manually. */',
+        '',
+        `export const KEYWORDS = ${renderObjectLiteral(keywordEntries)};`,
+        `export const OPERATORS = ${renderObjectLiteral(operatorEntries)};`,
+        '',
+    ].join('\n');
+
+    const dts = [
+        '/* Generated by scripts/build.js. Do not edit manually. */',
+        '',
+        `export declare const KEYWORDS: ${renderDtsObjectType(keywordEntries)};`,
+        `export declare const OPERATORS: ${renderDtsObjectType(operatorEntries)};`,
+        '',
+        'export type Keyword = keyof typeof KEYWORDS;',
+        'export type Operator = keyof typeof OPERATORS;',
+        '',
+    ].join('\n');
+
+    await writeFile(path.join(distRoot, 'index.js'), js, 'utf8');
+    await writeFile(path.join(distRoot, 'index.d.ts'), dts, 'utf8');
+}
+
+main().catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error(err);
+    process.exitCode = 1;
+});

package/src/keyword/and.md

@@ -0,0 +1,26 @@
+---
+token: 'and'
+---
+
+`and` 用于在模式匹配中组合多个模式，也可以作为 `&&` 运算符的替代写法。
+
+---
+
+逻辑与模式：
+
+```mira
+fn is_month(month) {
+  month is >= 1 and <= 12
+}
+```
+
+---
+
+逻辑与运算符：
+
+```mira
+fn is_adult(age) {
+  // 等同于 age >= 18 && age <= 65
+  age >= 18 and age <= 65
+}
+```

package/src/keyword/break.md

@@ -0,0 +1,32 @@
+---
+token: 'break'
+---
+
+`break` 用于提前退出 `for` / `while` / `loop`。
+
+---
+
+基本用法
+
+```mira
+let mut i = 0;
+loop {
+  i += 1;
+  break;
+}
+```
+
+---
+
+从循环中返回一个值
+
+```mira
+let mut i = 0;
+let result = loop {
+  i += 1;
+  if i == 10 {
+    break i * 2;
+  }
+};
+// result 的值是 20
+```

package/src/keyword/case.md

@@ -0,0 +1,16 @@
+---
+token: 'case'
+---
+
+`case` 是 `match` 表达式中的分支。
+
+```mira
+fn age_group(age) {
+  match age {
+    case 0..12 { "child"}
+    case 13..19 { "teenager" }
+    case 20..64 { "adult" }
+    case _ { "senior" }
+  }
+}
+```

package/src/keyword/const.md

@@ -0,0 +1,10 @@
+---
+token: 'const'
+---
+
+`const` 用于声明常量。常量名必须以 `@` 开头。
+
+```mira
+const @PI = 3.14159;
+// @PI = 0; // 错误：常量不可重新赋值
+```

package/src/keyword/continue.md

@@ -0,0 +1,14 @@
+---
+token: 'continue'
+---
+
+`continue` 用于跳过本次循环剩余部分，进入下一次循环。
+
+```mira
+let mut sum = 0;
+for i in 1..5 {
+  if i % 2 == 0 { continue; }
+  sum += i;
+}
+// sum == 1 + 3 + 5
+```

package/src/keyword/effect.md

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

package/src/keyword/else.md

@@ -0,0 +1,32 @@
+---
+token: 'else'
+---
+
+`else` 用于 `if` 表达式，也可用作 `while` 和 `for` 循环的可选分支。
+
+---
+
+作为 `if` 表达式的分支
+
+```mira
+let x = if false { 1 } else { 2 }; // 2
+```
+
+---
+
+作为循环的可选分支
+
+```mira
+let mut i = 0;
+let result = while i < 5 {
+  i += 1;
+  if i == 6 {
+    // 使用 break 语句提前退出循环，并返回一个值
+    break i * 2;
+  }
+} else {
+  // 当循环正常结束时执行
+  100
+};
+// result 的值是 100
+```

package/src/keyword/false.md

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

package/src/keyword/finally.md

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

package/src/keyword/fn.md

@@ -0,0 +1,35 @@
+---
+token: 'fn'
+---
+
+使用 `fn` 关键字定义一个函数或函数表达式。
+
+---
+
+定义一个简单的函数：
+
+```mira
+fn add(a, b) {
+  return a + b;
+}
+```
+
+---
+
+定义一个变量，并使用函数表达式初始化：
+
+```mira
+let multiply = fn(x, y) {
+  return x * y;
+};
+```
+
+---
+
+当函数只有一个参数时，可以省略括号，并用 `it` 引用该参数。
+
+```mira
+fn square {
+  return it * it;
+}
+```

package/src/keyword/for.md

@@ -0,0 +1,43 @@
+---
+token: 'for'
+---
+
+`for` 用于遍历可迭代对象。
+
+---
+
+遍历一个范围：
+
+```mira
+let mut sum = 0;
+for i in 1..3 { // 或者 1..<4
+  sum += i;
+}
+// sum == 6
+```
+
+---
+
+遍历一个数组：
+
+```mira
+let arr = [10, 20, 30];
+let mut sum = 0;
+for value in arr {
+  sum += value;
+}
+// sum == 60
+```
+
+---
+
+遍历一个记录：
+
+```mira
+let record = (a: 1, b: 2, c: 3);
+let mut sum = 0;
+for key in record {
+  sum += record[key];
+}
+// sum == 6
+```

package/src/keyword/global.md

@@ -0,0 +1,16 @@
+---
+token: 'global'
+---
+
+`global` 表示全局对象（全局命名空间）。通常用于读取全局变量或判断某个全局键是否存在。
+
+```mira
+// 访问全局变量
+global.some_name;
+
+// 动态访问全局变量
+global['some_name'];
+
+// 判断键是否存在
+'some_name' in global;
+```

package/src/keyword/handle.md

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

package/src/keyword/if.md

@@ -0,0 +1,40 @@
+---
+token: 'if'
+---
+
+`if` 用于 `if` 表达式或 `match` 表达式的守卫条件。
+
+---
+
+`if` 表达式根据条件选择分支。条件必须是 `boolean`。
+
+```mira
+let x = if 1 > 0 { "pos" } else { "neg" };
+```
+
+---
+
+使用 `else if` 添加多个条件分支：
+
+```mira
+let x = if 1 > 2 {
+  "greater"
+} else if 1 == 2 {
+  "equal"
+} else {
+  "less"
+};
+```
+
+---
+
+在 `match` 表达式中使用 `if` 作为守卫条件：
+
+```mira
+let num = 10;
+let result = match num {
+  case n if n % 2 == 0 { "even" }
+  case n { "odd" }
+};
+// result 的值是 "even"
+```