vx-toolkit 1.16.2__py3-none-any.whl

vx_toolkit/__init__.py

@@ -0,0 +1,10 @@
+"""vx_toolkit —— VX 工具链的 uv 安装包装。
+
+本包不含任何编译逻辑：它只把 `uv tool install` 生成的命令转发给
+随 wheel 分发的原生二进制（vxc / vlnk / vmake / vxls / vx），
+或转发给 `VX_TOOLKIT_BIN` / PATH 中已安装的同一套工具。
+"""
+
+__version__ = "1.16.2"
+
+__all__ = ["__version__"]

vx_toolkit/_bin/headers/collections/vec.c

@@ -0,0 +1,8 @@
+/* collections/vec 库实现 — 导出 _vx_vec_sum_to。 */
+#include <stdint.h>
+
+int32_t _vx_vec_sum_to(int32_t n) {
+  int32_t s = 0;
+  for (int32_t i = 1; i <= n; ++i) s += i;
+  return s;
+}

vx_toolkit/_bin/headers/collections/vec.vxh

@@ -0,0 +1,2 @@
+# collections/vec 库 — 子目录库，用 @imp(collections/vec) 引用（库名取末段 vec）
+extern func sum_to(n: int) -> int

vx_toolkit/_bin/headers/cpp/greet.cpp

@@ -0,0 +1,11 @@
+// greet.cpp — @cppimp 示例实现（C++ 符号 greet，非 VX ABI）。
+// vlnk 生成的 shim 调用本函数；字符串用静态缓冲返回以便 const char* 可用。
+#include "greet.hpp"
+
+#include <string>
+
+const char* greet(const char* name) {
+  static std::string msg;
+  msg = std::string("Hello, ") + (name ? name : "") + "!";
+  return msg.c_str();
+}

vx_toolkit/_bin/headers/cpp/greet.hpp

@@ -0,0 +1,6 @@
+// greet.hpp — @cppimp 示例：普通 C++ 头文件（C++ ABI，无 extern "C"）。
+// vlnk 在链接期自动生成 shim，把 C++ 符号 greet 包装为 VX ABI 符号
+// _vx_greet_greet（见同目录伴生声明 greet.vxh）。
+#pragma once
+
+const char* greet(const char* name);

vx_toolkit/_bin/headers/cpp/greet.vxh

@@ -0,0 +1,4 @@
+# cpp/greet 库 — @cppimp 伴生声明头（.vxh，必须与 greet.hpp 同目录同主名）
+# 用 @cppimp(cpp/greet.hpp) 引用；以 greet.greet(x) 访问。
+# VX ABI 类型映射：string → const char*。
+extern func greet(name: string) -> string

vx_toolkit/_bin/headers/fmath.c

@@ -0,0 +1,3 @@
+/* fmath 库实现 — 浮点 VX ABI（double 进出）。 */
+double _vx_fmath_halve(double x) { return x / 2.0; }
+double _vx_fmath_average(double a, double b) { return (a + b) / 2.0; }

vx_toolkit/_bin/headers/fmath.vxh

@@ -0,0 +1,5 @@
+# fmath 库 — 浮点（float/double）类型的 VX ABI 声明头
+# @imp(fmath) 后以 fmath.halve / fmath.average 访问；符号为
+# _vx_fmath_halve / _vx_fmath_average。类型映射：float → double。
+extern func halve(x: float) -> float
+extern func average(a: float, b: float) -> float

vx_toolkit/_bin/headers/math.c

@@ -0,0 +1,6 @@
+/* math 库实现 — 导出 VX ABI 符号（_vx_<lib>_<name>）。
+ * 与 headers/math.vxh 的声明一一对应，由 vlnk 在链接期并入。 */
+#include <stdint.h>
+
+int32_t _vx_math_add(int32_t a, int32_t b) { return a + b; }
+int32_t _vx_math_mul(int32_t a, int32_t b) { return a * b; }

vx_toolkit/_bin/headers/math.vxh

