codecin 5.5.3__tar.gz → 5.6.0__tar.gz

{codecin-5.5.3 → codecin-5.6.0}/CHANGELOG.md

@@ -5,6 +5,145 @@
 
 ---
 
+## [5.6.0] - 2026-09-27
+
+一次以「静默错误清零 + 安全加固」为主的修复发布，落地 `docs/SUGGESTIONS_NEXT.md`
+第一轮评审的全部 P0/P1 项。所有语义修复均同步 Python 解释器与 Go 原生 VM 两条路径，
+并新增 25 个回归测试（`tests/test_p0_fixes.py`）；同时新增**键盘输入监听**宿主能力
+（非阻塞轮询）与键盘场景的**顺序实时输出**、终端输入缓存兼容。
+
+### 修复 (Fixed)
+
+- **`enum` 末成员无尾逗号解析失败**：`expect(RBRACE)` 前未跳过换行导致
+  `enum Color { RED, GREEN = 5 }` 报 `Expected RBRACE but got NL`。
+  Python 编译器与 Go 编译器同步修复。
+- **`input()` 真实现**：此前恒编译为 `MOV x0, 0`，任何输入都返回 0。现编译为
+  `IN` 指令：解释器从 `input_buffer` / 标准输入逐行读取（非法行返回 0），
+  Go 原生 VM 在缓冲耗尽后回退标准输入；CLI 启动时预读管道 stdin，
+  管道喂入（`echo 42 | ...`）与交互输入均可用。
+- **`substr` / `indexof` 统一字节语义**：此前按字符索引，与 `strlen` / `s[i]`
+  的字节语义不一致，非 ASCII 字符串算错下标。现与 Go 侧一致按 UTF-8 字节切片/查找。
+- **`sqrt` / `pow` 数学域错误对齐 NaN**：解释器此前对 `sqrt(-1.0)` 抛 CPython
+  `ValueError`，与 Go 路径（返回 NaN）不一致。现统一返回 NaN
+  （IEEE-754 允许同一 NaN 有多个位模式，不做精确位断言）。
+- **CLI 编码兜底**：Windows GBK 控制台下输出非 ASCII 即崩，`main()` 入口对
+  stdout/stderr 强制 `reconfigure(encoding='utf-8', errors='replace')`。
+- **Go 编译器无法构建**（既有）：`genRangeFor` 的 `elemType` 参数误声明为
+  `*Node` 导致整个 compiler 包编译失败，改回 `*Type`；同步修正两个从未跑通的
+  Go 测试（range-for 标签前缀、enum 全局初始化器用例的期望值）。
+
+### 安全 (Security)
+
+- **`--sandbox` 真实现**：此前为空壳。现拦截全部宿主能力 SYS 调用
+  （`AUDIOPLAY=39` 起的文件/网络/桌面/进程类），并强制放弃原生 DLL 路径
+  回退解释器执行，保证拦截无旁路。
+- **条件断点白名单求值**：`debugger` 的断点条件此前直接 `eval`，远程调试端口
+  可执行任意代码。现以 AST 白名单（字面量/寄存器名/算术比较/布尔逻辑）
+  校验后受限求值，拒绝 Call/Attribute/Subscript/推导式等一切可执行语法，
+  条件长度上限 512 字符。
+
+### 加固 (Hardened)
+
+- **JIT 栈保护补齐**：PUSH 生成代码补栈溢出检查（栈顶与堆区相撞即报错），
+  POP 补栈下溢检查，与解释器 / 原生 VM 对齐。
+- **汇编器非法数字字面量报错**：`0x_`、`0b__` 等残缺字面量此前静默求值为 0，
+  现编译报错。
+
+### 新增 (Added)
+
+#### CIN 语法
+
+- **`enum` 枚举**：`enum Color { RED, GREEN = 5, BLUE }`。成员是**编译期整数常量**，
+  未显式赋值时自动递增（首个成员从 `0` 起）；`= <整数常量表达式>` 支持
+  `+ - * / % << >> & | ^` 与一元 `-` / `~`，可引用**先前已定义**的成员。
+  枚举类型名等价于 `int`（`Color c = BLUE`），成员可用于表达式、全局初始化与 `case` 标签；
+  成员只读，赋值报 `Cannot assign to enum member: X (constants are read-only)`。
+- **范围 for**：`for (int v : arr)` 遍历定长数组元素（元素可为标量 / `string` / struct），
+  支持 `break` / `continue`。被遍历对象必须是定长数组：`int[]` 指针形式报
+  `range-for requires a fixed-size array`，多维数组报
+  `range-for over multi-dimensional arrays is not supported`（改用下标循环）。
+- **`for` 初始化子句支持赋值**：`for (i = 0; i < n; i = i + 1)` 现在与类型声明一样合法。
+- **`switch` 增强**：`case 1, 2, 7..9:` —— 逗号分隔的单值与**闭区间**范围可混用（含负数），
+  仍是 C 的贯穿语义；范围要求 `lo <= hi`，否则报 `Empty case range: lo..hi`。
+- **转义扩展**：`\xH` / `\xHH` 写入**原始字节**（`"\xE4\xB8\xAD"` 即 `"中"` 的 UTF-8 三字节）、
+  `\uHHHH` / `\UHHHHHHHH` 按 **Unicode 码点**解析并以 UTF-8 编码写入；新增 `\a \b \f \v`
+  （字符字面量同样支持这四个）。`\u` / `\U` 位数不足或码点越界都有明确报错；未知转义保持原样。
+- **多参数 `print` / `println`**：`println("a=", a, " b=", b)` 依次输出、**不加分隔符**；
+  `println()` 输出空行；单参数行为不变。
+
+#### 宿主 API（36 个，全部 Go 原生实现）
+
+- **路径与文件系统**：`path_join` `path_basename` `path_dirname` `path_abs`（string，路径分隔符随平台）、
+  `file_copy` `file_move` `dir_remove`（递归删除）`chdir`（int，`0`/`-1`）、
+  `is_dir`（`1`/`0`）、`file_mtime`（Unix 秒 / `-1`）、`temp_dir`（string）。
+- **时间与系统**：`time_ms`、`sleep_ms`（单次上限 10 分钟 / 600000 ms）、`cpu_count`、
+  `arch_name`、`mem_info`（JSON `{"total_kb":N,"free_kb":M}`，未知平台为 0）、`is_android`。
+- **网络**：`http_get` / `http_post`（返回响应体，失败空串；15 秒超时、8 MiB 上限）、
+  `download`（`0`/`-1`；非 2xx 算失败，落盘上限 256 MiB）。
+- **编码与哈希**：`sha256`（十六进制小写）、`base64_encode`、`base64_decode`（非法输入空串）。
+- **桌面集成**（Termux 优先，再按平台分发，命令缺失即优雅失败）：`clipboard_get` / `clipboard_set`、
+  `notify`、`open_url`。Windows 用 PowerShell `Get-Clipboard` / `cmd /c clip`、`Wscript.Shell.Popup`
+  （10 秒自动消失）、`cmd /c start`；Linux 用 `wl-paste` / `xclip` / `xsel`、`notify-send`、`xdg-open`；
+  macOS 用 `pbpaste` / `pbcopy`、`osascript`、`open`；Android/Termux 用 `termux-clipboard-*`、
+  `termux-notification`、`termux-open-url`。
+- **Android / Termux 扩展**（非 Android 环境一律优雅失败）：`android_intent`（`am start`，Termux 下回退
+  `termux-am`）、`termux_call`、`termux_share`、`termux_torch`、`termux_volume`、`termux_brightness`、
+  `termux_camera_photo`、`termux_fingerprint`、`termux_sensor`。
+- **`os_name()` 说明更新**：除 `"windows"` / `"darwin"` / `"linux"` 外，Android 原生构建返回 `"android"`。
+
+#### 键盘输入监听（SYS 116..118，非阻塞轮询）
+
+- **`key_hit()` / `get_key()` / `key_flush()`**：面向游戏循环 / TUI 的非阻塞键盘轮询，
+  核心实现全部由 Go 原生引擎承担（纯标准库，零第三方依赖）。
+  - `key_hit()` -> `1` 有待读按键 / `0` 无；
+  - `get_key()` -> 取出一个键码，无按键返回 `-1`；`0..255` 为原始字节
+    （Ctrl+字母 = 字母 & 0x1F，监听期间 Ctrl+C 不再终止程序），
+    方向键 / Home / End / PgUp / PgDn / Ins / Del 映射为 `1001..1010`，
+    F1..F10 映射为 `1021..1030`（Unix 转义序列与 Windows 扫描码在引擎内统一解码）；
+  - `key_flush()` -> 清空键盘输入缓冲。
+- **平台实现**：Windows 用 msvcrt `_kbhit`/`_getch`；Linux / macOS / Termux 用
+  termios 原始输入（只关行缓冲 / 回显 / Ctrl+C 信号，保留输出处理，
+  `println` 不受影响）；程序退出自动恢复终端设置（幂等，覆盖所有执行出口）。
+- **终端缓存兼容**：激活监听时清空控制台输入残留（Windows `FlushConsoleInputBuffer` /
+  Unix 非阻塞排空）；Windows 启用前先以 `GetConsoleMode` 校验 stdin 为控制台，
+  管道 / 重定向的判定与非 Windows 一致。
+- **顺序输出（禁止一股脑输出）**：真实终端下激活监听时，原生引擎先把已缓冲输出
+  落到终端，之后逐条直写 stdout 实时可见 —— "提示 → 等按键 → 反馈"顺序正确；
+  非终端环境（管道 / 重定向 / 测试捕获）保持"缓冲 + 结束回传"不变。
+- **非终端环境优雅失败**：`key_hit` 恒 `0`，`get_key` 恒 `-1`，不阻塞、不报错。
+- **`codecin/lib/key.cin` 标准库**：`enum Key` 键码常量（`K_UP`..`K_F10`、
+  `K_ESC` `K_ENTER` `K_TAB` `K_BACKSPACE`）+ `k_ctrl`（Ctrl 组合键码）+
+  `k_is_special`（扩展键码判定）+ `key_wait`（10ms 轮询阻塞等一键）。
+- 三个内建同时注册进 Python 编译器 `HOST_BUILTINS` 表；纯解释路径
+  （`--no-native`）调用报 `require the native Go runtime`（与全部宿主 API 一致），
+  `--sandbox` 同样拦截；`cpu.py` 宿主能力判定由编号区间改为
+  `>= AUDIOPLAY` 下界，未来新增宿主 SYS 不再漏判。
+
+### 文档 (Docs)
+
+- `docs/CIN_GUIDE.md`：新增「enum 枚举」「范围 for」「转义序列」小节，`switch` 增加多值/范围 case，
+  `for` 说明 init 赋值，`print`/`println` 改为多参数签名；宿主能力新增 6 个分组的 API 表
+  （路径与文件系统 / 时间与系统 / 网络 / 编码与哈希 / 桌面集成，含各平台机制对照表 / Android-Termux 扩展）、
+  限制与常见错误同步。
+- `docs/language/`：`types.md`（新增 enum 类型）、`control-flow.md`（范围 for、case 范围）、
+  `lexical.md`（转义表、关键字、续行运算符 `..`）、`strings.md`、`builtins.md`、`host-abilities.md`
+  （网络 / 编码 / 桌面 / Android 分组与能力矩阵）、`errors.md`、`arrays.md`、`variables.md`、`index.md` 同步。
+- `docs/beginner/`：`cheatsheet.md`、`ch11-io-host.md`（新增网络、编码与哈希、桌面集成、路径与文件管理、
+  时间与系统、Android/Termux 扩展小节）、`ch04-conditions.md`、`ch05-loops.md`、`index.md` 同步。
+- `misc/vim/syntax/cin.vim`：`enum` 加入类型高亮，36 个新宿主内建加入 `cinBuiltin`。
+- `docs/CIN_GUIDE.md`：新增「宿主能力: 键盘输入监听（非阻塞轮询）」分节
+  （键码约定表 + 游戏循环示例 + 平台实现与输出行为说明），官方标准库清单收录 `key.cin`。
+- 修正 `input()` 的过时描述（`docs/language/builtins.md`、`beginner/ch02-variables.md`、
+  `ch11-io-host.md`、`ch12-debug.md`、`cheatsheet.md`、`projects.md`）：
+  自本版起 `input()` 已真实现（读一行标准输入，非法行 / EOF 返回 `0`），
+  相关章节与避坑清单同步为实际行为；`cheatsheet.md` 的 `sqrt(-1)` 条目
+  同步为"两条路径一致返回 NaN"。
+- 本版宿主 API 均为 **Go 原生引擎实现**：纯解释路径（`--no-native`）调用会报
+  `host builtins (GUI/audio/system/Termux) require the native Go runtime`；
+  它们具备真实文件与网络权限，请只运行可信脚本。
+
+---
+
 ## [5.5.3] - 2026-09-26
 
 以「消除静默算错地址」为主线的一次修复发布：两个会**读错/写错内存且不报错**的

