读一行，不必吞下整个文件

# 读一行，不必吞下整个文件

`io` 这个库是慢慢长起来的。先是 buffer，能当 Reader 也能当 Writer；然后是 `io.stdin()`、`io.stdout()`、`io.pipe()`，把进程的三个标准流和管道接上。到了 11 月 5 日，`io.scanner` 补进来（上游 `0fb36d4`，PR #48），`io.fun` 加了 113 行。

它干的事很小：给任意 Reader 套一层，按分隔符切成 token，默认按行。小归小，位置很正。之前要逐行处理一个文件，只有两条路：`read()` 一口气读完再 `split()`，或者自己拿 `read(n)` 拼缓冲区。前者省事，内存账难看；后者省内存，边界条件得自己写一遍，写完还未必对。

## 一、它不吞文件

Scanner 内部只留两个东西：一个 8192 字节的读缓冲，一个当前 token。`scan()` 被调用时，先在缓冲里找分隔符；找不到就再读一块，直到找到、到 EOF，或者超过 `maxToken`。

```fun
use 'io.fun';
var sc = io.scanner(io.stdin());
while sc.scan() do ?. sc.text(); end do;
if sc.err() <> nil then raise sc.err(); end if;
```

一个 1 GB 的日志文件，内存里同时存在的也就是 8 KB 缓冲加一行。`maxToken` 默认 64 KB，是给坏数据准备的：没有换行符的二进制文件、被截断的传输、故意不换行的攻击输入，都能在长到 64 KB 时停住，报 `token too long`，而不是把内存吃光。

（吐槽：流式处理的第一课，永远是先假定输入会耍赖。）

## 二、换行这件事，惯例比文法多

默认分隔符是 `\n`，行为按行的直觉来：

- `''` 扫出 0 个 token；
- `'a'` 扫出 1 个；
- `'a\n'` 也是 1 个，末尾那个换行不额外产生空 token；
- `'a\n\nb'` 是 3 个，中间的空行算一个空串；
- `'a\r\nb'` 是 2 个，行模式下会去掉结尾的 `\r`。

这套规则不对称：末尾的分隔符不产生 token，开头的分隔符却会产生一个空 token。`',a'` 按逗号切，第一个 token 就是空串。看着别扭，其实是照着「行」的直觉写的。文本文件末尾有没有换行，都不该多出一行；但开头就空着，那确实是一行空的。

自定义分隔符时，`\r` 不特殊处理。`io.scanner(r, [delimiter: ','])` 扫 `'a\r,b'`，第一个 token 是 `'a\r'`。多字符分隔符也认，`'a||b'` 按 `'||'` 切就是两个。分隔符不能是空串，`maxToken` 不能是零或负数，构造时就报错。

## 三、EOF 和出错，都返回 false

`scan()` 的返回值只有真和假。到 EOF 是假，出错也是假，区别在 `err()`：

```fun
while sc.scan() do
  ?. sc.text();
end do;
if sc.err() <> nil then
  ?. 'scan failed: ' & sc.err();
end if;
```

为什么不用异常：逐行扫描本来就是一个循环，EOF 是正常终点，不是异常。把 EOF 做成异常，每读一个文件都要多一层 `try`，还会把真正的读错误和正常结束混在一起。现在读错误也走 `err()`，`token too long`、Reader 自己抛的异常、Reader 返回了非字符串，都记在那里。出错之后 `scan()` 一直返回假，`text()` 保留最后一个成功的 token，不会突然清空。

代价是调用方必须记得看 `err()`。忘了看，出错和读完就分不出来。这个取舍不完美，但比每个循环都包一层 `try` 干净。

## 四、Reader 的契约

Scanner 不关闭 Reader。`io.stdin()` 不该被关，`fs.open` 的句柄关不关由调用方决定，库不该替人做主。

它还会预读。为了判断一个 token 有没有结束，可能已经从 Reader 里多拿了一块。所以同一个 Reader 上，不要一边 `scanner()` 一边直接 `read()`，两边会抢数据。要么全交给 scanner，要么全自己读。

测试里有个 `_ShortReader`，每次 `read()` 只回一个字节。`'a\nb'` 在这种 Reader 上照样切出两个 token，说明分隔符跨缓冲块的情况是认真处理过的。另一个 `_FailReader` 专门在 `read()` 里抛异常，验证错误能落到 `err()` 而不是炸穿循环。

## 五、边界都写在测试里

`io.fun` 加了 113 行，`lib-io-test.fun` 加了 114 行，差不多一比一。覆盖的东西不花哨，都是会踩的：

空输入、只有分隔符、连续分隔符、末尾分隔符、CRLF、只有 `\r`、单字节 Reader、自定义分隔符、多字符分隔符、`maxToken` 正好等于长度和超出一个字节、Reader 抛异常、`nil` Reader、空分隔符、零 `maxToken`。还有一条容易忘的：出错之后 `text()` 保留原值。

这些断言没什么技术含量，但少一条，用户就会在某个边界上撞一次。

## 结语

`io.scanner` 不是新东西，Go 的 `bufio.Scanner` 早就在做同一件事，Fun 这边只是把接口换成了自己的 Reader 契约。真正有用的不是它多能干，是它把「读一行」这件事从业务代码里拿走了。以后读日志、读 CSV、读配置，不用每次再手写一遍缓冲区。

至于 64 KB 的 `maxToken` 够不够，得看具体场景。一行 JSON 超过 64 KB 的，这年头也不少见，那就显式传一个更大的值。默认值保的是大多数，不是全部。