ic10c-node 2.6.6

package/types/lexer/token.d.ts

@@ -0,0 +1,341 @@
+// Copyright (c) 2026. All rights reserved.
+// This source code is licensed under the CC BY-NC-SA
+// (Creative Commons Attribution-NonCommercial-NoDerivatives) License, By Xiao Songtao.
+// This software is protected by copyright law. Reproduction, distribution, or use for commercial
+// purposes is prohibited without the author's permission. If you have any questions or require
+// permission, please contact the author: edocsitahw@qq.com
+
+/**
+ * @file token.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/07/22 15:36
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+import {Pos} from "../common";
+
+
+/**
+ * IC10 词法标记类型枚举。
+ *
+ * 对应 C++ `ic10::TokenType`，值从 0 开始递增。
+ * 运行时由原生模块导出为不可变对象，可在 JS 层直接使用 `TokenType.FLOAT` 等访问。
+ *
+ * @public
+ */
+export enum TokenType {
+    /* 数字 */
+    INTEGER = 0,
+    FLOAT,
+    HEX_NUMBER,
+    BINARY_NUMBER,
+    STRING,
+
+    /* 变量名 */
+    IDENTIFIER,
+
+    /* 寄存器设备 */
+    REGISTER,
+    DEVICE,
+
+    /* 符号 */
+    LPAREN,
+    RPAREN,
+    COLON,
+
+    /* 注释 */
+    HEX_COMMENT,
+    SLASH_COMMENT,
+    DOC_COMMENT,
+    TYPE_HINT,
+
+    /* 换行 */
+    NEWLINE,
+
+    /* 关键字 - 宏与函数 */
+    KEYWORD_HASH,
+    KEYWORD_STR,
+
+    /* 关键字 - 常量 */
+    KEYWORD_NAN,
+    KEYWORD_PINF,
+    KEYWORD_NINF,
+    KEYWORD_PI,
+    KEYWORD_TAU,
+    KEYWORD_DEG2RAD,
+    KEYWORD_RAD2DEG,
+    KEYWORD_EPSILON,
+    KEYWORD_RGAS,
+
+    /* 文件结束标记 */
+    END,
+
+    /* 未知标记 */
+    UNKNOWN,
+
+    /* 关键字 - 空指令 */
+    KEYWORD_HCF,
+    KEYWORD_YIELD,
+
+    /* 关键字 - 预处理指令 */
+    KEYWORD_ALIAS,
+    KEYWORD_DEFINE,
+
+    /* 关键字 - 一元指令 */
+    KEYWORD_PEEK,
+    KEYWORD_POP,
+    KEYWORD_PUSH,
+    KEYWORD_CLR,
+    KEYWORD_J,
+    KEYWORD_JAL,
+    KEYWORD_JR,
+    KEYWORD_RAND,
+    KEYWORD_SLEEP,
+    KEYWORD_CLRD,
+
+    /* 关键字 - 二元指令 */
+    KEYWORD_ABS,
+    KEYWORD_ACOS,
+    KEYWORD_ADD,
+    KEYWORD_ASIN,
+    KEYWORD_ATAN,
+    KEYWORD_ATAN2,
+    KEYWORD_CEIL,
+    KEYWORD_COS,
+    KEYWORD_DIV,
+    KEYWORD_EXP,
+    KEYWORD_FLOOR,
+    KEYWORD_LOG,
+    KEYWORD_MAX,
+    KEYWORD_MIN,
+    KEYWORD_MOD,
+    KEYWORD_MUL,
+    KEYWORD_POW,
+    KEYWORD_ROUND,
+    KEYWORD_SIN,
+    KEYWORD_SQRT,
+    KEYWORD_SGN,
+    KEYWORD_SUB,
+    KEYWORD_TAN,
+    KEYWORD_TRUNC,
+    KEYWORD_NOT,
+    KEYWORD_MOVE,
+    KEYWORD_POKE,
+    KEYWORD_BEQZ,
+    KEYWORD_BEQZAL,
+    KEYWORD_BNEZ,
+    KEYWORD_BNEZAL,
+    KEYWORD_BGEZ,
+    KEYWORD_BGEZAL,
+    KEYWORD_BGTZ,
+    KEYWORD_BGTZAL,
+    KEYWORD_BLEZ,
+    KEYWORD_BLEZAL,
+    KEYWORD_BLTZ,
+    KEYWORD_BLTZAL,
+    KEYWORD_BNAN,
+    KEYWORD_BDNS,
+    KEYWORD_BDNSAL,
+    KEYWORD_BDSE,
+    KEYWORD_BDSEAL,
+    KEYWORD_BREQZ,
+    KEYWORD_BRNEZ,
+    KEYWORD_BRGEZ,
+    KEYWORD_BRGTZ,
+    KEYWORD_BRLEZ,
+    KEYWORD_BRLTZ,
+    KEYWORD_BRNAN,
+    KEYWORD_BRDNS,
+    KEYWORD_BRDSE,
+    KEYWORD_SEQZ,
+    KEYWORD_SNEZ,
+    KEYWORD_SGEZ,
+    KEYWORD_SGTZ,
+    KEYWORD_SLEZ,
+    KEYWORD_SLTZ,
+    KEYWORD_SNAN,
+    KEYWORD_SNANZ,
+    KEYWORD_SDNS,
+    KEYWORD_SDSE,
+
+    /* 关键字 - 三元指令 */
+    KEYWORD_AND,
+    KEYWORD_NOR,
+    KEYWORD_OR,
+    KEYWORD_SLA,
+    KEYWORD_SLL,
+    KEYWORD_SRA,
+    KEYWORD_SRL,
+    KEYWORD_XOR,
+    KEYWORD_GET,
+    KEYWORD_PUT,
+    KEYWORD_L,
+    KEYWORD_LS,
+    KEYWORD_LR,
+    KEYWORD_S,
+    KEYWORD_SB,
+    KEYWORD_ROL,
+    KEYWORD_ROR,
+    KEYWORD_RMAP,
+    KEYWORD_BEQ,
+    KEYWORD_BEQAL,
+    KEYWORD_BNE,
+    KEYWORD_BNEAL,
+    KEYWORD_BGE,
+    KEYWORD_BGEAL,
+    KEYWORD_BGT,
+    KEYWORD_BGTAL,
+    KEYWORD_BLE,
+    KEYWORD_BLEAL,
+    KEYWORD_BLT,
+    KEYWORD_BLTAL,
+    KEYWORD_BAPZ,
+    KEYWORD_BAPZAL,
+    KEYWORD_BNAZ,
+    KEYWORD_BNAZAL,
+    KEYWORD_BDNVL,
+    KEYWORD_BDNVS,
+    KEYWORD_BREQ,
+    KEYWORD_BRNE,
+    KEYWORD_BRGE,
+    KEYWORD_BRGT,
+    KEYWORD_BRLE,
+    KEYWORD_BRLT,
+    KEYWORD_BRAPZ,
+    KEYWORD_BRNAZ,
+    KEYWORD_SAPZ,
+    KEYWORD_SNAZ,
+    KEYWORD_SEQ,
+    KEYWORD_SNE,
+    KEYWORD_SGE,
+    KEYWORD_SGT,
+    KEYWORD_SLE,
+    KEYWORD_SLT,
+
+    /* 关键字 - 四元指令 */
+    KEYWORD_LERP,
+    KEYWORD_CLAMP,
+    KEYWORD_EXT,
+    KEYWORD_INS,
+    KEYWORD_SS,
+    KEYWORD_LB,
+    KEYWORD_SBN,
+    KEYWORD_SBS,
+    KEYWORD_BAP,
+    KEYWORD_BAPAL,
+    KEYWORD_BNA,
+    KEYWORD_BNAAL,
+    KEYWORD_BRAP,
+    KEYWORD_BRNA,
+    KEYWORD_SAP,
+    KEYWORD_SNA,
+    KEYWORD_SELECT,
+
+    /* 关键字 - 五元指令 */
+    KEYWORD_LBN,
+    KEYWORD_LBS,
+
+    /* 关键字 - 六元指令 */
+    KEYWORD_LBNS
+}
+
+
+/**
+ * IC10 词法标记类别枚举。
+ *
+ * 对应 C++ `ic10::TokenCategory`，值从 0 开始递增。
+ * 运行时由 C++ 端通过 `enum_to_str` 编译期反射导出，
+ * 保证与 C++ 枚举定义自动同步。
+ *
+ * @public
+ */
+export enum TokenCategory {
+    /** 字面值（数字、字符串、关键字等） */
+    LITERAL = 0,
+    /** 符号（括号、冒号等） */
+    SYMBOL,
+    /** 注释 */
+    COMMENT,
+    /** 注解（文档注释、类型提示） */
+    ANNOTATION,
+    /** 空白符 */
+    WHITESPACE,
+    /** 文件结束 */
+    END,
+    /** 无效标记 */
+    INVALID
+}
+
+
+/**
+ * @summary 词法单元类
+ *
+ * @desc 表示 IC10 源代码中的最小语义单元。
+ * 词法单元包括关键字（如 `move`、`add`）、标识符、数字、运算符等。
+ *
+ * Token 是词法分析的结果，作为语法分析器的输入。
+ *
+ * @public
+ */
+export class Token {
+    /**
+     * @summary 构造函数
+     *
+     * @param type - Token 类型（对应 ic10::TokenType 枚举）
+     * @param pos - 位置对象，记录该 Token 在源代码中的位置
+     * @param lexeme - 词素，即源代码中的原始字符串
+     * @param category - Token 类别（对应 ic10::TokenCategory 枚举，可选）
+     *
+     * @example
+     * ```typescript
+     * const pos = new ic10.Pos();
+     * pos.line = 0;
+     * pos.column = 0;
+     * const token = new ic10.Token(TokenType.KEYWORD_MOVE, pos, 'move', TokenCategory.LITERAL);
+     * ```
+     */
+    constructor(type: TokenType, pos: Pos, lexeme?: string, category?: TokenCategory);
+
+    /**
+     * @summary Token 类型
+     * @desc 对应 ic10::TokenType 枚举值，表示 Token 的语法类别
+     */
+    type: TokenType;
+
+    /**
+     * @summary 位置信息
+     * @desc 该 Token 在源代码中的起始位置
+     */
+    pos: Pos;
+
+    /**
+     * @summary 词素
+     * @desc 源代码中匹配该 Token 的原始字符串
+     */
+    lexeme: string;
+
+    /**
+     * @summary Token 类别
+     * @desc 对应 ic10::TokenCategory 枚举值，提供更细粒度的分类
+     */
+    category: TokenCategory;
+
+    /**
+     * @summary 返回可读字符串表示
+     *
+     * @returns 格式化的字符串，如 `Token{type=1, lexeme="move"}`
+     *
+     * @desc 用于调试目的，返回人类可读的 Token 描述。
+     */
+    toString(): string;
+
+    /**
+     * @summary 返回 JSON 字符串表示
+     *
+     * @returns JSON 格式的 Token 表示
+     *
+     * @desc 返回包含 type、pos、lexeme、category 的 JSON 对象字符串。
+     */
+    toJSON(): string;
+}

