ic10c-node 2.6.6

package/types/parser/program.d.ts

@@ -0,0 +1,136 @@
+// 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 program.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/07/22 15:52
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+import {Pos} from "../common";
+import {LabelDefNode, PreprocessorDirectiveNode, ErrorNode} from "./ast";
+import {
+    NullaryInstructionNode,
+    UnaryInstructionNode,
+    BinaryInstructionNode,
+    TernaryInstructionNode,
+    QuaternaryInstructionNode, QuinaryInstructionNode, SenaryInstructionNode
+} from "./instructions";
+
+
+/**
+ * @summary 可执行指令联合类型
+ *
+ * @desc 包含所有可执行指令类型的联合，包括零元、一元、二元、三元、四元、五元和六元指令。
+ * 这是 IC10 程序中所有可执行指令的完整集合。
+ *
+ * @elseif en
+ * @summary Executable instruction union type
+ *
+ * @desc Union of all executable instruction types, including nullary, unary, binary, ternary, quaternary, quinary, and senary instructions.
+ * This is the complete set of all executable instructions in IC10 programs.
+ *
+ * @public
+ */
+export type ExecutableInstructionNode =
+    | NullaryInstructionNode
+    | UnaryInstructionNode
+    | BinaryInstructionNode
+    | TernaryInstructionNode
+    | QuaternaryInstructionNode
+    | QuinaryInstructionNode
+    | SenaryInstructionNode;
+
+export type PureExeInstructionNode = Exclude<ExecutableInstructionNode, ErrorNode>;
+
+/**
+ * @summary 语句联合类型
+ *
+ * @desc 包含 IC10 程序中所有语句类型的联合：
+ * - 可执行指令（{@link ExecutableInstructionNode}）
+ * - 标签定义（{@link LabelDefNode}）
+ * - 预处理指令（{@link PreprocessorDirectiveNode}）
+ *
+ * @elseif en
+ * @summary Statement union type
+ *
+ * @desc Union of all statement types in IC10 programs:
+ * - Executable instructions ({@link ExecutableInstructionNode})
+ * - Label definitions ({@link LabelDefNode})
+ * - Preprocessor directives ({@link PreprocessorDirectiveNode})
+ *
+ * @public
+ */
+export type StatementNode =
+    | ExecutableInstructionNode
+    | LabelDefNode
+    | PreprocessorDirectiveNode;
+
+
+/**
+ * @summary 程序节点类
+ *
+ * @desc 表示 IC10 程序的根节点。
+ * 包含程序的所有语句和结束位置信息。
+ *
+ * @elseif en
+ * @summary Program node class
+ *
+ * @desc Represents the root node of an IC10 program.
+ * Contains all statements of the program and end position information.
+ *
+ * @example
+ * ```typescript
+ * // 解析 IC10 代码
+ * const parser = new ic10.Parser(tokens);
+ * const program = parser.parse();
+ *
+ * // 访问程序语句
+ * console.log(`语句数量: ${program.statements.length}`);
+ * ```
+ *
+ * @public
+ */
+export class Program {
+    /**
+     * @summary 节点名称
+     * @desc 通常为 "Program"
+     */
+    nodeName: string;
+
+    /**
+     * @summary 程序语句列表
+     * @desc 包含程序中的所有语句（指令、标签、预处理指令等）
+     */
+    statements: StatementNode[];
+
+    /**
+     * @summary 结束位置
+     * @desc 程序在源代码中的结束位置
+     */
+    end: Pos;
+
+    /**
+     * @summary 返回可读字符串表示
+     *
+     * @returns 格式化的程序字符串
+     *
+     * @desc 用于调试目的，返回人类可读的程序表示。
+     */
+    toString(): string;
+
+    /**
+     * @summary 返回 JSON 字符串表示
+     *
+     * @returns JSON 格式的程序表示
+     *
+     * @desc 返回包含 nodeName、statements 和 end 的 JSON 对象字符串。
+     */
+    toJSON(): string;
+}

package/types/semantic/analyser.d.ts

