vx-toolkit 1.16.2__tar.gz

vx_toolkit-1.16.2/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+.eggs/
+dist/
+build/
+.venv/
+venv/
+env/
+scripts/stage.py
+# 构建产物
+build-*/
+cmake-build-*/
+
+# IDE / 编辑器
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# 系统文件
+.DS_Store
+Thumbs.db
+
+# uv / pip 缓存
+.cache/
+"><|end|><|start|>write to=assistant<|channel|>analysis<|message|>Now update pyproject.toml license. Also add license-files? Hatchling. Let me edit.<|end|><|start|>-start_of_image_generation_placeholder <|constrain|>xml<|message|><rfl:parameter name="prompt">
+Apache License 2.0 badge? not needed

vx_toolkit-1.16.2/LICENSE

@@ -0,0 +1,198 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or
+      Object form, that is based on (or derived from) the Work and for
+      which the editorial revisions, annotations, elaborations, or other
+      modifications represent, as a whole, an original work of authorship.
+      For the purposes of this License, Derivative Works shall not include
+      works that remain separable from, or merely link (or bind by name)
+      to the interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright
+      owner or by an individual or Legal Entity authorized to submit on
+      behalf of the copyright owner. For the purposes of this definition,
+      "submitted" means any form of electronic, verbal, or written
+      communication sent to the Licensor or its representatives, including
+      but not limited to communication on electronic mailing lists, source
+      code control systems, and issue tracking systems that are managed by,
+      or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is
+      conspicuously marked or otherwise designated in writing by the
+      copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal
+      Entity on behalf of whom a Contribution has been received by
+      Licensor and subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      modify, merge, publish, distribute, sublicense, and/or sell copies
+      of the Work, and to permit persons to whom the Work is furnished
+      to do so, subject to the following conditions:
+
+      The above copyright notice and this permission notice shall be
+      included in all copies or substantial portions of the Work.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have
+      made, use, offer to sell, sell, import, and otherwise transfer
+      the Work, where such license applies only to those patent claims
+      licensable by such Contributor that are necessarily infringed by
+      their Contribution(s) alone or by combination of their
+      Contribution(s) with the Work to which such Contribution(s) was
+      submitted. If You institute patent litigation against any entity
+      (including a cross-claim or counterclaim in a lawsuit) alleging
+      that the Work or a Contribution incorporated within the Work
+      constitutes direct or indirect patent infringement, then any
+      patent licenses granted to You under this License for that Work
+      shall terminate as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute
+          must include a readable copy of the attribution notices
+          contained within such NOTICE file, excluding those notices
+          that do not pertain to any part of the Derivative Works,
+          in at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or as an addendum to
+          the NOTICE text file from the Work, provided that such
+          additional attribution notices cannot be construed as
+          modifying the License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing
+      the origin of the Work and reproducing the content of the NOTICE
+      file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or
+      conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or
+      FITNESS FOR A PARTICULAR PURPOSE. You are hereby notified that
+      you may be exposing yourself and others to risks by using the Work,
+      and that the recommended and prudent course of action is to
+      analyze all aspects of the Work and test it in a controlled
+      environment before putting it into production. You assume all
+      risks and responsibilities associated with the use of the Work.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to you for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any kind, arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Support, Services, Maintenance,
+      or Insurance. Licensor may choose to provide additional support,
+      services, maintenance, or insurance beyond the terms of this
+      License, but is not obligated to do so.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!) The text should be at least be included in the
+      appropriate "NOTICE" file; however, each source file may include
+      them on the first line, or as a separate "NOTICE" section within
+      the file's documentation. See the NOTICE file for additional
+      details (if applicable).
+
+      Copyright [yyyy] [name of copyright owner]
+
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied. See the License for the specific language governing
+      permissions and limitations under the License.

vx_toolkit-1.16.2/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.5
+Name: vx-toolkit
+Version: 1.16.2
+Summary: VX language toolchain (vxc, vlnk, vmake, vxls) installed through uv
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: build,compiler,lsp,toolchain,vx
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Compilers
+Requires-Python: >=3.9

vx_toolkit-1.16.2/README.md

@@ -0,0 +1,20 @@
+# vx-toolkit
+
+VX 语言工具链的 uv 安装包装（`vxc` / `vlnk` / `vmake` / `vxls` / `vmake-lsp` / `vfmt` / `vx`）。
+
+本仓库的 Python 包本身不含编译逻辑，仅把 `uv tool install` 生成的命令转发给随 wheel
+分发的原生二进制，或转发给 `VX_TOOLKIT_BIN` / `PATH` 中已安装的同一套工具。
+
+## 安装
+
+```sh
+# 先把 CMake 产物 + headers 装进包内 _bin/
+python3 scripts/stage.py
+
+# 再安装，得到 vxc / vlnk / vmake / vxls / ...
+uv tool install .
+```
+
+## 许可证
+
+本项目基于 [Apache License 2.0](LICENSE) 协议开源。

vx_toolkit-1.16.2/pyproject.toml

@@ -0,0 +1,42 @@
+# vx-toolkit — uv 安装包装（Python 包只做命令转发，工具链本体是 C++ 二进制）
+#
+# 安装：
+#   python3 scripts/stage.py             # 先把 CMake 产物 + headers 装进包内 _bin/
+#   uv tool install .                    # 再安装，得到 vxc / vlnk / vmake / vxls ...
+#
+# 所有 console script 都指向同一个转发入口，按脚本名分派到对应二进制；
+# 二进制查找顺序见 src/vx_toolkit/_dispatch.py。
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vx-toolkit"
+version = "1.16.2"
+description = "VX language toolchain (vxc, vlnk, vmake, vxls) installed through uv"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+keywords = ["vx", "compiler", "toolchain", "lsp", "build"]
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: C++",
+    "Environment :: Console",
+    "Topic :: Software Development :: Compilers",
+]
+
+[project.scripts]
+vxc = "vx_toolkit._dispatch:main"
+vlnk = "vx_toolkit._dispatch:main"
+vmake = "vx_toolkit._dispatch:main"
+vxls = "vx_toolkit._dispatch:main"
+vmake-lsp = "vx_toolkit._dispatch:main"
+vfmt = "vx_toolkit._dispatch:main"
+vx = "vx_toolkit._dispatch:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vx_toolkit"]
+# _bin/ 里是 stage.py 复制的 C++ 二进制与 headers，必须强制进入 wheel
+#（仓库 .gitignore 规则会让 hatchling 默认忽略它们）。
+artifacts = ["src/vx_toolkit/_bin/**"]
+include = ["src/vx_toolkit/_bin/**"]

vx_toolkit-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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-1.16.2/src/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