Line Reader 技术文档

本文档旨在帮助用户安装、使用以及理解 Line Reader 的 API。Line Reader 是一个异步、缓冲的逐行文件/流读取器，支持用户自定义行分隔符。

1. 安装指南

要安装 Line Reader，请在命令行中运行以下命令：

npm install line-reader

2. 项目使用说明

Line Reader 提供了多种读取文件的方式，以下是一些基本的使用示例：

eachLine 方法

eachLine 函数逐行读取给定文件。每读取一行，就会调用提供的回调函数，并传入读取的行和一个布尔值，指示是否为文件的最后一行。如果回调返回 false，则停止读取并关闭文件。

var lineReader = require('line-reader');

lineReader.eachLine('file.txt', function(line, last) {
  console.log(line);

  if (/* done */) {
    return false; // 停止读取
  }
});

eachLine 也可以以异步方式使用，通过提供第三个回调参数：

var lineReader = require('line-reader');

lineReader.eachLine('file.txt', function(line, last, cb) {
  console.log(line);

  if (/* done */) {
    cb(false); // 停止读取
  } else {
    cb();
  }
});

完成回调

可以提供一个可选的第二个回调函数，当读取失败时调用（错误），或者当读取完成时调用（即使通过返回 false 手动终止迭代）：

var lineReader = require('line-reader');

lineReader.eachLine('file.txt', function(line) {
  console.log(line);
}, function (err) {
  if (err) throw err;
  console.log("读取完成！");
});

更多控制

对于更细粒度的控制，可以使用 open、hasNextLine 和 nextLine 方法逐行迭代文件（但必须自己关闭它）：

var lineReader = require('line-reader');

lineReader.open('file.txt', function(err, reader) {
  if (err) throw err;
  if (reader.hasNextLine()) {
    reader.nextLine(function(err, line) {
      try {
        if (err) throw err;
        console.log(line);
      } finally {
        reader.close(function(err) {
          if (err) throw err;
        });
      }
    });
  } else {
    reader.close(function(err) {
      if (err) throw err;
    });
  }
});

选项

可以在 eachLine 或 open 的回调之前提供额外的选项：

• separator - 行分隔符（默认为 /\r\n?|\n/）
• encoding - 文件编码（默认为 'utf8'）
• bufferSize - 缓冲的字节数（默认为 1024）

例如：

lineReader.eachLine('file.txt', {separator: ';', encoding: 'utf8'}, function(line, last, cb) {
  console.log(line);
});
lineReader.open('file.txt', {bufferSize: 1024}, function(err, reader) {
  ...
});

3. 项目API使用文档

Streams

eachLine 和 open 支持传递文件名或读取流：

// 从 stdin 读取
lineReader.eachLine(process.stdin, function(line) {});

// 使用文件位置界限读取
var readStream = fs.createReadStream('test.log', { start: 0, end: 10000 });
lineReader.eachLine(readStream, function(line) {});

注意，如果从 stdin 读取用户输入，则 readline 模块 可能是更好的选择。

Promises

eachLine 和 open 可以与 bluebird 的 promisify 函数兼容：

var lineReader = require('line-reader'),
    Promise = require('bluebird');

var eachLine = Promise.promisify(lineReader.eachLine);
eachLine('file.txt', function(line) {
  console.log(line);
}).then(function() {
  console.log('完成');
}).catch(function(err) {
  console.error(err);
});

如果使用的承诺库没有 promisify 函数，以下是如何实现的示例：

var lineReader = require('line-reader'),
    Promise = require(...);

var eachLine = function(filename, options, iteratee) {
  return new Promise(function(resolve, reject) {
    lineReader.eachLine(filename, options, iteratee, function(err) {
      if (err) {
        reject(err);
      } else {
        resolve();
      }
    });
  });
}
eachLine('file.txt', function(line) {
  console.log(line);
}).then(function() {
  console.log('完成');
}).catch(function(err) {
  console.error(err);
});

4. 项目安装方式

请参考上文“安装指南”部分，使用 npm 命令安装 Line Reader：

npm install line-reader