@@ -0,0 +1,98 @@
+// 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 analyser.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/07/22 16:01
+ * @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 "./type_table";
+
+
+/**
+ * @summary 静态分析器类
+ *
+ * @desc 对 IC10 程序进行静态分析，包括：
+ * - 符号表构建
+ * - 语义检查
+ * - 类型检查
+ * - 错误检测
+ *
+ * @elseif en
+ * @summary Static analyser class
+ *
+ * @desc Performs static analysis of IC10 programs, including:
+ * - Symbol table construction
+ * - Semantic checking
+ * - Type checking
+ * - Error detection
+ *
+ * @example
+ * ```typescript
+ * // 创建分析器并分析程序
+ * const analyser = new ic10.Analyser();
+ * analyser.visit(program);
+ *
+ * // 检查是否有诊断信息
+ * if (analyser.diagnostics.length > 0) {
+ *     console.log('诊断信息:', analyser.diagnostics);
+ * }
+ *
+ * // 获取符号表
+ * const symbolTable = analyser.symbolTable;
+ * ```
+ *
+ * @public
+ */
+export class Analyser {
+    /**
+     * @summary 符号表
+     *
+     * @desc 分析过程中构建的符号表，包含所有定义的符号信息。
+     */
+    get symbolTable(): SymbolTable;
+
+    /**
+     * @summary 类型表
+     *
+     * @desc 分析过程中构建的类型表，包含所有自定义类型（设备类型和枚举类型）。
+     */
+    get typeTable(): TypeTable;
+
+    /**
+     * @summary 诊断列表
+     *
+     * @desc 分析过程中产生的诊断信息（包含错误、警告、提示）。
+     *       每个诊断对象包含 level、id、start、end、message 字段。
+     */
+    get diagnostics(): Diagnostic[];
+
+    /**
+     * @summary 静态方法：分析程序
+     *
+     * @param program - 要分析的 Program 节点
+     *
+     * @desc 便捷方法，直接分析程序而不需要创建 Analyser 实例。
+     */
+    static analyse(program: Program): void;
+
+    /**
+     * @summary 访问程序节点
+     *
+     * @param program - 要访问的 Program 节点
+     *
+     * @desc 执行实际的静态分析，更新符号表和诊断列表。
+     */
+    visit(program: Program): Promise<void>;
+}

package/types/semantic/index.d.ts

@@ -0,0 +1,19 @@
+// 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 index.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/07/22 17:16
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+export * from "./analyser";
+export * from "./semantic";
+export * from "./types";
+export * from "./type_table";

package/types/semantic/semantic.d.ts

@@ -0,0 +1,81 @@
+// 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 semantic.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/07/22 17:13
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+import {BasicType} from "./types";
+import {TypeCategory} from "./types";
+
+
+/**
+ * @summary 符号表类
+ *
+ * @desc 存储 IC10 程序中的符号信息（如标签、别名定义等）。
+ * 用于静态分析和代码验证。
+ *
+ * @elseif en
+ * @summary Symbol table class
+ *
+ * @desc Stores symbol information in IC10 programs (such as labels, alias definitions, etc.).
+ * Used for static analysis and code validation.
+ *
+ * @example
+ * ```typescript
+ * // 执行静态分析
+ * ic10.Analyser.analyse(program);
+ *
+ * // 获取符号表
+ * const symbolTable = analyser.symbolTable;
+ * console.log(JSON.parse(symbolTable.toJSON()));
+ * ```
+ *
+ * @public
+ */
+export class SymbolTable {
+    /**
+     * @summary 返回 JSON 字符串表示
+     *
+     * @returns JSON 格式的符号表表示
+     *
+     * @desc 返回包含所有符号信息的 JSON 对象字符串。
+     */
+    toJSON(): string;
+}
+
+
+/**
+ * @summary 符号信息
+ *
+ * @desc 表示符号表中的单个符号，由 `SymbolTable.toJSON()` 序列化输出。
+ *
+ * @public
+ */
+export interface Symbol {
+    /** 符号名称 */
+    name: string;
+    /** 基本类型（BasicType 枚举值） */
+    type: BasicType;
+    /** 类型类别（TypeCategory 枚举值） */
+    category: TypeCategory;
+    /** 类型名称（可选，如设备类型名） */
+    typeName?: string;
+    /** 符号值（可选） */
+    value?: string;
+    /** 描述信息（可选） */
+    desc?: string;
+}
+
+
+export interface SymbolMap {
+    [key: string]: Symbol;
+}

package/types/semantic/type_table.d.ts

