Node.js v0.11.11 マニュアル & ドキュメンテーション

Readline#

Stability: 2 - Unstable

このモジュールを使用するには、require('readline') をします。 Readline はストリーム (たとえば process.stdin) を行ごとに読み込むことを可能にします。

このモジュールを一度起動すると、このインタフェースを クローズするまで node プログラムは終了しないことに注意してください。 プログラムをスムーズに終了する方法を以下に示します: 

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)#

行を読み込む Interface のインスタンスを作成します。 以下の値を含む options オブジェクトを受け取ります。

  • input - 監視する入力ストリーム (必須)。

  • output - 読み込んだデータを書くための出力ストリーム (必須)。

  • completer - タブによる自動補完のための関数 (オプション)。 後述の例を参照してください。

  • terminal - input および output ストリームが TTY デバイスで、 ANSI/VT100 エスケープコードを出力する場合は true を渡します。 デフォルトはインスタンス生成時に output に対して isTTY でチェックします。

completer 関数にはユーザが入力した現在の行が与えられ、 2 つのエントリを含む配列を返すことが期待されます:

  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.stdin と process.stdout が使用されます。 

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

readline のインスタンスを作成すると、ほとんどの場合 'line' イベントを 監視することになります。

もしこのインスタンスの terminal が true の場合、 output ストリームはもし outout.columns プロパティが定義されていれば それに適合し、カラム幅が変更されると output 上で 'resize' イベントが生成されます (process.stdout が TTY の場合、それは自動的に行われます)。

Class: Interface#

入力と出力を持つ readline インタフェースを表現するクラスです。

rl.setPrompt(prompt)#

プロンプトを設定します。 たとえば、コマンドプロンプトで node コマンドを実行すると、 > を見ることができます。これが Node のプロンプトです。

rl.prompt([preserveCursor])#

ユーザからの入力を 1 行読み込みます。 現在の setPrompt() の値を新しい行に出力し、 ユーザに新しい入力エリアを与えます。 preserveCursor を true に設定すると、カーソル位置が 0 にリセットされなくなります。

これは、 createInterface() によって使われる input ストリームが 中断されていれば再開します。

rl.question(query, callback)#

query をプロンプトとして、ユーザが応答すると callback を起動します。 ユーザに質問を表示し、ユーザが応答をタイプすると、callback が起動されます。

これは、 createInterface() によって使われる input ストリームが 中断されていれば再開します。

使用例: 

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

rl.pause()#

input ストリームからの入力を中断します。 必要なら後で再開することができます。

rl.resume()#

input ストリームからの入力を再開します。

rl.close()#

Interface のインスタンスをクローズし、input および output ストリームの 制御を解放します。'close' イベントも生成されます。

rl.write(data, [key])#

data を output ストリームに出力します。 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 を読み込むごとに生成されます。 通常、ユーザがエンターまたはリターンを打つごとに受信します。 これはユーザ入力のよいフックとなります。

line を監視する例: 

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

Event: 'pause'#

function () {}

input ストリームが中断されたときに生成されます。

input ストリームが中断されていない時に SIGCONT イベントを受信した際にも 生成されます (SIGTSTP および SIGCONT も参照してください)。

'pause' を監視する例: 

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

Event: 'resume'#

function () {}

input ストリームが再開された時に生成されます。

'resume' を監視する例: 

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

Event: 'close'#

function () {}

close() が呼ばれた場合に生成されます。

input ストリームが 'end' イベントを受け取った場合にも生成されます。 これが生成された後、Interface インスタンスは完了したと考えられるべきです。 例えば、input ストリームが EOT として知られる ^D を受け取った場合。

このイベントは SIGINT イベントリスナが与えられていない場合に、 input ストリームが SIGINT として知られる ^C を受け取った場合にも 生成されます。

Event: 'SIGINT'#

function () {}

input ストリームが SIGINT として知られる ^C を受信した場合に 生成されます。 もし input ストリームが SIGINT を受信した時に 'SIGINT' イベントの リスナが存在しなければ、'pause' イベントがトリガされます。

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

これは Windows では動作しません。

input ストリームが SIGTSTP として知られる ^Z を受信した場合に 生成されます。 もし input ストリームが SIGTSTP を受信した時に 'SIGTSTP' イベントの リスナが存在しなければ、プログラムはバックグラウンドに送られます。

プログラムが fg により再開されると、'pause' および 'SIGCONT' イベントが 生成されます。どちらもストリームを再開するために使うことができます。

プログラムがバックグラウンドに送られる前にストリームが中断されていると、 'pause' および 'SIGCONT' イベントは生成されません。

'SIGTSTP' を監視する例: 

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 ストリームが SIGTSTP として知られる ^Z によってバックグラウンドに 送られた後で、fg(1) によって再開されるた場合に生成されます。 このイベントはプログラムがバックグラウンドに送られる前にストリームが中断されていなかった場合にのみ生成されます。

'SIGCONT' を監視する例: 

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)#

スクリーンのカーソルより下を消去します。