@@ -0,0 +1,4 @@
+# math 库 — VX ABI 声明头（.vxh）
+# @imp(math) 后以 math.add / math.mul 访问；符号 _vx_math_add / _vx_math_mul
+extern func add(a: int, b: int) -> int
+extern func mul(a: int, b: int) -> int

vx_toolkit/_bin/headers/sys.c

@@ -0,0 +1,9 @@
+/* sys 库实现 — 执行 shell 命令，返回 libc system() 的退出状态。
+ * 导出 VX ABI 符号：_vx_sys_system。 */
+#include <stdint.h>
+#include <stdlib.h>
+
+int32_t _vx_sys_system(const char *cmd) {
+  if (!cmd) return -1;
+  return (int32_t)system(cmd);
+}

vx_toolkit/_bin/headers/sys.vxh

@@ -0,0 +1,3 @@
+# sys 库 — 系统能力的 VX ABI 声明头（.vxh）
+# @imp(sys) 后以 sys.system(cmd) 访问；符号 _vx_sys_system
+extern func system(cmd: string) -> int

vx_toolkit/_bin/headers/text.c

@@ -0,0 +1,17 @@
+/* text 库实现 — 导出 VX ABI 符号：_vx_text_length / _vx_text_is_empty /
+ * _vx_text_shout。覆盖 string 入参、int/bool 返回与 void 返回三种形态。 */
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+int32_t _vx_text_length(const char *s) {
+  return s ? (int32_t)strlen(s) : 0;
+}
+
+int32_t _vx_text_is_empty(const char *s) { return (s == NULL || *s == '\0'); }
+
+void _vx_text_shout(const char *s) {
+  if (!s) return;
+  for (const char *p = s; *p; ++p) putchar(*p);
+  putchar('\n');
+}

vx_toolkit/_bin/headers/text.vxh

@@ -0,0 +1,6 @@
+# text 库 — 字符串/布尔/void 类型的 VX ABI 声明头
+# @imp(text) 后以 text.length / text.is_empty / text.shout 访问。
+# 类型映射：string → const char*，bool → int32_t，无返回 = void。
+extern func length(s: string) -> int
+extern func is_empty(s: string) -> bool
+extern func shout(s: string)

vx_toolkit/_bin/std/README.md

