codecin 5.4.2__py3-none-any.whl

codecin/cli.py

@@ -0,0 +1,282 @@
+"""命令行入口: argparse 参数解析 -> 加载程序 -> 运行。
+
+建议 3: 采用 argparse 统一参数表 (不再三份手写解析), 全部选项由
+build_parser() 单一来源定义, --help 与解析行为自动保持一致。
+"""
+
+import argparse
+import os
+import sys
+from typing import List, Optional
+
+from .config import Config
+from .console import Colors, Console, Panel
+
+HELP_INTRO = f"""{Colors.colorize('Code CIN v5.3', Colors.CYAN, True)}
+
+{Colors.colorize('Usage:', Colors.YELLOW)}
+  python cpu.py <program.[cin|pl|asm|bin]> [options]
+
+{Colors.colorize('Supported formats:', Colors.YELLOW)}
+  .cin   CIN 高级语言 (函数/struct/数组/浮点/字符串)
+  .pl    Code CIN 汇编语言 (PL 关键字风格)
+  .asm   Code CIN 汇编
+  .bin   UCBC 字节码 (由 --compile 生成)
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """参数表单一来源 (与 Config 字段一一对应)。"""
+    p = argparse.ArgumentParser(
+        prog='cpu.py',
+        description='Code CIN - 高级语言与运行时 (CIN/PL/ASM 工具链 + 多执行路径)',
+        add_help=False,          # 帮助由 main 以彩色形式打印 (见 --help)
+    )
+    p.add_argument('program', nargs='?', default=None,
+                   metavar='program.[cin|pl|asm|bin]',
+                   help='程序源文件/字节码/镜像')
+    p.add_argument('--help', '-h', action='store_true', dest='show_help',
+                   help='显示帮助')
+    from . import __version__
+    p.add_argument('--version', '-V', action='version',
+                   version=f'Code CIN {__version__}',
+                   help='显示版本号并退出')
+
+    # 执行路径
+    p.add_argument('--no-native', action='store_true',
+                   help='禁用 Go 原生库, 强制纯 Python 解释执行')
+    p.add_argument('--jit', action='store_true', dest='enable_jit',
+                   help='启用 Python JIT (基本块动态编译)')
+    p.add_argument('--no-jit', action='store_true', dest='disable_jit',
+                   help=argparse.SUPPRESS)
+
+    # 日志与调试
+    p.add_argument('--debug', action='store_true',
+                   help='调试模式 (超详细 rich 追踪: 逐指令/寄存器/内存/栈/缓存)')
+    p.add_argument('--step', action='store_true',
+                   help='交互式单步执行 (step> 命令集, 与断点调试一致)')
+    p.add_argument('--log-level', choices=['DEBUG', 'INFO', 'WARNING', 'ERROR',
+                                           'CRITICAL'],
+                   help='日志级别 (默认 INFO)')
+    p.add_argument('--log-file', metavar='FILE', help='日志输出到文件')
+    p.add_argument('--sandbox', action='store_true',
+                   help='沙箱模式 (限制宿主访问)')
+    p.add_argument('--no-io', action='store_true',
+                   help='禁止 IN/OUT 与宿主 I/O')
+
+    # 性能分析
+    p.add_argument('--profile', action='store_true',
+                   help='执行后输出性能统计')
+    p.add_argument('--cache-size', type=int, metavar='N',
+                   help='缓存行数 (默认 64)')
+    p.add_argument('--cache-assoc', type=int, metavar='N',
+                   help='缓存关联度 (默认 4)')
+    p.add_argument('--mem-size', type=int, metavar='BYTES',
+                   help='内存大小 (默认 65536)')
+    p.add_argument('--max-instructions', type=int, metavar='N',
+                   help='指令数上限 (默认 100000000)')
+    p.add_argument('--execution-interval', type=float, metavar='SEC',
+                   help='每指令间隔秒数 (演示减速用)')
+
+    # 编译 / CROM
+    p.add_argument('--compile', action='store_true', dest='compile_to_bin',
+                   help='编译为 .bin 字节码后继续执行')
+    p.add_argument('--compile-only', action='store_true',
+                   help='仅编译为 .bin 不执行')
+    p.add_argument('-o', '--output', metavar='FILE',
+                   help='指定输出文件 (.crom/.bin)')
+    p.add_argument('--crom', metavar='FILE', help='加载指定 .crom 内存镜像')
+    p.add_argument('--save', action='store_true', dest='auto_save_crom',
+                   help='执行后保存 .crom 内存镜像')
+    p.add_argument('--no-compress', action='store_false', dest='compress_crom',
+                   help='.crom 不压缩 (默认压缩)')
+
+    # 语言/汇编
+    p.add_argument('--optimize', type=int, metavar='0-3',
+                   help='优化级别 (0-3, 默认 0)')
+    p.add_argument('--strict', action='store_true', help='严格汇编模式')
+
+    # 运行时行为 (A1/A2/A4)
+    p.add_argument('--seed', type=int, default=None, metavar='N',
+                   help='随机种子 (确定性执行; 默认随机)')
+    p.add_argument('--bounds-check', action='store_true',
+                   help='CIN 数组越界运行时检查 (强制解释执行)')
+    p.add_argument('--mmu', action='store_true',
+                   help='启用 MMU 分页 (identity 页表; 未映射页触发缺页错误)')
+    p.add_argument('--debug-server', type=int, default=None, metavar='PORT',
+                   help='启动 TCP 远程调试服务 (连接后驱动式调试: step/continue/'
+                        'break/regs/mem/history)')
+    p.add_argument('--disasm', action='store_true',
+                   help='反汇编 .bin 字节码为文本清单后退出')
+
+    # AOT: 编译成独立静态可执行文件
+    p.add_argument('--build-exe', nargs='?', const='', default=None,
+                   metavar='OUT',
+                   help='编译成独立静态可执行文件 (不依赖 Python/动态库) 后退出; '
+                        '省略路径时输出到 <程序名>[.exe]')
+    p.add_argument('--build-target', default=None, metavar='OS/ARCH',
+                   help='AOT 交叉编译目标 (默认当前平台): '
+                        'windows/amd64, linux/amd64, linux/arm64, '
+                        'darwin/amd64, darwin/arm64')
+    p.add_argument('--build-keep-temp', action='store_true',
+                   help='AOT 构建时保留临时目录 (排查 go build 失败)')
+    return p
+
+
+def _apply_namespace(config: Config, ns: argparse.Namespace) -> None:
+    """把 argparse Namespace 映射到 Config 字段。"""
+    config.step_mode = ns.step
+    config.debug_mode = ns.debug
+    if ns.step or ns.debug:
+        config.interactive_mode = True
+    config.use_native = not ns.no_native
+    config.enable_jit = ns.enable_jit and not ns.disable_jit
+    config.sandbox_mode = ns.sandbox
+    config.profile = ns.profile
+    config.auto_save_crom = ns.auto_save_crom
+    config.compress_crom = ns.compress_crom
+    config.compile_to_bin = ns.compile_to_bin
+    config.compile_only = ns.compile_only
+    config.output_file = ns.output
+    config.allow_io = not ns.no_io
+    config.strict_mode = ns.strict
+    config.seed = ns.seed
+    config.bounds_check = ns.bounds_check
+    config.mmu = ns.mmu
+    config.debug_server_port = ns.debug_server
+
+    if ns.log_level is not None:
+        config.log_level = ns.log_level
+    if ns.log_file is not None:
+        config.log_file = ns.log_file
+    if ns.mem_size is not None:
+        config.mem_size = ns.mem_size
+    if ns.cache_size is not None:
+        config.cache_size = ns.cache_size
+    if ns.cache_assoc is not None:
+        config.cache_assoc = ns.cache_assoc
+    if ns.max_instructions is not None:
+        config.max_instructions = ns.max_instructions
+    if ns.execution_interval is not None:
+        config.execution_interval = ns.execution_interval
+    if ns.optimize is not None:
+        config.optimize = ns.optimize
+
+
+def _run_aot_build(ns: argparse.Namespace, console, program_file: str) -> int:
+    """AOT: 把 CIN 程序编译成独立静态可执行文件 (--build-exe)。"""
+    from . import aot
+    from .errors import CPUSimulatorError
+
+    target = ns.build_target or aot.host_target()
+    try:
+        goos, _goarch = aot.parse_target(target)
+    except aot.AotError as e:
+        console.print(Panel(str(e), title='Build Error', border_style='red'))
+        return 1
+
+    out = ns.build_exe or (os.path.splitext(program_file)[0]
+                           + aot.exe_suffix(goos))
+    console.print(Colors.colorize(
+        f"AOT build: {program_file} -> {out} (静态链接, 目标 {target})",
+        Colors.CYAN))
+    try:
+        built = aot.build_program(program_file, out=out, target=target,
+                                  keep_temp=ns.build_keep_temp)
+    except (aot.AotError, CPUSimulatorError) as e:
+        console.print(Panel(str(e), title='Build Error', border_style='red'))
+        return 1
+    console.print(Colors.colorize(f"AOT build 完成: {built}", Colors.GREEN))
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+
+    if '--help' in args or '-h' in args:
+        sys.stdout.write(HELP_INTRO + "\n")
+        sys.stdout.write(build_parser().format_help())
+        return 0
+
+    console = Console()
+    parser = build_parser()
+    try:
+        ns = parser.parse_args(args)
+    except SystemExit as e:
+        # argparse 错误 (未知选项/非法数值): 已打印 usage, 返回其退出码
+        return int(e.code) if e.code is not None else 2
+
+    if ns.program is None:
+        console.print(Panel("No program file specified.\n"
+                            "Use --help for usage information.",
+                            title="Error", border_style='red'))
+        return 1
+
+    config = Config()
+    _apply_namespace(config, ns)
+    config.validate()
+
+    program_file = ns.program
+    crom_file = ns.crom
+    output_file = (config.output_file
+                   or os.path.splitext(program_file)[0] + '.bin')
+
+    if ns.disasm:
+        from .disasm import disassemble_file
+        try:
+            lines = disassemble_file(program_file)
+        except Exception as e:
+            from .errors import CPUSimulatorError
+            title = ("Disasm Error" if isinstance(e, CPUSimulatorError)
+                     else "Error")
+            console.print(Panel(str(e), title=title, border_style='red'))
+            return 1
+        sys.stdout.write("\n".join(lines))
+        return 0
+
+    if ns.build_exe is not None:
+        return _run_aot_build(ns, console, program_file)
+
+    try:
+        from .cpu import CPU
+        cpu = CPU(config, program_file, crom_file=crom_file)
+    except Exception as e:
+        from .errors import CPUSimulatorError
+        if isinstance(e, CPUSimulatorError):
+            console.print(Panel(str(e), title="Load Error", border_style='red'))
+        else:
+            console.print(Panel(str(e), title="Error", border_style='red'))
+            if config.debug_mode:
+                # 超详细: rich 彩色完整堆栈
+                console.print_exception()
+        return 1
+
+    try:
+        if config.compile_to_bin or config.compile_only:
+            from . import crom as crom_mod
+            crom_mod.save_bin(cpu, output_file, logger=cpu.logger)
+            console.print(Colors.colorize(
+                f"Compiled to {output_file}", Colors.GREEN))
+            if config.compile_only:
+                return 0
+
+        cpu.run()
+    except KeyboardInterrupt:
+        pass
+    except Exception as e:
+        from .errors import CPUSimulatorError
+        if isinstance(e, CPUSimulatorError):
+            console.print(Panel(str(e), title="Error", border_style='red'))
+        else:
+            console.print(Panel(str(e), title="Unexpected Error",
+                                border_style='red'))
+            console.print_exception()
+        return 1
+    # CPU.run 内部会捕获执行期异常并记录日志, 这里据失败标志决定退出码
+    if getattr(cpu, 'execution_failed', False):
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

codecin/config.py

@@ -0,0 +1,58 @@
+"""运行配置与命令行参数解析。"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class Config:
+    mem_size: int = 64 * 1024
+    stack_size: int = 1024
+    step_mode: bool = False
+    debug_mode: bool = False
+    auto_save_crom: bool = False
+    execution_interval: float = 0.0
+    max_execution_time: float = 60.0
+    interactive_mode: bool = True
+    sandbox_mode: bool = False
+    max_instructions: int = 100_000_000
+    allow_io: bool = True
+    log_level: str = 'INFO'
+    log_file: Optional[str] = None
+    show_memory_bytes: int = 32
+    show_vector_regs: bool = True
+    show_timings: bool = True
+    strict_mode: bool = False
+    output_file: Optional[str] = None
+    optimize: int = 0
+    enable_jit: bool = False
+    use_native: bool = True          # 允许使用 Go 原生库加速
+    cache_size: int = 64
+    cache_assoc: int = 4
+    profile: bool = False
+    compress_crom: bool = True
+    compile_to_bin: bool = False
+    compile_only: bool = False
+    # A2: 确定性随机种子 (None = 随机)
+    seed: Optional[int] = None
+    # A1: CIN 运行时断言/边界检查开关
+    bounds_check: bool = False
+    # B1: MMU/分页 (默认 identity 映射; unmap/protect 需测试或宿主侧设置)
+    mmu: bool = False
+    # A4: 远程调试服务端口 (None = 不启动)
+    debug_server_port: Optional[int] = None
+
+    # 命令行解析请使用 codecin/cli.py build_parser() (argparse, 单一来源)。
+    # Config 仅承载运行配置, 由 cli._apply_namespace 填充。
+
+    def validate(self) -> None:
+        if self.mem_size < 256:
+            self.mem_size = 256
+        if self.max_instructions < 1:
+            self.max_instructions = 1
+        if self.optimize < 0:
+            self.optimize = 0
+        if self.optimize > 3:
+            self.optimize = 3
+        if self.cache_size < 8:
+            self.cache_size = 8

