跳转至

OP 0015: 最小 I/O、命令行参数与退出码

  • 状态:Implemented(2026-11-20)
  • 作者:Oort 设计讨论
  • 相关:OP 0012、 规范:标准库
  • 动机来源:需要一个可运行的 JSON 格式化/校验 CLI 示例,当前语言无法读文件、 读命令行参数或设置退出码。

摘要

新增两个最小的原生模块,让 Oort 程序可以当作真实 CLI 使用:

import "io"
import "os"

if len(os.args) == 0 {
    print("usage: json.ort <file>")
    os.exit(2)
}

val text = io.read_file(os.args[0])
io.write_file("copy.json", text)

同时给 string 模块补两个 Unicode 辅助函数:

string.ord("A")    # 65
string.chr(65)     # "A"

动机

  • 现有标准库只有 math / string;程序只能处理内嵌数据,无法读取用户文件。
  • 没有命令行参数,任何“真实示例”都只能写死输入。
  • 没有退出码,CLI 无法区分成功/用法错误/数据错误。
  • JSON 的 \uXXXX 转义需要码点与字符串互转;ord / chr 是最小且通用的补口。

跨语言调研

语言 参数(含程序名?) 读文件失败 退出
Python sys.argv[0] 是脚本名 open() 抛 OSError sys.exit(code),默认 0
Node.js process.argv[0/1] 是 node/入口 fs.readFileSync 抛异常 process.exit(code)
Go os.Args[0] 是程序名 os.ReadFile 返回 (bytes, error) os.Exit(code)
Rust env::args() 首项通常是可执行文件 fs::read_to_string 返回 Result process::exit(code)
Ruby ARGV 不含程序名 File.read 抛 Errno exit(code)
Kotlin args 不含程序名 File.readText 抛异常 exitProcess(code)
Lua arg[0] 是脚本名,arg[1..] 是参数 io.open 返回 nil, err os.exit(code)

来源:

结论:

  • “参数是否含程序名”两种传统都有;Ruby/Kotlin 的用户参数风格更适合脚本作者。
  • Go/Rust 的错误返回值模型最清晰,但 Oort 还没有 Result/Option 与用户级 异常处理;首版只能选择“运行时错误”或 null + 错误信息。
  • os.exit(code) 在几乎所有语言里都存在,语义一致:立即结束进程。

决策(已确认)

D1:模块划分

  • io:read_file(path)、write_file(path, text)。
  • os:args、script、exit(code)。
  • string:ord(text)、chr(code)。

模块名沿用 Python 的 io / os 直觉;不引入 fs、process 等额外名称。

D2:os.args 只含用户参数

oort app.ort a b → os.args == ["a", "b"];os.script == "app.ort"。 oort -c "..." a b → os.args == ["a", "b"],os.script == null。 REPL → 两者分别为 [] / null。

理由:脚本作者最常写 os.args[0];把脚本名放在 os.script 里更清晰。与 Ruby ARGV、Kotlin args 一致;需要原始 argv 的用户可以组合两者。

D3:文件 API 是最小、UTF-8、整文件

  • io.read_file(path) -> String:读取整个文件,按 UTF-8 解码。
  • io.write_file(path, text) -> null:覆盖写入,UTF-8;父目录必须存在。
  • 失败(不存在、权限、解码错误)→ 运行时错误(OortRuntimeError),带路径。
  • 不做流式读写、目录操作、文件句柄或 stdin;后续按需另立提案。

D4:os.exit(code) 立即结束进程

  • code 为 Int;建议 0–125;0 表示成功。
  • 立即退出,不执行任何清理(Oort 没有 finally)。
  • 在 REPL 中调用会结束 REPL 进程。

D5:ord / chr 使用 Unicode 码点

  • string.ord(text):text 必须恰好一个 Unicode 字符,返回其码点。
  • string.chr(code):code 必须是合法的 Unicode 标量值(0–0x10FFFF,排除 surrogate),返回单字符 String。
  • 非法输入 → 运行时错误。

D6:非目标

  • 环境变量、工作目录、stdin、网络、文件元数据、二进制读写。
  • 用户级异常/Result;JSON 解析错误仍由解析器对象显式返回。
  • 沙箱或路径限制:与 Python/Node 一样,文件系统访问不受语言层限制;文档明确 说明运行不受信任脚本的风险。

兼容性

纯新增模块与函数;不影响现有程序。os/io 作为裸模块名会优先于同名本地文件 (与 math/string 规则一致);./os、./io 仍可加载本地模块。

测试计划

  • io:临时目录读写、UTF-8 中文/emoji、覆盖写入、缺失文件/目录的错误诊断。
  • os:文件与 -c 的参数切分、os.script、REPL 空参数、os.exit(0/2) 的 子进程退出码。
  • string.ord/chr:ASCII、中文、emoji/增补平面、非法长度与非法码点。
  • JSON CLI 示例:合法/非法 JSON、\uXXXX、代理对、格式化输出、错误退出码。

实现与测试

  • 原生模块:runtime/stdlib/io_module.py、runtime/stdlib/os_module.py; string 增加 ord / chr。
  • CLI:oort script.ort a b 与 oort -c CODE a b 都填充 os.args; Compiler 把参数与脚本路径传给解释器,REPL 保持空参数。
  • 测试:tests/unit/runtime/test_io_os_modules.py、tests/integration/test_json_example.py。
  • 示例:examples/07_showcase/07_00_json.ort(可读取文件参数)。

已决问题

  • 文件读取失败:首版用运行时错误(无用户级捕获);未来有 Result 后再评估 显式返回。
  • os.args 是 List 值(os.args[0]),只含用户参数;脚本路径在 os.script。
  • ord/chr 留在 string 模块内,避免污染全局命名空间。
  • os.exit 状态范围 0–255;0 表示成功。

未决问题

  • 是否需要 io.read_stdin() / print_error()?首版不做。
  • 二进制读写、目录操作、环境变量与工作目录:后续按需提案。