Node.js v0.10.18 手册 & 文档

Readline#

稳定度: 2 - 不稳定

To use this module, do require('readline'). Readline allows reading of a stream (such as process.stdin) on a line-by-line basis.

要使用此模块，需要require('readline').Readline程序允许逐行读取一个流内容(例如process.stdin).

Note that once you've invoked this module, your node program will not terminate until you've closed the interface. Here's how to allow your program to gracefully exit:

需要注意的是你一旦调用了这个模块，你的node程序将不会终止直到你关闭此接口。下面是如何让你的程序正常退出的方法:

  rl.close();
});

readline.createInterface(options)#

Creates a readline Interface instance. Accepts an "options" Object that takes the following values:

创建一个readline的接口实例. 接受一个Object类型参数，可传递以下几个值:

input - the readable stream to listen to (Required).
input - 要监听的可读流 (必需).
output - the writable stream to write readline data to (Required).
output - 要写入 readline 的可写流 (必须).
completer - an optional function that is used for Tab autocompletion. See below for an example of using this.
completer - 用于 Tab 自动补全的可选函数。见下面使用的例子。
terminal - pass true if the input and output streams should be treated like a TTY, and have ANSI/VT100 escape codes written to it. Defaults to checking isTTY on the output stream upon instantiation.
terminal - 如果希望 input 和 output 流像 TTY 一样对待，那么传递参数 true ，并且经由 ANSI/VT100 转码。默认情况下检查 isTTY 是否在 output 流上实例化。

The completer function is given a the current line entered by the user, and is supposed to return an Array with 2 entries:

通过用户 completer 函数给定了一个当前行入口，并且期望返回一个包含两个条目的数组：

An Array with matching entries for the completion.
一个匹配当前输入补全的字符串数组.
The substring that was used for the matching.
一个用于匹配的子字符串。

Which ends up looking something like: [[substr1, substr2, ...], originalsubstring].

最终像这种形式: [[substr1, substr2, ...], originalsubstring].

Example:

示例：

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]
}

Also completer can be run in async mode if it accepts two arguments:

completer 也可以运行在异步模式下，此时接受两个参数：

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

createInterface is commonly used with process.stdin and process.stdout in order to accept user input:

为了接受用户的输入，createInterface 通常跟 process.stdin 和 process.stdout 一块使用：

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

Once you have a readline instance, you most commonly listen for the "line" event.

一旦你有一个 readline 实例，你通常会监听 "line" 事件。

If terminal is true for this instance then the output stream will get the best compatibility if it defines an output.columns property, and fires a "resize" event on the output if/when the columns ever change (process.stdout does this automatically when it is a TTY).

如果这个实例中terminal为true，而且output流定义了一个output.columns属性，那么output流将获得最好的兼容性，并且，当columns变化时(当它是TTY时，process.stdout会自动这样做)，会在output上触发一个 "resize"事件。

类: 接口#

The class that represents a readline interface with an input and output stream.

代表一个有输入输出流的 readline 接口的类。

rl.setPrompt(prompt)#

Sets the prompt, for example when you run node on the command line, you see > , which is node's prompt.

设置提示符，例如当你在命令行运行 node 时，你会看到 > ，这就是 node 的提示符。

rl.prompt([preserveCursor])#

Readies readline for input from the user, putting the current setPrompt options on a new line, giving the user a new spot to write. Set preserveCursor to true to prevent the cursor placement being reset to 0.

为用户输入准备好readline，将现有的setPrompt选项放到新的一行，让用户有一个新的地方开始输入。将preserveCursor设为true来防止光标位置被重新设定成0。

This will also resume the input stream used with createInterface if it has been paused.

如果暂停，也会使用 createInterface 重置 input 流。

rl.question(query, callback)#

Prepends the prompt with query and invokes callback with the user's response. Displays the query to the user, and then invokes callback with the user's response after it has been typed.

预处理 query提示，用户应答时调用 callback . 当类型被确定后，将查询结果显示给用户, 然后在用户应答时调用 callback.

This will also resume the input stream used with createInterface if it has been paused.

如果暂停，也会使用 createInterface 重置 input 流。

Example usage:

使用示例：

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

rl.pause()#

Pauses the readline input stream, allowing it to be resumed later if needed.

暂停 readline 的输入流 (input stream), 如果有需要稍后还可以恢复。

rl.resume()#

Resumes the readline input stream.

恢复 readline 的输入流 (input stream).

rl.close()#

Closes the Interface instance, relinquishing control on the input and output streams. The "close" event will also be emitted.

关闭接口实例 (Interface instance), 放弃控制输入输出流。"close" 事件会被触发。

rl.write(data, [key])#

Writes data to output stream. key is an object literal to represent a key sequence; available if the terminal is a TTY.

将 data 写入到 output 流。key 是一个代表键序列的对象；当终端是一个 TTY 时可用。

