@mirascript/help 0.1.44 → 0.1.45

package/dist/index.d.ts

@@ -18,11 +18,13 @@ export declare const KEYWORDS: {
   readonly "let": string;
   readonly "loop": string;
   readonly "match": string;
+  readonly "mod": string;
   readonly "mut": string;
   readonly "nan": string;
   readonly "nil": string;
   readonly "not": string;
   readonly "or": string;
+  readonly "pub": string;
   readonly "return": string;
   readonly "true": string;
   readonly "type": string;

package/dist/index.js

@@ -19,11 +19,13 @@ export const KEYWORDS = Object.freeze({
   "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",
+  "mod": "`mod` 用于声明一个模块。\n\n```mira\nmod counter {\n  pub let mut value = 0;\n  pub fn inc(){\n    value += 1;\n  }\n}\n\ndebug_print(counter.value); // 0\ncounter.inc();\ndebug_print(counter.value); // 1\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",
+  "pub": "`pub` 用于将模块内的声明导出。\n\n```mira\nmod counter {\n  pub let mut value = 0;\n  pub fn inc(){\n    value += 1;\n  }\n}\n\ndebug_print(counter.value); // 0\ncounter.inc();\ndebug_print(counter.value); // 1\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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mirascript/help",
-  "version": "0.1.44",
+  "version": "0.1.45",
   "author": "CloudPSS",
   "license": "MIT",
   "description": "Help documentation for Mirascript core language.",

package/scripts/build.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { load } from 'js-yaml';
 
 const packageRoot = path.resolve(import.meta.dirname, '..');
-const srcRoot = path.join(packageRoot, 'src');
+const srcRoot = path.join(packageRoot, '../../docs/references');
 const distRoot = path.join(packageRoot, 'dist');
 
 /**
@@ -86,8 +86,8 @@ async function loadDocsFromFolder(folder) {
         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 { token, title, reserved } = attributes;
+        putItem({ token: token ?? title, body, reserved: Boolean(reserved), file: relativePath });
     }
 
     const seenToken = new Set();

package/src/keyword/and.md

@@ -1,26 +0,0 @@
----
-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

@@ -1,32 +0,0 @@
----
-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

@@ -1,16 +0,0 @@
----
-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

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

package/src/keyword/continue.md

@@ -1,14 +0,0 @@
----
-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

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

package/src/keyword/else.md

@@ -1,32 +0,0 @@
----
-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

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

package/src/keyword/finally.md

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

package/src/keyword/fn.md

@@ -1,35 +0,0 @@
----
-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

@@ -1,43 +0,0 @@
----
-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

@@ -1,29 +0,0 @@
----
-token: 'global'
----
-
-`global` 关键字用于读取全局变量或判断某个全局变量是否存在。
-
----
-
-当变量名与局部变量冲突时，可以使用 `global` 关键字来访问全局变量。
-
-```mira
-let some_name = 'shadow';
-some_name; // 访问局部变量 'some_name'
-global.some_name; // 访问全局变量 'some_name'
-```
-
----
-
-动态判断和访问全局变量：
-
-```mira
-fn get_global(name, fallback) {
-  if name in global {
-    global[name]
-  } else {
-    fallback
-  }
-}
-```

package/src/keyword/handle.md

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

package/src/keyword/if.md

@@ -1,40 +0,0 @@
----
-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"
-```

package/src/keyword/in.md

@@ -1,44 +0,0 @@
----
-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

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

package/src/keyword/is.md

@@ -1,11 +0,0 @@
----
-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

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

package/src/keyword/loop.md

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

package/src/keyword/match.md

@@ -1,18 +0,0 @@
----
-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

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

package/src/keyword/mut.md

@@ -1,25 +0,0 @@
----
-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

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

package/src/keyword/nil.md

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

package/src/keyword/not.md

@@ -1,26 +0,0 @@
----
-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

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

package/src/keyword/or.md

@@ -1,26 +0,0 @@
----
-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

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

package/src/keyword/pub.md

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

package/src/keyword/resume.md

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

package/src/keyword/return.md

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

package/src/keyword/true.md

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

package/src/keyword/try.md

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

package/src/keyword/type.md

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