package/types/linker.d.ts

@@ -0,0 +1,156 @@
+// Copyright (c) 2026. All rights reserved.
+// This source code is licensed under the CC BY-NC-SA
+// (Creative Commons Attribution-NonCommercial-NoDerivatives) License, By Xiao Songtao.
+// This software is protected by copyright law. Reproduction, distribution, or use for commercial
+// purposes is prohibited without the author's permission. If you have any questions or require
+// permission, please contact the author: edocsitahw@qq.com
+
+/**
+ * @file linker.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/07/22 17:12
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+import { Diagnostic } from "./common";
+import { Program } from "./parser";
+import { SymbolTable } from "./semantic";
+import { TypeTable } from "./semantic/type_table";
+
+
+/**
+ * @summary 编译单元信息
+ *
+ * @desc 表示链接过程中每个编译单元的信息，包括路径和诊断信息。
+ *
+ * @public
+ */
+export interface UnitInfo {
+    /**
+     * @summary 源文件路径
+     */
+    path: string;
+
+    /**
+     * @summary 该单元的诊断信息列表
+     */
+    diagnostics: Diagnostic[];
+}
+
+
+/**
+ * @summary 链接器类
+ *
+ * @desc 用于链接多个 IC10 编译单元，合并它们的符号表并收集所有诊断信息。
+ *
+ * @elseif en
+ * @summary Linker class
+ *
+ * @desc Used to link multiple IC10 compilation units, merge their symbol tables,
+ *       and collect all diagnostics.
+ *
+ * @example
+ * ```typescript
+ * // 创建链接器并链接多个编译单元
+ * const linker = new ic10.Linker();
+ *
+ * // 添加源代码字符串
+ * linker.addUnit('alias sensor0 console0');
+ * linker.addUnit('move r0 r1', 'file.ic10');
+ *
+ * // 添加已解析的 Program 对象
+ * const tokens = ic10.Lexer.tokenize('add r2 r0 r1');
+ * const parser = new ic10.Parser(tokens);
+ * const program = parser.parse();
+ * linker.addUnit(program, 'another.ic10');
+ *
+ * // 执行链接
+ * const symbolTable = linker.link();
+ *
+ * // 检查诊断信息
+ * if (linker.diagnostics.length > 0) {
+ *     console.log('诊断信息:', linker.diagnostics);
+ * }
+ * ```
+ *
+ * @public
+ */
+export class Linker {
+    /**
+     * @summary 构造函数
+     *
+     * @desc 创建一个新的链接器实例。
+     */
+    constructor();
+
+    /**
+     * @summary 添加编译单元（Program 对象）
+     *
+     * @param program - 要链接的 Program 对象
+     *
+     * @desc 将已解析的 AST 程序添加到链接器中。
+     */
+    addUnit(program: Program): void;
+
+    /**
+     * @summary 添加编译单元（源代码字符串）
+     *
+     * @param source - IC10 源代码字符串
+     *
+     * @desc 将源代码字符串添加到链接器，内部会自动进行词法分析和语法分析。
+     */
+    addUnit(source: string): void;
+
+    /**
+     * @summary 添加编译单元（带路径）
+     *
+     * @param program - 要链接的 Program 对象
+     * @param path - 源文件路径
+     *
+     * @desc 将已解析的 AST 程序添加到链接器中，并关联源文件路径。
+     */
+    addUnit(program: Program, path: string): void;
+
+    /**
+     * @summary 添加编译单元（源代码字符串带路径）
+     *
+     * @param source - IC10 源代码字符串
+     * @param path - 源文件路径
+     *
+     * @desc 将源代码字符串添加到链接器，内部会自动进行词法分析和语法分析，并关联源文件路径。
+     */
+    addUnit(source: string, path: string): void;
+
+    /**
+     * @summary 执行链接操作
+     *
+     * @returns 合并后的 SymbolTable 对象
+     *
+     * @desc 对所有已添加的编译单元执行语义分析，合并符号表，并返回最终的符号表。
+     */
+    link(): SymbolTable;
+
+    /**
+     * @summary 诊断列表
+     *
+     * @desc 链接过程中产生的所有诊断信息（包含错误、警告、提示）。
+     *       每个诊断对象包含 level、id、start、end、message 字段。
+     */
+    get diagnostics(): Diagnostic[];
+
+    /**
+     * @summary 编译单元列表
+     *
+     * @desc 所有已添加的编译单元信息，每个单元包含路径和诊断信息。
+     */
+    get units(): UnitInfo[];
+
+    /**
+     * @summary 全局类型表
+     *
+     * @desc 链接过程中合并的全局类型表，包含所有编译单元通过文档注释定义的设备类型和枚举类型。
+     *       应在调用 {@link Linker.link} 之后访问以获取完整结果。
+     */
+    get typeTable(): TypeTable;
+}

package/types/locale.d.ts

@@ -0,0 +1,36 @@
+// Copyright (c) 2026. All rights reserved.
+// This source code is licensed under the CC BY-NC-SA
+// (Creative Commons Attribution-NonCommercial-NoDerivatives) License, By Xiao Songtao.
+// This software is protected by copyright law. Reproduction, distribution, or use for commercial
+// purposes is prohibited without the author's permission. If you have any questions or require
+// permission, please contact the author: edocsitahw@qq.com
+
+/**
+ * @file locale.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/07/22 17:21
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+
+/**
+ * @summary 本地化设置类
+ *
+ * @desc 提供 IC10 编译器的本地化支持，允许设置错误消息和诊断信息的语言。
+ *
+ * @public
+ */
+export class IC10CompilerLocal {
+    /**
+     * @summary 设置编译器的语言环境
+     *
+     * @param language - 语言代码（如 'en'、'zh' 等）
+     *
+     * @example
+     * ```typescript
+     * ic10.IC10Local.setLanguage('zh');
+     * ```
+     */
+    static setLanguage(language: string): void;
+}