{codecin-5.5.3/codecin.egg-info → codecin-5.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecin
-Version: 5.5.3
+Version: 5.6.0
 Summary: Code CIN - 高级语言与运行时 (CIN/PL/ASM 工具链 + Go 原生 VM + ARM64/RISC-V/FP/Vector 指令集)
 Author: ByUsi Studio, 北啊呢
 License-Expression: MIT
@@ -417,7 +417,8 @@ flowchart TD
 **安装（pip）**
 
 ```bash
-pip install codecin          # 内置标准库 (codecin/lib/*.cin) 随包分发
+pip install codecin          # 安装 (内置标准库 codecin/lib/*.cin 随包分发)
+pip install -U codecin       # 升级到最新版 (不要锁定版本号)
 codecin --version
 ```
 

{codecin-5.5.3 → codecin-5.6.0}/README.md

@@ -399,7 +399,8 @@ flowchart TD
 **安装（pip）**
 
 ```bash
-pip install codecin          # 内置标准库 (codecin/lib/*.cin) 随包分发
+pip install codecin          # 安装 (内置标准库 codecin/lib/*.cin 随包分发)
+pip install -U codecin       # 升级到最新版 (不要锁定版本号)
 codecin --version
 ```
 

{codecin-5.5.3 → codecin-5.6.0}/codecin/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "5.5.3"
+__version__ = "5.6.0"
 __author__ = "ByUsi Studio"
 
 from .config import Config

{codecin-5.5.3 → codecin-5.6.0}/codecin/assembler.py

@@ -36,12 +36,12 @@ def _eval_expr(text: str, symbols: Dict[str, int]) -> Optional[int]:
         raw = match.group(0).replace('_', '')
         if len(raw) > 1 and raw[:2].lower() in ('0x', '0b', '0o'):
             raw = '0' + raw[1].lower() + raw[2:]
-        try:
-            return str(int(raw, 0))
-        except ValueError:
-            return '0'
+        return str(int(raw, 0))  # 非法字面量 (如 0x_) 抛 ValueError -> 整体求值失败
 
-    text = _RE_EXPR_NUM.sub(repl_num, text)
+    try:
+        text = _RE_EXPR_NUM.sub(repl_num, text)
+    except ValueError:
+        return None
 
     def repl_name(match):
         name = match.group(0)