IO.js Readline

穩(wěn)定度: 2 - 穩(wěn)定

通過require('readline')來使用這個模塊。Readline允許逐行讀取一個流（如process.stdin）。

注意，一旦你執(zhí)行了這個模塊，你的io.js程序在你關(guān)閉此接口之前，將不會退出。以下是如何讓你的程序優(yōu)雅的退出的例子：

var readline = require('readline');

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

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

  rl.close();
});

readline.createInterface(options)

創(chuàng)建一個readline接口實例。接受一個options對象，接受以下值：

• input - 需要監(jiān)聽的可讀流（必選）。

• output - 將逐行讀取的數(shù)據(jù)寫入的流（可選）。

• completer - 用于Tab自動補全的可選函數(shù)。參閱下文的使用例子。

• terminal - 如果input和output流需要被像一個TTY一樣對待，并且被經(jīng)由ANSI/VT100轉(zhuǎn)義代碼寫入，就傳遞true。默認為在實例化時，檢查出的ouput流的isTTY值。

• historySize - 保留的歷史記錄行的最大數(shù)量。默認為30。

completer函數(shù)被給予了一個用戶輸入的當前行，并且支持返回一個含有兩個元素的數(shù)組：

1. 一個匹配當前輸入補全的數(shù)組。

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同樣也可以以同步的方式運行，如果它接受兩個參數(shù)：

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

createInterface通常與process.stdin和process.stdout搭配，用來接受用戶輸入：

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

一旦你有了一個readline接口，你通常要監(jiān)聽一個line事件。

如果這個實例中，terminal為true。那么output流將會得到最好的兼容性，如果它定義了output.columns屬性，并且在output的columns變化時（當它是一個TTY時，process.stdout會自動這么做），觸發(fā)了一個resize事件。

Class: Interface

一個代表了有input和output流的readline接口。

rl.setPrompt(prompt)

設(shè)置提示符，例如當你在命令行運行iojs命令時，你看到了>，這就是io.js的提示符。

rl.prompt([preserveCursor])

為用戶的輸入準備好readline，在新的一行放置當前的setPrompt選項，給予用戶一個新的用于輸入的地方。設(shè)置preserveCursor為true，來防止光標位置被重置為0。

仍會重置被createInterface使用的input流，如果它被暫停。

如果當調(diào)用createInterface時output被設(shè)置為null或undefined，提示符將不會被寫入。

rl.question(query, callback)

帶著query來預先放置提示符，并且在用戶應(yīng)答時執(zhí)行回調(diào)函數(shù)。給用戶展示query，然后在用戶輸入了應(yīng)答后調(diào)用callback。

仍會重置被createInterface使用的input流，如果它被暫停。

如果當調(diào)用createInterface時output被設(shè)置為null或undefined，什么都不會被展示。

例子：

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

rl.pause()

暫停readline的input流，允許它在晚些需要時恢復。

注意，帶著事件的流不會立刻被暫停。在調(diào)用了pause后，許多事件可能被觸發(fā)，包括line事件。

rl.resume()

恢復readline的input流。

rl.close()

關(guān)閉實例接口，放棄對input和output流的控制。close事件也會被觸發(fā)。

rl.write(data[, key])

向output流寫入數(shù)據(jù)，除非當調(diào)用createInterface時output被設(shè)置為null或undefined。key是一個代表了鍵序列的對象；在當終端為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時觸發(fā)，通常在用戶敲下回車時觸發(fā)。這是一個監(jiān)聽用戶輸入的好鉤子。

例子：

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

Event: 'pause'

• function () {}

當input流被暫停時觸發(fā)。

也會在input沒有被暫停并且收到一個SIGCONT事件時觸發(fā)（參閱SIGTSTP事件和SIGCONT事件）。

例子：

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

Event: 'resume'

• function () {}

當input流被恢復時觸發(fā)。

例子：

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

Event: 'close'

• function () {}

當close()被調(diào)用時觸發(fā)。

也會在input流收到它的end事件時觸發(fā)。當這個事件觸發(fā)時，接口實例需要考慮“被結(jié)束”。例如，當input流接收到^D（也被認作EOT）。

這個事件也會在如果當前沒有SIGINT事件監(jiān)聽器，且input流接收到^C（也被認作SIGINT）時觸發(fā)。

Event: 'SIGINT'

• function () {}

當input流接收到^C（也被認作SIGINT）時觸發(fā)。如果當前沒有SIGINT事件的監(jiān)聽器，pause事件將會被觸發(fā)。

例子：

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）時觸發(fā)。如果當前沒有SIGTSTP事件的監(jiān)聽器，這個程序?qū)凰椭梁笈_運行。

當程序使用fg恢復，pause和SIGCONT事件都會被觸發(fā)。你可以選擇其中的一個來恢復流。

如果流在程序被送至后臺前就被暫停，pause和SIGCONT事件將不會觸發(fā)。

例子：

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）送至后臺時觸發(fā)，然后使用fg(1)繼續(xù)執(zhí)行。這個事件僅在程序被送至后臺前流沒有被暫停時觸發(fā)。

例子：

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

Example: Tiny CLI

下面是一個使用以上方法來創(chuàng)建一個迷你的控制臺接口的例子：

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)

從當前的光標位置，清除屏幕。