codecin/console.py

@@ -0,0 +1,183 @@
+import re
+from typing import Any, Optional
+
+from rich import box as _box_mod
+from rich.console import Console as RichConsole
+from rich.panel import Panel as RichPanel
+from rich.table import Table as RichTable
+from rich.text import Text
+
+_ANSI_RE = re.compile(r'\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])')
+
+
+def _to_renderable(obj: Any) -> Any:
+    """将任意对象转换为 rich 可渲染对象。
+
+    str 含 ANSI 时转 Text (rich 渲染时按终端能力自动上/去色)。
+    """
+    if isinstance(obj, str):
+        if '\x1b' in obj:
+            return Text.from_ansi(obj)
+        return obj
+    if hasattr(obj, '__rich_console__'):
+        return obj
+    return str(obj)
+
+
+class Colors:
+    """ANSI 颜色码 (历史 API, 输出层自动转换为 rich Text)。"""
+
+    RESET = '\033[0m'
+    BOLD = '\033[1m'
+    DIM = '\033[2m'
+
+    BLACK = '\033[30m'
+    RED = '\033[31m'
+    GREEN = '\033[32m'
+    YELLOW = '\033[33m'
+    BLUE = '\033[34m'
+    MAGENTA = '\033[35m'
+    CYAN = '\033[36m'
+    WHITE = '\033[37m'
+
+    BG_BLACK = '\033[40m'
+    BG_RED = '\033[41m'
+    BG_GREEN = '\033[42m'
+    BG_YELLOW = '\033[43m'
+    BG_BLUE = '\033[44m'
+    BG_MAGENTA = '\033[45m'
+    BG_CYAN = '\033[46m'
+    BG_WHITE = '\033[47m'
+
+    @staticmethod
+    def strip(text: str) -> str:
+        return _ANSI_RE.sub('', text)
+
+    @staticmethod
+    def colorize(text: str, color: str, bold: bool = False) -> str:
+        return f"{Colors.BOLD if bold else ''}{color}{text}{Colors.RESET}"
+
+
+class Console:
+    """rich 控制台封装。"""
+
+    def __init__(self, force_color: Optional[bool] = None):
+        kwargs: dict = {}
+        if force_color is not None:
+            kwargs['force_terminal'] = force_color
+            kwargs['color_system'] = 'truecolor' if force_color else None
+        self._rc = RichConsole(
+            highlight=False, emoji=False, markup=False,
+            soft_wrap=False, **kwargs)
+
+    @property
+    def rich(self) -> RichConsole:
+        """底层 rich Console (供 logger/异常渲染复用)。"""
+        return self._rc
+
+    @property
+    def color_support(self) -> bool:
+        return self._rc.color_system is not None
+
+    def width(self) -> int:
+        return self._rc.width
+
+    def print(self, *args, **kwargs) -> None:
+        objs = [_to_renderable(a) for a in args]
+        self._rc.print(*objs, sep=kwargs.pop('sep', ' '),
+                       markup=False, highlight=False, **kwargs)
+
+    def print_exception(self, **kwargs) -> None:
+        """rich 彩色堆栈回溯。"""
+        self._rc.print_exception(word_wrap=True, **kwargs)
+
+    def clear(self) -> None:
+        self._rc.clear()
+
+    def rule(self, title: str = "", style: str = "cyan") -> None:
+        self._rc.rule(Text.from_ansi(title) if '\x1b' in title else title,
+                      style=style, align='center')
+
+    def clear_line(self) -> None:
+        self._rc.print('\r' + ' ' * 80 + '\r', end='')
+
+
+class Panel:
+    """rich Panel 适配器, 兼容 str(Panel(...)) 用法。"""
+
+    def __init__(self, content, title: str = "", border_style: str = "",
+                 box=None):
+        self._content = content
+        self._title = title
+        self._border_style = border_style or 'cyan'
+        self._box = box or _box_mod.ROUNDED
+
+    def build(self) -> RichPanel:
+        content = _to_renderable(self._content)
+        title = Text.from_ansi(self._title) if '\x1b' in self._title \
+            else self._title
+        return RichPanel(content, title=title, border_style=self._border_style,
+                         box=self._box, expand=False)
+
+    def __rich_console__(self, console, options):
+        return self.build().__rich_console__(console, options)
+
+    def __str__(self) -> str:
+        import io
+        buf = io.StringIO()
+        c = RichConsole(file=buf, width=80, highlight=False, emoji=False,
+                        markup=False)
+        c.print(self.build())
+        return buf.getvalue().rstrip('\n')
+
+
+class Table:
+    """rich Table 适配器, 兼容旧 add_column/add_row API。
+
+    print(table) 时按 rich 全彩渲染; str(table) 输出纯文本。
+    """
+
+    def __init__(self, title: str = "", box=None, border_style: str = "",
+                 show_lines: bool = False):
+        self._title = title
+        self._box = box or _box_mod.ROUNDED
+        self._border_style = border_style or 'cyan'
+        self._show_lines = show_lines
+        self._cols: list = []
+        self._rows: list = []
+
+    def add_column(self, name, style: str = "", width: int = 0, **kw) -> None:
+        self._cols.append((str(name), style or None, width or None, kw))
+
+    def add_row(self, *args) -> None:
+        self._rows.append([_to_renderable(a) if isinstance(a, str) else a
+                           for a in args])
+
+    @property
+    def rows(self) -> list:
+        return self._rows
+
+    @property
+    def headers(self) -> list:
+        return [name for name, _, _, _ in self._cols]
+
+    def build(self) -> RichTable:
+        t = RichTable(title=self._title or None, box=self._box,
+                      border_style=self._border_style,
+                      show_lines=self._show_lines, highlight=False)
+        for name, style, width, kw in self._cols:
+            t.add_column(name, style=style, width=width, **kw)
+        for row in self._rows:
+            t.add_row(*row)
+        return t
+
+    def __rich_console__(self, console, options):
+        return self.build().__rich_console__(console, options)
+
+    def __str__(self) -> str:
+        import io
+        buf = io.StringIO()
+        c = RichConsole(file=buf, width=80, highlight=False, emoji=False,
+                        markup=False)
+        c.print(self.build())
+        return buf.getvalue().rstrip('\n')