feat: implement mdr frontend semantics and examples

Author: Minsecrus

.gitignore

@@ -91,6 +91,7 @@ dist
 examples-temp
 *.timestamp-*.mjs
 /.vitepress/
+code/项目/Mdr_Lang/compiler_c/build/
 
 # linter&formatter
 .cpp-linter_cache

code/项目/Mdr_Lang/compiler/README.md

@@ -0,0 +1,53 @@
+# Mdr Lang 编译器（起步版）
+
+这个目录提供了一个可运行的前端原型，当前阶段完成了：
+
+1. 词法分析（Token 流）。
+2. 语法分析（AST）。
+3. 命令行入口。
+
+## 目录结构
+
+```text
+compiler/
+  cli.mjs
+  src/
+    compiler.mjs
+    error.mjs
+    lexer.mjs
+    parser.mjs
+    token.mjs
+  tests/
+    smoke.mjs
+```
+
+## 用法
+
+```bash
+node code/项目/Mdr_Lang/compiler/cli.mjs docs/教程/正文/项目/Mdr_Lang/example/vec2.mdr
+```
+
+输出 AST 到文件：
+
+```bash
+node code/项目/Mdr_Lang/compiler/cli.mjs docs/教程/正文/项目/Mdr_Lang/example/range_step.mdr --out temp/range_step.ast.json
+```
+
+同时打印 Token：
+
+```bash
+node code/项目/Mdr_Lang/compiler/cli.mjs docs/教程/正文/项目/Mdr_Lang/example/range_step.mdr --tokens
+```
+
+## 已覆盖的核心语法
+
+1. 顶层：`use`、`struct`、`function`。
+2. 语句：`let` / `const`、`if` / `else`、`while`、`loop`、`for`、`return`、`break`、`continue`、赋值语句、表达式语句。
+3. 表达式：逻辑运算、比较、四则、前缀一元、成员访问、函数调用、元组字面量、数组字面量、`this`、`null`。
+4. 范围表达式：`a..b`、`a...b`、`a..b..s`、`a...b..s`。
+
+## 下一步建议
+
+1. 在 AST 之后加入语义分析（名称解析、类型检查）。
+2. 设计中间表示（IR）。
+3. 先实现解释执行，再接入机器码后端或 C 后端。

code/项目/Mdr_Lang/compiler/cli.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+import { compileSource } from "./src/compiler.mjs";
+import { MdrCompileError } from "./src/error.mjs";
+
+const args = process.argv.slice(2);
+const options = {
+  inputPath: "",
+  astOutPath: "",
+  dumpTokens: false,
+};
+
+if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+  printUsage();
+  process.exit(args.length === 0 ? 1 : 0);
+}
+
+for (let i = 0; i < args.length; i += 1) {
+  const arg = args[i];
+  if (arg === "--tokens") {
+    options.dumpTokens = true;
+    continue;
+  }
+  if (arg === "--out") {
+    const next = args[i + 1];
+    if (next == null) {
+      console.error("missing output path after --out");
+      process.exit(1);
+    }
+    options.astOutPath = next;
+    i += 1;
+    continue;
+  }
+  if (arg.startsWith("-")) {
+    console.error(`unknown option: ${arg}`);
+    process.exit(1);
+  }
+  if (options.inputPath !== "") {
+    console.error("only one input file is supported");
+    process.exit(1);
+  }
+  options.inputPath = arg;
+}
+
+if (options.inputPath === "") {
+  console.error("missing input file");
+  printUsage();
+  process.exit(1);
+}
+
+const absoluteInput = path.resolve(options.inputPath);
+const source = fs.readFileSync(absoluteInput, "utf8");
+
+try {
+  const { tokens, ast } = compileSource(source, absoluteInput);
+  const astJson = JSON.stringify(ast, null, 2);
+  if (options.astOutPath !== "") {
+    const outPath = path.resolve(options.astOutPath);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, `${astJson}\n`, "utf8");
+  } else {
+    process.stdout.write(`${astJson}\n`);
+  }
+
+  if (options.dumpTokens) {
+    process.stdout.write(`${JSON.stringify(tokens, null, 2)}\n`);
+  }
+} catch (error) {
+  if (error instanceof MdrCompileError) {
+    printCompileError(error, source);
+    process.exit(1);
+  }
+  throw error;
+}
+
+function printUsage() {
+  process.stdout.write("Usage: node cli.mjs <input.mdr> [--out <file>] [--tokens]\n");
+}
+
+/**
+ * @param {MdrCompileError} error
+ * @param {string} source
+ */
+function printCompileError(error, source) {
+  const lines = source.split(/\r?\n/u);
+  const lineText = lines[error.line - 1] ?? "";
+  const pointer = `${" ".repeat(Math.max(error.column - 1, 0))}^`;
+
+  console.error(`${error.filePath}:${error.line}:${error.column}: ${error.message}`);
+  console.error(lineText);
+  console.error(pointer);
+}

code/项目/Mdr_Lang/compiler/src/compiler.mjs

@@ -0,0 +1,12 @@
+import { tokenize } from "./lexer.mjs";
+import { parse } from "./parser.mjs";
+
+/**
+ * @param {string} source
+ * @param {string} filePath
+ */
+export function compileSource(source, filePath) {
+  const tokens = tokenize(source, filePath);
+  const ast = parse(tokens, filePath);
+  return { tokens, ast };
+}

code/项目/Mdr_Lang/compiler/src/error.mjs

@@ -0,0 +1,17 @@
+export class MdrCompileError extends Error {
+  /**
+   * @param {string} message
+   * @param {{
+   *   filePath: string;
+   *   line: number;
+   *   column: number;
+   * }} options
+   */
+  constructor(message, options) {
+    super(message);
+    this.name = "MdrCompileError";
+    this.filePath = options.filePath;
+    this.line = options.line;
+    this.column = options.column;
+  }
+}