Node.js api 中文文档 - Readline


稳定度: 2 - 稳定

通过require('readline')来使用这个模块。Readline允许逐行读取一个流(如process.stdin)。

注意,一旦你执行了这个模块,你的node.js程序在你关闭此接口之前,将不会退出。以下是如何让你的程序优雅的退出的例子:

var readline = require('readline');

var rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
});

rl.question("What do you think of node.js? ", function(answer) {
  // TODO: Log the answer in a database
  console.log("Thank you for your valuable feedback:", answer);

  rl.close();
});

readline.createInterface(options)

创建一个readline接口实例。接受一个options对象,接受以下值:

  • input - 需要监听的可读流(必选)。

  • output - 将逐行读取的数据写入的流(可选)。

  • completer - 用于Tab自动补全的可选函数。参阅下文的使用例子。

  • terminal - 如果inputoutput流需要被像一个TTY一样对待,并且被经由ANSI/VT100转义代码写入,就传递true。默认为在实例化时,检查出的ouput流的isTTY值。

  • historySize - 保留的历史记录行的最大数量。默认为30

completer函数被给予了一个用户输入的当前行,并且支持返回一个含有两个元素的数组:

  1. 一个匹配当前输入补全的数组。

  2. 一个被用于匹配的子字符串。

最终形式如:[[substr1, substr2, ...], originalsubstring]

例子:

function completer(line) {
  var completions = '.help .error .exit .quit .q'.split(' ')
  var hits = completions.filter(function(c) { return c.indexOf(line) == 0 })
  // show all completions if none found
  return [hits.length ? hits : completions, line]
}

completer同样也可以以同步的方式运行,如果它接受两个参数:

function completer(linePartial, callback) {
  callback(null, [['123'], linePartial]);
}

createInterface通常与process.stdinprocess.stdout搭配,用来接受用户输入:

var readline = require('readline');
var rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
});

一旦你有了一个readline接口,你通常要监听一个line事件。

如果这个实例中,terminaltrue。那么output流将会得到最好的兼容性,如果它定义了output.columns属性,并且在outputcolumns变化时(当它是一个TTY时,process.stdout会自动这么做),触发了一个resize事件。

Class: Interface

一个代表了有inputoutput流的readline接口。

rl.setPrompt(prompt)

设置提示符,例如当你在命令行运行iojs命令时,你看到了>,这就是node.js的提示符。

rl.prompt([preserveCursor])

为用户的输入准备好readline,在新的一行放置当前的setPrompt选项,给予用户一个新的用于输入的地方。设置preserveCursortrue,来防止光标位置被重置为0

仍会重置被createInterface使用的input流,如果它被暂停。

如果当调用createInterfaceoutput被设置为nullundefined,提示符将不会被写入。

rl.question(query, callback)

带着query来预先放置提示符,并且在用户应答时执行回调函数。给用户展示query,然后在用户输入了应答后调用callback

仍会重置被createInterface使用的input流,如果它被暂停。

如果当调用createInterfaceoutput被设置为nullundefined,什么都不会被展示。

例子:

interface.question('What is your favorite food?', function(answer) {
  console.log('Oh, so your favorite food is ' + answer);
});

rl.pause()

暂停readlineinput流,允许它在晚些需要时恢复。

注意,带着事件的流不会立刻被暂停。在调用了pause后,许多事件可能被触发,包括line事件。

rl.resume()

恢复readlineinput流。

rl.close()

关闭实例接口,放弃对inputoutput流的控制。close事件也会被触发。

rl.write(data[, key])

output流写入数据,除非当调用createInterfaceoutput被设置为nullundefinedkey是一个代表了键序列的对象;在当终端为TTY时可用。

如果input流被暂停,它也会被恢复。

例子:

rl.write('Delete me!');
// Simulate ctrl+u to delete the line written previously
rl.write(null, {ctrl: true, name: 'u'});

Events

Event: 'line'

  • function (line) {}

input流收到一个\n时触发,通常在用户敲下回车时触发。这是一个监听用户输入的好钩子。

例子:

rl.on('line', function (cmd) {
  console.log('You just typed: '+cmd);
});

Event: 'pause'

  • function () {}

input流被暂停时触发。

也会在input没有被暂停并且收到一个SIGCONT事件时触发(参阅SIGTSTP事件和SIGCONT事件)。

例子:

rl.on('pause', function() {
  console.log('Readline paused.');
});

Event: 'resume'

  • function () {}

input流被恢复时触发。

例子:

rl.on('resume', function() {
  console.log('Readline resumed.');
});

Event: 'close'

  • function () {}

close()被调用时触发。

也会在input流收到它的end事件时触发。当这个事件触发时,接口实例需要考虑“被结束”。例如,当input流接收到^D(也被认作EOT)。

这个事件也会在如果当前没有SIGINT事件监听器,且input流接收到^C(也被认作SIGINT)时触发。

Event: 'SIGINT'

  • function () {}

input流接收到^C(也被认作SIGINT)时触发。如果当前没有SIGINT事件的监听器,pause事件将会被触发。

例子:

rl.on('SIGINT', function() {
  rl.question('Are you sure you want to exit?', function(answer) {
    if (answer.match(/^y(es)?$/i)) rl.pause();
  });
});

Event: 'SIGTSTP'

  • function () {}

在Windows平台下不能使用。

input流接收到一个^Z(也被认作SIGTSTP)时触发。如果当前没有SIGTSTP事件的监听器,这个程序将会被送至后台运行。

当程序使用fg恢复,pauseSIGCONT事件都会被触发。你可以选择其中的一个来恢复流。

如果流在程序被送至后台前就被暂停,pauseSIGCONT事件将不会触发。

例子:

rl.on('SIGTSTP', function() {
  // This will override SIGTSTP and prevent the program from going to the
  // background.
  console.log('Caught SIGTSTP.');
});

Event: 'SIGCONT'

  • function () {}

在Windows平台下不能使用。

input流被^Z(也被认作SIGTSTP)送至后台时触发,然后使用fg(1)继续执行。这个事件仅在程序被送至后台前流没有被暂停时触发。

例子:

rl.on('SIGCONT', function() {
  // `prompt` will automatically resume the stream
  rl.prompt();
});

Example: Tiny CLI

下面是一个使用以上方法来创建一个迷你的控制台接口的例子:

var readline = require('readline'),
    rl = readline.createInterface(process.stdin, process.stdout);

rl.setPrompt('OHAI> ');
rl.prompt();

rl.on('line', function(line) {
  switch(line.trim()) {
    case 'hello':
      console.log('world!');
      break;
    default:
      console.log('Say what? I might have heard `' + line.trim() + '`');
      break;
  }
  rl.prompt();
}).on('close', function() {
  console.log('Have a great day!');
  process.exit(0);
});

readline.cursorTo(stream, x, y)

在给定的TTY流中,将光标移动到指定位置。

readline.moveCursor(stream, dx, dy)

在给定的TTY流中,相对于当前位置,将光标移动到指定位置。

readline.clearLine(stream, dir)

用指定的方式,在给定的TTY流中,清除当前的行。dir可以是以下值之一:

  • -1 - 从光标的左边
  • 1 - 从光标的右边
  • 0 - 整行 #### readline.clearScreenDown(stream)#

从当前的光标位置,清除屏幕。

更多Node.js教程

学习更多Node.js教程