Readline · io.js API 中文文檔

### 穩定度: 2 - 穩定通過`require('readline')`來使用這個模塊。`Readline`允許逐行讀取一個流（如`process.stdin`）。注意，一旦你執行了這個模塊，你的`io.js`程序在你關閉此接口之前，將不會退出。以下是如何讓你的程序優雅的退出的例子： ~~~ 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) 創建一個`readline`接口實例。接受一個`options`對象，接受以下值： - input - 需要監聽的可讀流（必選）。 - output - 將逐行讀取的數據寫入的流（可選）。 - completer - 用于Tab自動補全的可選函數。參閱下文的使用例子。 - terminal - 如果`input`和`output`流需要被像一個TTY一樣對待，并且被經由ANSI/VT100轉義代碼寫入，就傳遞`true`。默認為在實例化時，檢查出的`ouput`流的`isTTY`值。 - historySize - 保留的歷史記錄行的最大數量。默認為`30`。 `completer`函數被給予了一個用戶輸入的當前行，并且支持返回一個含有兩個元素的數組： 1. 一個匹配當前輸入補全的數組。 1. 一個被用于匹配的子字符串。最終形式如：`[[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.stdin`和`process.stdout`搭配，用來接受用戶輸入： ~~~ var readline = require('readline'); var rl = readline.createInterface({ input: process.stdin, output: process.stdout }); ~~~ 一旦你有了一個`readline`接口，你通常要監聽一個`line`事件。如果這個實例中，`terminal`為`true`。那么`output`流將會得到最好的兼容性，如果它定義了`output.columns`屬性，并且在`output`的`columns`變化時（當它是一個TTY時，`process.stdout`會自動這么做），觸發了一個`resize`事件。 #### Class: Interface 一個代表了有`input`和`output`流的`readline`接口。 #### rl.setPrompt(prompt) 設置提示符，例如當你在命令行運行`iojs`命令時，你看到了`>`，這就是`io.js`的提示符。 #### rl.prompt([preserveCursor]) 為用戶的輸入準備好`readline`，在新的一行放置當前的`setPrompt`選項，給予用戶一個新的用于輸入的地方。設置`preserveCursor`為`true`，來防止光標位置被重置為`0`。仍會重置被`createInterface`使用的`input`流，如果它被暫停。如果當調用`createInterface`時`output`被設置為`null`或`undefined`，提示符將不會被寫入。 #### rl.question(query, callback) 帶著`query`來預先放置提示符，并且在用戶應答時執行回調函數。給用戶展示`query`，然后在用戶輸入了應答后調用`callback`。仍會重置被`createInterface`使用的`input`流，如果它被暫停。如果當調用`createInterface`時`output`被設置為`null`或`undefined`，什么都不會被展示。例子： ~~~ interface.question('What is your favorite food?', function(answer) { console.log('Oh, so your favorite food is ' + answer); }); ~~~ #### rl.pause() 暫停`readline`的`input`流，允許它在晚些需要時恢復。注意，帶著事件的流不會立刻被暫停。在調用了`pause`后，許多事件可能被觸發，包括`line`事件。 #### rl.resume() 恢復`readline`的`input`流。 #### rl.close() 關閉實例接口，放棄對`input`和`output`流的控制。`close`事件也會被觸發。 #### rl.write(data[, key]) 向`output`流寫入數據，除非當調用`createInterface`時`output`被設置為`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`時觸發，通常在用戶敲下回車時觸發。這是一個監聽用戶輸入的好鉤子。例子： ~~~ 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`恢復，`pause`和`SIGCONT`事件都會被觸發。你可以選擇其中的一個來恢復流。如果流在程序被送至后臺前就被暫停，`pause`和`SIGCONT`事件將不會觸發。例子： ~~~ 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) 從當前的光標位置，清除屏幕。