@@ -0,0 +1,119 @@
+// 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 type_table.d.ts
+ * @author edocsitahw
+ * @version 1.0
+ * @date 2026/07/26
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+
+/**
+ * @summary 类型表类
+ *
+ * @desc 管理 IC10 程序中的自定义类型定义（设备类型和枚举类型）。
+ * 支持 JSON 序列化。
+ *
+ * @elseif en
+ * @summary Type table class
+ *
+ * @desc Manages custom type definitions in IC10 programs (device types and enum types).
+ * Supports JSON serialization.
+ *
+ * @example
+ * ```typescript
+ * const analyser = new ic10.Analyser();
+ * await analyser.visit(program);
+ * const typeTable = analyser.typeTable;
+ * console.log(JSON.parse(typeTable.toJSON()));
+ * ```
+ *
+ * @public
+ */
+export class TypeTable {
+    /**
+     * @summary 返回 JSON 字符串表示
+     *
+     * @returns JSON 格式的类型表表示
+     *
+     * @desc 返回包含所有自定义类型信息的 JSON 对象字符串。
+     */
+    toJSON(): string;
+}
+
+/** 描述值 */
+export interface DescValue {
+    kind: "text" | "link";
+    value: string;
+}
+
+/** 设备插槽 */
+export interface DeviceSlot {
+    index: string;
+    direction: "input" | "output";
+    desc?: DescValue;
+}
+
+/** 设备逻辑 */
+export interface DeviceLogic {
+    name: string;
+    access: "R" | "W" | "RW";
+}
+
+/** 设备模式 */
+export interface DeviceMode {
+    index: string;
+    desc?: DescValue;
+}
+
+/** 设备逻辑插槽 */
+export interface DeviceLogicSlot {
+    name: string;
+}
+
+/** 设备连接 */
+export interface DeviceConnect {
+    index: string;
+    desc?: DescValue;
+}
+
+/** 设备类型 (from toJSON()) */
+export interface DeviceType {
+    type: "device";
+    name: string;
+    desc?: DescValue;
+    slots: DeviceSlot[];
+    logics: DeviceLogic[];
+    modes: DeviceMode[];
+    logicSlots: string[];
+    connects: DeviceConnect[];
+}
+
+/** 枚举值条目 */
+export interface EnumValueEntry {
+    name: string;
+    value: string;
+    desc?: DescValue;
+}
+
+/** 枚举类型 (from toJSON()) */
+export interface EnumType {
+    type: "enum";
+    name: string;
+    desc?: DescValue;
+    values: EnumValueEntry[];
+}
+
+/** 自定义类型 */
+export type CustomType = DeviceType | EnumType;
+
+/** 类型表 JSON 映射 */
+export interface TypeTableMap {
+    [key: string]: CustomType;
+}

package/types/semantic/types.d.ts

@@ -0,0 +1,100 @@
+// 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 types.d.ts
+ * @author edocsitahw
+ * @version 1.1
+ * @date 2026/07/22 17:13
+ * @desc
+ * @copyright CC BY-NC-SA 2026. All rights reserved.
+ * */
+
+/**
+ * @summary 基础类型枚举
+ *
+ * @desc 定义 IC10 语言支持的基础数据类型。
+ *
+ * @public
+ */
+export enum BasicType {
+    /** 字符串类型 */
+    STRING = 0,
+    /** 整数类型 */
+    INTEGER,
+    /** 浮点类型 */
+    FLOAT,
+    /** 寄存器类型 (r0-r15) */
+    REGISTER,
+    /** 设备类型 (@开头) */
+    DEVICE,
+    /** 未知类型（解析错误） */
+    UNKNOWN,
+    /** 枚举类型 */
+    ENUM
+}
+
+
+/**
+ * @summary 类型类别枚举
+ *
+ * @desc 定义类型的语义类别，用于区分不同语义用途的类型。
+ *
+ * @public
+ */
+export enum TypeCategory {
+    /** 标签类别 */
+    LABEL = 0,
+    /** STR宏调用类别 */
+    STR_CALL,
+    /** HASH宏调用类别 */
+    HASH_CALL,
+    /** 常量类别 */
+    CONSTANT,
+    /** 数字类别 */
+    NUMBER,
+    /** 基础类别 */
+    BASIC
+}
+
+
+/**
+ * @summary 节点类型映射接口
+ *
+ * @desc 定义 AST 节点类型名到 BasicType 和 TypeCategory 的映射。
+ *
+ * @public
+ */
+export interface TypeOfNodeEntry {
+    /** 基础类型 */
+    kind: BasicType;
+    /** 类型类别 */
+    category: TypeCategory;
+}
+
+
+/**
+ * @summary AST 节点类型映射
+ *
+ * @desc 将节点类型名映射到对应的类型信息。
+ *
+ * @public
+ */
+export const TypeOfNode: {
+    Integer: TypeOfNodeEntry;
+    Float: TypeOfNodeEntry;
+    String: TypeOfNodeEntry;
+    StrCall: TypeOfNodeEntry;
+    HashCall: TypeOfNodeEntry;
+    Register: TypeOfNodeEntry;
+    Device: TypeOfNodeEntry;
+    LabelDef: TypeOfNodeEntry;
+    ErrorNode: TypeOfNodeEntry;
+    Constant: TypeOfNodeEntry;
+    BinaryNumber: TypeOfNodeEntry;
+    HexNumber: TypeOfNodeEntry;
+};