@@ -0,0 +1,90 @@
+# VX 标准库（设计参考）
+
+> **当前定位：前瞻设计稿，不可被当前工具链编译执行。**
+>
+> 本目录 v1.0 版本为早期 VM 执行路线设计（源码 → VM 字节码 → 虚拟机解释）。
+> 工具链已转向原生路线（`vxc` → VXOBJ → `vlnk` → clang 链接为原生可执行），
+> 原「VM 内建指令」前提整体作废，本文末尾的 VM 指令清单不再代表演进方向。
+> 本目录保留作为标准库 API 设计参考，待编译器能力补齐后逐步原生化。
+
+## 当前真实可用的能力
+
+标准库的职能当前由两套机制承担：
+
+| 机制 | 内容 | 位置 |
+|------|------|------|
+| 内置运行时（无需声明） | `out` / `out_int` / `out_bool` / `out_float` / `sys_argv_count` / `sys_argv_get` / `file_read` / `file_write` / `file_exists` / `puts` / `exit` / `malloc` / `free` | `src/runtime/vxrt.c` |
+| 导入库（`@imp` / `@cppimp`） | math / text / fmath / collections/vec / cpp/greet / sys（`system(cmd)`）（VX ABI：`_vx_<lib>_<name>`） | `headers/` |
+
+文件 I/O 与命令行参数等本目录中标记 `not implemented` 的能力，
+在上述内置运行时中已有原生实现，可直接使用（见 README §2.1 / docs/SYNTAX.md §3.3）。
+
+## 与编译器现状的差距（v1.12.0 实测）
+
+47 个 `.vx` 文件中 36 个可被当前编译器解析，11 个失败，对照如下：
+
+| 文件 | 依赖的不支持语法 |
+|------|------------------|
+| `error.vx`、`sys/coroutine.vx` | `enum` 声明 |
+| `bytes.vx` | 泛型参数 `Vec<int>` |
+| `reflect/mod.vx` | 类内常量字段（无类型注解赋值字段） |
+| `macros.vx` | `macro` 声明 |
+| `conv.vx` | 类型转换调用 `int(v)` |
+| `char.vx` | 十六进制字面量 `0x4E00` |
+| `collections/linked_list.vx` | 函数体内 `import` |
+| `mem/arena.vx`、`mem/page.vx` | 空函数体（仅注释，无语句） |
+| `tests/test_string_io.vx` | 字符串方法调用 `s.split(...)` |
+
+> 可解析 ≠ 可执行：`import` 语法、全局状态、字符串方法等运行时支撑
+> 同样未落地。`std/tests/` 从未接入 CTest，不代表有效回归覆盖。
+
+## 编译器能力补齐后的演进路径
+
+1. 解析缺口（上表）逐项支持后，std/ 源码先达到「全部可解析」；
+2. `import` / 全局 `var`/`const` 代码生成落地后，std/ 以 `@imp` 或模块
+   编译单元形式接入工具链；
+3. VM 前提的功能（协程、同步原语等）按原生语义重新设计或裁剪。
+
+## 目录结构（设计稿）
+
+```
+std/
+├── mod.vx                 # std 总入口
+├── prelude.vx             # 预导入模块
+├── error.vx               # 错误处理（零依赖）
+├── macros.vx              # 编译时宏工具（零依赖）
+├── collections/           # 核心数据结构（vec / hashmap / linked_list / set）
+├── string/                # 字符串处理（util / pattern / codec / iter / core）
+├── math/                  # 基础数学（math / random）
+├── io/                    # 输入输出与文件系统（file / stream / path / dir）
+├── mem/                   # 内存管理（allocator / arena / general / page）
+├── sys/                   # 系统与并发（time / duration / datetime / coroutine / sync / env）
+├── iter.vx / option.vx / conv.vx / bytes.vx / char.vx / reflect/
+└── tests/                 # 设计期手写用例（未接入 CTest）
+```
+
+## 模块依赖关系（设计）
+
+```
+error (零依赖)
+macros (零依赖)
+  ↓
+collections → error
+  ↓
+string → collections, error
+  ↓
+math → (弱依赖 collections)
+  ↓
+io → collections, string, error, sys
+sys → collections, error
+```
+
+## 语法约束（当前 VX 编译器限制）
+
+v1.0 标准库基于设计期编译器能力编写：
+
+- 使用 `class` 替代 `struct + impl`（VX 无 `impl` 块）
+- 使用 `if/elif/else` 替代 `match` 表达式
+- 使用函数返回值替代 `const` 常量
+- 所有定义默认公开（VX 无 `pub` 关键字）
+- 以 `var` 类型字段模拟泛型（`Option.value: var`）

vx_toolkit/_bin/std/bytes.vx

@@ -0,0 +1,65 @@
+# ============================================================
+# std::bytes —— 字节缓冲区
+# 为 VXOBJ 二进制生成提供基础支持
+# 底层用 Vec<int> 存储 0..255
+# ============================================================
+
+import std.collections.vec
+import std.error
+
+class ByteBuffer:
+    data: Vec<int>   # Vec<int>
+
+    func new() -> ByteBuffer:
+        b = new ByteBuffer()
+        b.data = new Vec<int>()
+        return b
+
+    # 写入单字节（0..255）
+    func write_u8(v: int):
+        self.data.push(v % 256)
+
+    # 大端写入 32 位无符号整数
+    func write_u32_be(v: int):
+        self.write_u8(v / 16777216 % 256)
+        self.write_u8(v / 65536 % 256)
+        self.write_u8(v / 256 % 256)
+        self.write_u8(v % 256)
+
+    # 写入原始字节数组
+    func write_bytes(arr: Vec<int>):
+        i = 0
+        while i < len(arr):
+            self.data.push(arr[i] % 256)
+            i = i + 1
+
+    # 将字符串按 UTF-8 字节写入（每个字符一个码点字节，仅适合 ASCII/字节串）
+    func write_str(s: str):                                     
+        i: int = 0
+        while i < len(s):
+            self.data.push(ord(s[i]) % 256)
+            i = i + 1
+
+    # 返回原始字节数组
+    func to_vec() -> Vec<int>:
+        return self.data.to_array()
+
+    # 当前缓冲区大小
+    func size() -> int:
+        return self.data.size()
+
+    # 清空缓冲区
+    func clear():
+        self.data.clear()
+
+    # 写入另一个 ByteBuffer 的内容
+    func write_buffer(other: ByteBuffer):
+        bytes: Vec<int> = other.to_vec()
+        self.write_bytes(bytes)
+
+    # 生成 4 字节大端长度前缀 + 内容
+    func write_with_length_prefix() -> ByteBuffer:
+        result = new ByteBuffer()
+        result.write_u32_be(self.size())
+        result.write_buffer(self)
+        return result

