文件
文件读写命名空间。 所有返回 结果 容器，失败不炸程序。
函数
| 调用 | 返回 | 说明 |
|---|---|---|
文件.读(路径) | 结果 | 成功时 .值 为文件内容字符串；失败时 .错误 为原因 |
文件.写(路径, 内容) | 结果 | 成功时 .值 为 真；失败（路径非法、写入/刷盘失败等）时 .错误 为原因 |
文件.存在?(路径) | 布尔 | 文件是否存在 |
文件.删(路径) | 结果 | 删除文件；占用/瞬时锁会自动重试，最终失败时 .错误 带尝试次数与系统错误码；文件不存在视为明确错误 |
文件.建目录(路径) | 结果 | 创建单层目录；已存在或无权时失败 |
文件.删目录(路径) | 结果 | 删除空目录；非空或不存在时失败 |
文件.复制(源, 目标) | 结果 | 复制文件（流式 8KB 缓冲，任意大小可用） |
文件.移动(源, 目标) | 结果 | 移动/更名（同盘 rename；跨盘移动请用 复制+删除） |
文件.尺寸(路径) | 结果 | 成功时 .值 为字节数（整） |
文件.修改时间(路径) | 结果 | 成功时 .值 为 Unix 时间戳（整，秒） |
文件.改目录(路径) | 结果 | 改变进程当前工作目录（影响后续相对路径解析） |
文件.打开(路径, 模式) | 结果 | 打开流式句柄；模式："读" / "写"（截断） / "追加" / "读写"（须已存在） / "写读"（截断）；成功时 .值 为文件句柄 |
流式句柄方法（文件.打开 的返回值）
句柄是 ARC 管理的对象：不显式关闭也会在回收时自动关闭（关闭幂等）。非对应模式的操作返回失败 结果。
| 调用 | 返回 | 说明 |
|---|---|---|
h.读一行() | 结果 | 读一行（剥行尾 \r\n/\n）；到文件尾时 .成功 为假、.错误 为 "已到文件尾" |
h.读全部() | 结果 | 自当前位置读到文件尾 |
h.读字节(n) | 结果 | 读 n 字节原始字节流（可含 NUL；短读正常） |
h.写文本(内容) / h.写行(内容) | 结果 | 写入字符串；写行自动补 \n（二进制语义，不翻译 \r\n） |
h.移动位置(偏移) | 结果 | 绝对位置（自文件首，从 0 起） |
h.到文件尾() | 结果 | 移到末尾（追加写前用） |
h.取位置() | 结果 | 当前读写位置（整，字节） |
h.取长度() | 结果 | 文件长度（整，字节；保持当前位置不变） |
h.尾?() | 布尔 | 上次读是否已越过末尾 |
h.刷新() | 结果 | 冲刷写缓冲到磁盘 |
h.关闭() | 结果 | 关闭句柄（幂等） |
xuantie
设 开 = 文件.打开("日志.txt", "追加")
若 开.成功 {
设 h = 开.值
h.写行("[" & 字(时.现()) & "] 启动")
h.关闭()
}
设 读 = 文件.打开("日志.txt", "读")
若 读.成功 {
设 h = 读.值
设 行 = h.读一行()
当 行.成功 {
示(行.值)
行 = h.读一行()
}
h.关闭()
}用法
xuantie
设 写果 = 文件.写("配置.json", "{\"版本\": 1}")
若 写果.成功 { 示("已写入") } 否 { 示("写入失败: " & 写果.错误) }
设 读果 = 文件.读("配置.json")
若 读果.成功 {
设 数据 = 解(读果.值) // 读回的是字符串,要解析 JSON 得再过 解
示(数据["版本"])
} 否 {
示("读取失败: " & 读果.错误)
}注意
文件.读返回的是结果容器不是字符串——直接解(文件.读(...))会在运行时显式报错退出（守卫：解只接受字符串）。必须先若 r.成功 { 解(r.值) }。- 删除文件不要写
执("cmd /c del …")：命令里的正斜杠会被 cmd 当作开关（Invalid switch），且失败常被忽略。用文件.删。 - 中文路径安全：
文件.*在 Windows 上走宽字符 API（_wfopen/DeleteFileW），UTF-8 路径可直接使用。
