Initial Dever 0.0.1

lib/doc/dever-io.md

@@ -0,0 +1,116 @@
+# 文件与标准输出
+
+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
+
+成功时返回共享流，失败时保留创建错误身份。