vx_toolkit/_bin/std/char.vx

@@ -0,0 +1,83 @@
+# ============================================================
+# std::char —— 字符分类工具
+# 依赖 VM 内建 ord(c) 返回 Unicode 码点
+# ============================================================
+
+import std.error
+
+class Char:
+    # 是否为 ASCII 数字 '0'..'9'
+    func is_digit(c: var) -> bool:
+        var code = ord(c)
+        return code >= 48 && code <= 57
+
+    # 是否为 ASCII 字母（含大小写）
+    func is_alpha(c: var) -> bool:
+        var code = ord(c)
+        return (code >= 65 && code <= 90) || (code >= 97 && code <= 122)
+
+    # 是否为 ASCII 字母或数字
+    func is_alnum(c: var) -> bool:
+        return Char.is_alpha(c) || Char.is_digit(c)
+
+    # 是否为空白字符（空格、\t、\n、\r、全角空格）
+    func is_whitespace(c: var) -> bool:
+        var code = ord(c)
+        return code == 32 || code == 9 || code == 10 || code == 13 || code == 12288
+
+    # 是否为小写 ASCII 字母
+    func is_lower(c: var) -> bool:
+        var code = ord(c)
+        return code >= 97 && code <= 122
+
+    # 是否为大写 ASCII 字母
+    func is_upper(c: var) -> bool:
+        var code = ord(c)
+        return code >= 65 && code <= 90
+
+    # 是否为 CJK 统一表意文字或常见 CJK 符号区
+    func is_cjk(c: var) -> bool:
+        var code = ord(c)
+        return (code >= 0x4E00 && code <= 0x9FFF) || (code >= 0x3000 && code <= 0x303F) || (code >= 0xFF00 && code <= 0xFFEF)
+
+    # 是否为下划线
+    func is_underscore(c: var) -> bool:
+        return ord(c) == 95
+
+    # 是否可作为标识符首字符（字母、下划线、CJK）
+    func is_ident_start(c: var) -> bool:
+        return Char.is_alpha(c) || Char.is_underscore(c) || Char.is_cjk(c)
+
+    # 是否可作为标识符后续字符（字母、数字、下划线、CJK）
+    func is_ident_part(c: var) -> bool:
+        return Char.is_alnum(c) || Char.is_underscore(c) || Char.is_cjk(c)
+
+    # 将字符转为小写（仅 ASCII）
+    func to_lower(c: var) -> var:
+        var code = ord(c)
+        if code >= 65 && code <= 90:
+            return chr(code + 32)
+        return c
+
+    # 将字符转为大写（仅 ASCII）
+    func to_upper(c: var) -> var:
+        var code = ord(c)
+        if code >= 97 && code <= 122:
+            return chr(code - 32)
+        return c
+
+# 顶层便捷函数
+func is_digit(c: var) -> bool:
+    return Char.is_digit(c)
+
+func is_alpha(c: var) -> bool:
+    return Char.is_alpha(c)
+
+func is_alnum(c: var) -> bool:
+    return Char.is_alnum(c)
+
+func is_whitespace(c: var) -> bool:
+    return Char.is_whitespace(c)
+
+func is_cjk(c: var) -> bool:
+    return Char.is_cjk(c)

vx_toolkit/_bin/std/collections/hashmap.vx