This will also resume the input stream if it has been paused.

如果暂停，也会重置 input 流。

Example:

示例：

rl.write('Delete me!');
// 模仿 ctrl+u快捷键，删除之前所写行 
rl.write(null, {ctrl: true, name: 'u'});

Events#

Event: 'line'#

function (line) {}

Emitted whenever the input stream receives a \n, usually received when the user hits enter, or return. This is a good hook to listen for user input.

在 input 流接受了一个 \n 时触发，通常在用户敲击回车或者返回时接收。这是一个监听用户输入的利器。

Example of listening for line:

监听 line 事件的示例:

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

事件: 'pause'#

function () {}

Emitted whenever the input stream is paused.

不论何时，只要输入流被暂停就会触发。

Also emitted whenever the input stream is not paused and receives the SIGCONT event. (See events SIGTSTP and SIGCONT)

而在输入流未被暂停，但收到 SIGCONT 信号时也会触发。 (详见 SIGTSTP 和 SIGCONT 事件)

Example of listening for pause:

监听 pause 事件的示例：

rl.on('pause', function() {
  console.log('Readline 输入暂停.');
});

事件: 'resume'#

function () {}

Emitted whenever the input stream is resumed.

不论何时，只要输入流重新启用就会触发。

Example of listening for resume:

监听 resume 事件的示例：

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

事件: 'close'#

function () {}

Emitted when close() is called.

当 close() 被调用时触发。

Also emitted when the input stream receives its "end" event. The Interface instance should be considered "finished" once this is emitted. For example, when the input stream receives ^D, respectively known as EOT.

当 input流接收到"结束"事件时也会被触发. 一旦触发，应当认为Interface实例 "结束" . 例如, 当input流接收到^D时, 分别被认为EOT.

This event is also called if there is no SIGINT event listener present when the input stream receives a ^C, respectively known as SIGINT.

当 input 流接收到一个 ^C 时，即使没有 SIGINT 监听器，也会触发这个事件，分别被称为 SIGINT 。

Event: 'SIGINT'#

function () {}

Emitted whenever the input stream receives a ^C, respectively known as SIGINT. If there is no SIGINT event listener present when the input stream receives a SIGINT, pause will be triggered.

只要 input流接收到^C就会被触发, 分别被认为SIGINT.当input流接收到SIGINT时, 如果没有 SIGINT 事件监听器，pause 将会被触发.

Example of listening for SIGINT:

监听 SIGINT 信号的示例：

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 () {}

This does not work on Windows.

该功能不支持 windows 操作系统

Emitted whenever the input stream receives a ^Z, respectively known as SIGTSTP. If there is no SIGTSTP event listener present when the input stream receives a SIGTSTP, the program will be sent to the background.

只要input流接收到^Z时就被触发, 分别被认为SIGTSTP. 当input流接收到 SIGTSTP时，如果没有SIGTSTP 事件监听器 ,程序会被发送到后台 .

When the program is resumed with fg, the pause and SIGCONT events will be emitted. You can use either to resume the stream.

当程序使用参数 fg 重启，pause 和 SIGCONT 事件将会被触发。你可以使用两者中任一事件来恢复流。

The pause and SIGCONT events will not be triggered if the stream was paused before the program was sent to the background.

在程序被发送到后台之前，如果流暂停，pause 和 SIGCONT 事件将不会被触发。

Example of listening for SIGTSTP:

监听 SIGTSTP 的示例：

rl.on('SIGTSTP', function() {
  // 这将重载 SIGTSTP并防止程序转到
  // 后台.
  console.log('Caught SIGTSTP.');
});

Event: 'SIGCONT'#

function () {}

This does not work on Windows.

该功能不支持 windows 操作系统

Emitted whenever the input stream is sent to the background with ^Z, respectively known as SIGTSTP, and then continued with fg(1). This event only emits if the stream was not paused before sending the program to the background.

一旦 input流中含有 ^Z并被发送到后台就会触发,分别被认为 SIGTSTP, 然后继续执行fg(1). 这一事件只有在流被发送后台之前没有暂停才会触发.

Example of listening for SIGCONT:

监听 SIGCONT 的示例:

rl.on('SIGCONT', function() {
  // `prompt` 将会自动恢复流
  rl.prompt();
});

示例: Tiny CLI#

Here's an example of how to use all these together to craft a tiny command line interface:

这里有一个使用所有方法精心设计的小命令行程序：

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#

readline.createInterface(options)#

类: 接口#

rl.setPrompt(prompt)#

rl.prompt([preserveCursor])#

rl.question(query, callback)#

rl.pause()#

rl.resume()#

rl.close()#

rl.write(data, [key])#

Events#

Event: 'line'#

事件: 'pause'#

事件: 'resume'#

事件: 'close'#

Event: 'SIGINT'#

Event: 'SIGTSTP'#

Event: 'SIGCONT'#

示例: Tiny CLI#