# 文件与标准输出

File 副本共用游标和关闭状态。文件操作同步执行；异步流程用 blocking，不能在 pure 函数中调用。

## dever.io.OpenResult

打开或新建文件的结果。

分支：
- `Opened(file: dever.system.File)`：成功状态
- `error Failed(message: Text)`：失败原因

## dever.io.ReadState

一次读取可短于请求长度；End 表示文件结束。

分支：
- `Read(bytes: Bytes)`：成功状态
- `End`：成功状态

## dever.io.ReadResult

显式捕获读取失败时保留 ReadState。

分支：
- `Done(state: ReadState)`：成功状态
- `error Failed(message: Text)`：失败原因

## dever.io.SystemReadResult

底层文件读取结果，在库内转换为 ReadState。

分支：
- `Read(bytes: Bytes)`：成功状态
- `End`：成功状态
- `error Failed(message: Text)`：失败原因

## dever.io.WriteResult

写入全部字节或返回失败。

分支：
- `Done`：成功状态
- `error Failed(message: Text)`：失败原因

## dever.io.CloseResult

关闭共享文件句柄或返回失败。关闭不承诺数据已落盘。

分支：
- `Closed`：成功状态
- `error Failed(message: Text)`：失败原因

## dever.io.ReadEvent

流每次产生一个数据块；终止错误只产生一次，然后结束。

分支：
- `Chunk(bytes: Bytes)`：读取的数据
- `error Failed(message: Text)`：读取失败

## dever.io.ReadStreamResult

捕获流创建失败，已创建的流仍按需读取。

分支：
- `Streaming(stream: Stream<ReadEvent>)`：共享游标的同步流
- `error Failed(message: Text)`：创建失败

## dever.io.println

写入文本及换行；标准输出失败为带源码位置的 Fault。

## dever.io.open

以只读方式打开现有文件。失败默认沿调用链传播。

## dever.io.create

新建可读写文件；路径已经存在则失败，绝不截断现有文件。

## dever.io.opened

成功时取得共享文件资源，失败时保留 OpenResult 错误身份。

## dever.io.read

读取最多 limit 字节并推进共享游标；limit 必须为正，EOF 返回 End。

## dever.io.readState

把底层读取结果转换为 ReadState；失败时传播 ReadResult.Failed。

## dever.io.write

写入全部字节；失败使用 WriteResult 传播，空字节同样验证文件是否已关闭。

## dever.io.wrote

成功时无输出，失败时保留 WriteResult 身份。

## dever.io.close

关闭底层文件使所有别名失效；重复关闭失败。最后一个别名离开作用域也会释放文件。

## dever.io.closed

成功时无输出，失败时保留 CloseResult 身份。

## dever.io.chunks

先验证正数 limit 和文件未关闭，再创建按需读取的同步流。close(stream) 幂等，释放源别名但不关闭外部文件别名。

## dever.io.readStream

成功时返回共享流，失败时保留创建错误身份。