@@ -0,0 +1,31 @@
+# ============================================================
+# std::collections::hashmap —— 哈希表
+# ============================================================
+
+class HashMap:
+    size: int
+
+    func new() -> int:
+        var m = new HashMap()
+        m.size = 0
+        return m
+
+    func insert(m: HashMap, key: var, val: var):
+        m.size = m.size + 1
+
+    func remove(m: HashMap, key: var) -> int:
+        if m.size > 0:
+            m.size = m.size - 1
+        return nil
+
+    func has_key(m: HashMap, key: var) -> bool:
+        return false
+
+    func size(m: HashMap) -> int:
+        return m.size
+
+    func is_empty(m: HashMap) -> bool:
+        return m.size == 0
+
+    func clear(m: HashMap):
+        m.size = 0

vx_toolkit/_bin/std/collections/linked_list.vx

@@ -0,0 +1,166 @@
+# ============================================================
+# std::collections::linked_list —— 双向链表
+# ============================================================
+
+import std.error
+
+# ---- Node 类：链表节点 ----
+class Node:
+    value: var
+    prev: var           # Node 或 nil
+    next: var           # Node 或 nil
+
+    func new(val: var) -> int:
+        var n = new Node()
+        n.value = val
+        n.prev = nil
+        n.next = nil
+        return n
+
+# ---- LinkedList 类：双向链表 ----
+class LinkedList:
+    head: var           # Node 或 nil
+    tail: var           # Node 或 nil
+    len: int
+
+    # ========== 构造器 ==========
+
+    func new() -> int:
+        var ll = new LinkedList()
+        ll.head = nil
+        ll.tail = nil
+        ll.len = 0
+        return ll
+
+    # ========== 头部操作 ==========
+
+    func push_front(val: var):
+        var node = new Node(val)
+        if self.head == nil:
+            self.head = node
+            self.tail = node
+        else:
+            node.next = self.head
+            self.head.prev = node
+            self.head = node
+        self.len = self.len + 1
+
+    func pop_front() -> int:
+        if self.head == nil:
+            return Result.err(error.value_error("LinkedList.pop_front: empty list"))
+        var val = self.head.value
+        if self.head == self.tail:
+            self.head = nil
+            self.tail = nil
+        else:
+            self.head = self.head.next
+            self.head.prev = nil
+        self.len = self.len - 1
+        return Result.ok(val)
+
+    func peek_front() -> int:
+        if self.head == nil:
+            return Result.err(error.value_error("LinkedList.peek_front: empty list"))
+        return Result.ok(self.head.value)
+
+    # ========== 尾部操作 ==========
+
+    func push_back(val: var):
+        var node = new Node(val)
+        if self.tail == nil:
+            self.head = node
+            self.tail = node
+        else:
+            node.prev = self.tail
+            self.tail.next = node
+            self.tail = node
+        self.len = self.len + 1
+
+    func pop_back() -> int:
+        if self.tail == nil:
+            return Result.err(error.value_error("LinkedList.pop_back: empty list"))
+        var val = self.tail.value
+        if self.head == self.tail:
+            self.head = nil
+            self.tail = nil
+        else:
+            self.tail = self.tail.prev
+            self.tail.next = nil
+        self.len = self.len - 1
+        return Result.ok(val)
+
+    func peek_back() -> int:
+        if self.tail == nil:
+            return Result.err(error.value_error("LinkedList.peek_back: empty list"))
+        return Result.ok(self.tail.value)
+
+    # ========== 查询 ==========
+
+    func size() -> int:
+        return self.len
+
+    func is_empty() -> bool:
+        if self.len == 0:
+            return true
+        return false
+
+    # 查找元素，返回第一个匹配的索引
+    func index_of(val: var) -> int:
+        var current = self.head
+        var idx = 0
+        while current != nil:
+            if current.value == val:
+                return idx
+            current = current.next
+            idx = idx + 1
+        return -1
+
+    # 检查是否包含
+    func contains(val: var) -> bool:
+        if LinkedList.index_of(self, val) >= 0:
+            return true
+        return false
+
+    # ========== 修改 ==========
+
+    # 清空链表
+    func clear():
+        self.head = nil
+        self.tail = nil
+        self.len = 0
+
+    # ========== 转换 ==========
+
+    # 转为 Vec
+    func to_vec() -> int:
+        import std.collections.vec
+        var result = new Vec()
+        var current = self.head
+        while current != nil:
+            result.push(current.value)
+            current = current.next
+        return result
+
+    # 转为内建数组
+    func to_array() -> int:
+        var result = []
+        var current = self.head
+        while current != nil:
+            result = result + [current.value]
+            current = current.next
+        return result
+
+    # ========== 字符串表示 ==========
+
+    func to_string() -> int:
+        var s = "["
+        var current = self.head
+        var first = true
+        while current != nil:
+            if first == false:
+                s = s + " <-> "
+            s = s + current.value
+            first = false
+            current = current.next
+        s = s + "]"
+        return s

vx_toolkit/_bin/std/collections/mod.vx

@@ -0,0 +1,8 @@
+# ============================================================
+# std::collections —— 模块入口
+# ============================================================
+
+import std.collections.vec
+import std.collections.hashmap
+import std.collections.linked_list
+import std.collections.set

vx_toolkit/_bin/std/collections/set.vx

@@ -0,0 +1,102 @@
+# ============================================================
+# std::collections::set —— 集合
+# 基于 HashMap 实现，Zig 风格无 self
+# ============================================================
+
+import std.collections.hashmap
+
+class Set:
+    inner: var          # HashMap 实例
+    len: int
+
+    func new() -> int:
+        var s = new Set()
+        s.inner = HashMap.new()
+        s.len = 0
+        return s
+
+    func insert(s: Set, val: var):
+        if HashMap.has_key(s.inner, val) == false:
+            HashMap.insert(s.inner, val, true)
+            s.len = s.len + 1
+
+    func remove(s: Set, val: var) -> int:
+        var r = HashMap.remove(s.inner, val)
+        if r.is_ok:
+            s.len = s.len - 1
+        return r
+
+    func contains(s: Set, val: var) -> bool:
+        return HashMap.has_key(s.inner, val)
+
+    func size(s: Set) -> int:
+        return s.len
+
+    func is_empty(s: Set) -> bool:
+        if s.len == 0:
+            return true
+        return false
+
+    func clear(s: Set):
+        HashMap.clear(s.inner)
+        s.len = 0
+
+    func union(s: Set, other: var) -> int:
+        var result = Set.new()
+        var self_keys = HashMap.keys(s.inner)
+        var i = 0
+        while i < len(self_keys):
+            Set.insert(result, self_keys[i])
+            i = i + 1
+        var other_keys = HashMap.keys(other.inner)
+        i = 0
+        while i < len(other_keys):
+            Set.insert(result, other_keys[i])
+            i = i + 1
+        return result
+
+    func intersection(s: Set, other: var) -> int:
+        var result = Set.new()
+        var self_keys = HashMap.keys(s.inner)
+        var i = 0
+        while i < len(self_keys):
+            var key = self_keys[i]
+            if Set.contains(other, key):
+                Set.insert(result, key)
+            i = i + 1
+        return result
+
+    func difference(s: Set, other: var) -> int:
+        var result = Set.new()
+        var self_keys = HashMap.keys(s.inner)
+        var i = 0
+        while i < len(self_keys):
+            var key = self_keys[i]
+            if Set.contains(other, key) == false:
+                Set.insert(result, key)
+            i = i + 1
+        return result
+
+    func is_subset(s: Set, other: var) -> bool:
+        var self_keys = HashMap.keys(s.inner)
+        var i = 0
+        while i < len(self_keys):
+            if Set.contains(other, self_keys[i]) == false:
+                return false
+            i = i + 1
+        return true
+
+    func is_superset(s: Set, other: var) -> bool:
+        return Set.is_subset(other, s)
+
+    func to_string(s: Set) -> int:
+        var s_str = "Set{"
+        var self_keys = HashMap.keys(s.inner)
+        var i = 0
+        while i < len(self_keys):
+            if i > 0:
+                s_str = s_str + ", "
+            s_str = s_str + self_keys[i]
+            i = i + 1
+        s_str = s_str + "}"
+        return s_str