Node.js v25.0.0 ドキュメンテーション

イベント: 'close'#

'close' イベントは、以下のいずれかが発生したときに発行されます。

• rl.close() メソッドが呼び出され、InterfaceConstructor インスタンスが input と output ストリームの制御を解放したとき。
• input ストリームが 'end' イベントを受け取ったとき。
• input ストリームが送信終了(EOT)を知らせる Ctrl+D を受け取ったとき。
• input ストリームが SIGINT を知らせる Ctrl+C を受け取り、かつ InterfaceConstructor インスタンスに 'SIGINT' イベントリスナーが登録されていないとき。

リスナー関数は引数なしで呼び出されます。

'close' イベントが発行されると、InterfaceConstructor インスタンスは終了します。

イベント: 'line'#

'line' イベントは、input ストリームが改行入力 (\n, \r, または \r\n) を受け取るたびに発行されます。これは通常、ユーザーが Enter または Return を押したときに発生します。

'line' イベントは、ストリームから新しいデータが読み込まれ、そのストリームが最後の改行マーカーなしで終了した場合にも発行されます。

リスナー関数は、受信した一行の入力を含む文字列を引数として呼び出されます。

rl.on('line', (input) => {
  console.log(`Received: ${input}`);
}); copy

イベント: 'history'#

'history' イベントは、履歴配列が変更されるたびに発行されます。

リスナー関数は履歴配列を引数として呼び出されます。これは、追加された行や historySize と removeHistoryDuplicates によって削除された行など、すべての変更を反映します。

主な目的は、リスナーが履歴を永続化できるようにすることです。リスナーが履歴オブジェクトを変更することも可能です。これは、パスワードのような特定の行が履歴に追加されるのを防ぐのに役立ちます。

rl.on('history', (history) => {
  console.log(`Received: ${history}`);
}); copy

イベント: 'pause'#

'pause' イベントは、以下のいずれかが発生したときに発行されます。

• input ストリームが一時停止されたとき。
• input ストリームが一時停止されておらず、'SIGCONT' イベントを受け取ったとき。(イベント 'SIGTSTP' と 'SIGCONT' を参照)

リスナー関数は引数なしで呼び出されます。

rl.on('pause', () => {
  console.log('Readline paused.');
}); copy

イベント: 'resume'#

'resume' イベントは、input ストリームが再開されるたびに発行されます。

リスナー関数は引数なしで呼び出されます。

rl.on('resume', () => {
  console.log('Readline resumed.');
}); copy

イベント: 'SIGCONT'#

'SIGCONT' イベントは、以前に Ctrl+Z (すなわち SIGTSTP) を使ってバックグラウンドに移動した Node.js プロセスが、fg(1p) を使ってフォアグラウンドに戻されたときに発行されます。

SIGTSTP リクエストの *前* に input ストリームが一時停止されていた場合、このイベントは発行されません。

リスナー関数は引数なしで呼び出されます。

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

'SIGCONT' イベントは Windows ではサポートされて *いません*。

イベント: 'SIGINT'#

'SIGINT' イベントは、input ストリームが Ctrl+C 入力 (通常 SIGINT として知られる) を受け取るたびに発行されます。input ストリームが SIGINT を受け取ったときに 'SIGINT' イベントリスナーが登録されていない場合、'pause' イベントが発行されます。

リスナー関数は引数なしで呼び出されます。

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

イベント: 'SIGTSTP'#

'SIGTSTP' イベントは、input ストリームが Ctrl+Z 入力 (通常 SIGTSTP として知られる) を受け取ったときに発行されます。input ストリームが SIGTSTP を受け取ったときに 'SIGTSTP' イベントリスナーが登録されていない場合、Node.js プロセスはバックグラウンドに送られます。

プログラムが fg(1p) を使って再開されると、'pause' と 'SIGCONT' イベントが発行されます。これらは input ストリームを再開するために使用できます。

プロセスがバックグラウンドに送られる前に input が一時停止されていた場合、'pause' と 'SIGCONT' イベントは発行されません。

リスナー関数は引数なしで呼び出されます。

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

'SIGTSTP' イベントは Windows ではサポートされて *いません*。

rl.close()#

rl.close() メソッドは InterfaceConstructor インスタンスを閉じ、input と output ストリームの制御を解放します。呼び出されると、'close' イベントが発行されます。

rl.close() を呼び出しても、InterfaceConstructor インスタンスによる他のイベント ('line' を含む) の発行が直ちに停止するわけではありません。

rl[Symbol.dispose]()#

rl.close() のエイリアスです。

rl.pause()#

rl.pause() メソッドは input ストリームを一時停止し、後で必要に応じて再開できるようにします。

rl.pause() を呼び出しても、InterfaceConstructor インスタンスによる他のイベント ('line' を含む) の発行が直ちに停止するわけではありません。

rl.prompt([preserveCursor])#

• preserveCursor <boolean> true の場合、カーソル位置が 0 にリセットされるのを防ぎます。

rl.prompt() メソッドは、InterfaceConstructor インスタンスに設定された prompt を output の新しい行に書き込み、ユーザーが入力を行うための新しい場所を提供します。

rl.prompt() を呼び出すと、一時停止されていた場合、input ストリームが再開されます。

InterfaceConstructor が output を null または undefined に設定して作成された場合、プロンプトは書き込まれません。

rl.resume()#

rl.resume() メソッドは、一時停止されている場合に input ストリームを再開します。

rl.setPrompt(prompt)#

• prompt <string>

rl.setPrompt() メソッドは、rl.prompt() が呼び出されるたびに output に書き込まれるプロンプトを設定します。

rl.getPrompt()#

• 戻り値: <string> 現在のプロンプト文字列

rl.getPrompt() メソッドは、rl.prompt() で使用される現在のプロンプトを返します。

rl.write(data[, key])#

• data <string>
• key <Object>
  • ctrl <boolean> Ctrl キーを示す場合は true。
  • meta <boolean> Meta キーを示す場合は true。
  • shift <boolean> Shift キーを示す場合は true。
  • name <string> キーの名前。

rl.write() メソッドは data または key によって識別されるキーシーケンスを output に書き込みます。key 引数は、output が TTY テキストターミナルである場合にのみサポートされます。キーの組み合わせのリストについては TTY キーバインディング を参照してください。

key が指定された場合、data は無視されます。

rl.write() を呼び出すと、一時停止されていた場合、input ストリームが再開されます。

InterfaceConstructor が output を null または undefined に設定して作成された場合、data と key は書き込まれません。

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

rl.write() メソッドは、あたかも *ユーザーによって提供されたかのように*、readline Interface の input にデータを書き込みます。

rl[Symbol.asyncIterator]()#

• 戻り値: <AsyncIterator>

入力ストリームの各行を文字列として反復処理する AsyncIterator オブジェクトを作成します。このメソッドにより、for await...of ループを通じて InterfaceConstructor オブジェクトの非同期反復が可能になります。

入力ストリームのエラーは転送されません。

ループが break、throw、または return で終了した場合、rl.close() が呼び出されます。言い換えると、InterfaceConstructor を反復処理すると、常に入力ストリームが完全に消費されます。

パフォーマンスは従来の 'line' イベント API と同等ではありません。パフォーマンスが重要なアプリケーションでは、代わりに 'line' を使用してください。

async function processLineByLine() {
  const rl = readline.createInterface({
    // ...
  });

  for await (const line of rl) {
    // Each line in the readline input will be successively available here as
    // `line`.
  }
} copy

readline.createInterface() は、呼び出されると入力ストリームの消費を開始します。インターフェース作成と非同期反復の間に非同期操作があると、行が失われる可能性があります。

rl.line#

• 型: <string>

node によって処理されている現在の入力データです。

これは、TTY ストリームから入力を収集する際に、line イベントが発行される前に、これまでに処理された現在の値を取得するために使用できます。line イベントが発行されると、このプロパティは空の文字列になります。

インスタンスの実行時にこの値を変更すると、rl.cursor も制御されていない場合に意図しない結果になる可能性があることに注意してください。

入力に TTY ストリームを使用していない場合は、'line' イベントを使用してください。

考えられる使用例の一つは次のとおりです。

const values = ['lorem ipsum', 'dolor sit amet'];
const rl = readline.createInterface(process.stdin);
const showResults = debounce(() => {
  console.log(
    '\n',
    values.filter((val) => val.startsWith(rl.line)).join(' '),
  );
}, 300);
process.stdin.on('keypress', (c, k) => {
  showResults();
}); copy

rl.cursor#

• 型: <number> | <undefined>

rl.line に対する相対的なカーソル位置です。

これは、TTY ストリームから入力を読み取る際に、現在のカーソルが入力文字列のどこにあるかを追跡します。カーソルの位置は、入力が処理される際に変更される入力文字列の部分、およびターミナルのキャレットが表示される列を決定します。

rl.getCursorPos()#

• 戻り値: <Object>
  • rows <number> カーソルが現在置かれているプロンプトの行
  • cols <number> カーソルが現在置かれている画面の列

入力プロンプト＋文字列に関連するカーソルの実際の位置を返します。長い入力（折り返し）文字列や複数行のプロンプトも計算に含まれます。

クラス: readlinePromises.Interface#

• 拡張元: <readline.InterfaceConstructor>

readlinePromises.Interface クラスのインスタンスは readlinePromises.createInterface() メソッドを使って構築されます。各インスタンスは、単一の input Readable ストリームと単一の output Writable ストリームに関連付けられています。output ストリームは、input ストリームに到着し、そこから読み取られるユーザー入力のためのプロンプトを表示するために使用されます。

const answer = await rl.question('What is your favorite food? ');
console.log(`Oh, so your favorite food is ${answer}`); copy

const signal = AbortSignal.timeout(10_000);

signal.addEventListener('abort', () => {
  console.log('The food question timed out');
}, { once: true });

const answer = await rl.question('What is your favorite food? ', { signal });
console.log(`Oh, so your favorite food is ${answer}`); copy

クラス: readlinePromises.Readline#

readlinePromises.createInterface(options)#

• options <Object>
  • input <stream.Readable> リッスンする Readable ストリーム。このオプションは *必須* です。
  • output <stream.Writable> readline データを書き込む Writable ストリーム。
  • completer <Function> タブのオートコンプリートに使用されるオプションの関数。
  • terminal <boolean> input と output ストリームを TTY のように扱い、ANSI/VT100 エスケープコードを書き込む場合は true。デフォルト: インスタンス化時に output ストリームで isTTY をチェックします。
  • history <string[]> 履歴行の初期リスト。このオプションは、terminal がユーザーによって、または内部の output チェックによって true に設定されている場合にのみ意味があります。そうでない場合、履歴キャッシュメカニズムはまったく初期化されません。デフォルト: []。
  • historySize <number> 保持される履歴行の最大数。履歴を無効にするには、この値を 0 に設定します。このオプションは、terminal がユーザーによって、または内部の output チェックによって true に設定されている場合にのみ意味があります。そうでない場合、履歴キャッシュメカニズムはまったく初期化されません。デフォルト: 30。
  • removeHistoryDuplicates <boolean> true の場合、履歴リストに追加された新しい入力行が古いものと重複する場合、古い行をリストから削除します。デフォルト: false。
  • prompt <string> 使用するプロンプト文字列。デフォルト: '> '。
  • crlfDelay <number> \r と \n の間の遅延が crlfDelay ミリ秒を超える場合、\r と \n の両方が別々の改行入力として扱われます。crlfDelay は 100 以上の数値に強制されます。Infinity に設定することもでき、その場合、\r に続く \n は常に単一の改行と見なされます (これは \r\n 行区切り文字でファイルを読み取る場合に合理的かもしれません)。デフォルト: 100。
  • escapeCodeTimeout <number> 曖昧なキーシーケンス (これまでの入力で完全なキーシーケンスを形成でき、かつより長いキーシーケンスを完成させるため追加の入力を受け取ることができるもの) を読み取る際に、readlinePromises が文字を待機する時間 (ミリ秒単位)。デフォルト: 500。
  • tabSize <integer> タブが等しいスペースの数 (最小 1)。デフォルト: 8。
  • signal <AbortSignal> AbortSignal を使用してインターフェースを閉じることができます。
• 戻り値: <readlinePromises.Interface>

readlinePromises.createInterface() メソッドは、新しい readlinePromises.Interface インスタンスを作成します。

import { createInterface } from 'node:readline/promises';
import { stdin, stdout } from 'node:process';
const rl = createInterface({
  input: stdin,
  output: stdout,
});const { createInterface } = require('node:readline/promises');
const rl = createInterface({
  input: process.stdin,
  output: process.stdout,
});copy

readlinePromises.Interface インスタンスが作成されたら、最も一般的なケースは 'line' イベントをリッスンすることです。

rl.on('line', (line) => {
  console.log(`Received: ${line}`);
}); copy

このインスタンスで terminal が true の場合、output ストリームが output.columns プロパティを定義し、列が変更された場合に output で 'resize' イベントを発行すると、最高の互換性が得られます (process.stdout は TTY の場合、これを自動的に行います)。

function completer(line) {
  const completions = '.help .error .exit .quit .q'.split(' ');
  const hits = completions.filter((c) => c.startsWith(line));
  // Show all completions if none found
  return [hits.length ? hits : completions, line];
} copy

async function completer(linePartial) {
  await someAsyncWork();
  return [['123'], linePartial];
} copy

クラス: readline.Interface#

• 拡張元: <readline.InterfaceConstructor>

readline.Interface クラスのインスタンスは readline.createInterface() メソッドを使って構築されます。各インスタンスは、単一の input Readable ストリームと単一の output Writable ストリームに関連付けられています。output ストリームは、input ストリームに到着し、そこから読み取られるユーザー入力のためのプロンプトを表示するために使用されます。

rl.question('What is your favorite food? ', (answer) => {
  console.log(`Oh, so your favorite food is ${answer}`);
}); copy

const ac = new AbortController();
const signal = ac.signal;

rl.question('What is your favorite food? ', { signal }, (answer) => {
  console.log(`Oh, so your favorite food is ${answer}`);
});

signal.addEventListener('abort', () => {
  console.log('The food question timed out');
}, { once: true });

setTimeout(() => ac.abort(), 10000); copy

readline.clearLine(stream, dir[, callback])#

• stream <stream.Writable>
• dir <number>
  • -1: カーソルから左側
  • 1: カーソルから右側
  • 0: 行全体
• callback <Function> 操作が完了したときに呼び出されます。
• 戻り値: <boolean> stream が、追加のデータを書き続ける前に 'drain' イベントが発行されるのを呼び出し元コードに待機させたい場合は false。それ以外は true。

readline.clearLine() メソッドは、指定された TTY ストリームの現在の行を dir で指定された方向にクリアします。

readline.clearScreenDown(stream[, callback])#

• stream <stream.Writable>
• callback <Function> 操作が完了したときに呼び出されます。
• 戻り値: <boolean> stream が、追加のデータを書き続ける前に 'drain' イベントが発行されるのを呼び出し元コードに待機させたい場合は false。それ以外は true。

readline.clearScreenDown() メソッドは、指定された TTY ストリームをカーソルの現在位置から下に向かってクリアします。

readline.createInterface(options)#

• options <Object>
  • input <stream.Readable> リッスンする Readable ストリーム。このオプションは *必須* です。
  • output <stream.Writable> readline データを書き込む Writable ストリーム。
  • completer <Function> タブのオートコンプリートに使用されるオプションの関数。
  • terminal <boolean> input と output ストリームを TTY のように扱い、ANSI/VT100 エスケープコードを書き込む場合は true。デフォルト: インスタンス化時に output ストリームで isTTY をチェックします。
  • history <string[]> 履歴行の初期リスト。このオプションは、terminal がユーザーによって、または内部の output チェックによって true に設定されている場合にのみ意味があります。そうでない場合、履歴キャッシュメカニズムはまったく初期化されません。デフォルト: []。
  • historySize <number> 保持される履歴行の最大数。履歴を無効にするには、この値を 0 に設定します。このオプションは、terminal がユーザーによって、または内部の output チェックによって true に設定されている場合にのみ意味があります。そうでない場合、履歴キャッシュメカニズムはまったく初期化されません。デフォルト: 30。
  • removeHistoryDuplicates <boolean> true の場合、履歴リストに追加された新しい入力行が古いものと重複する場合、古い行をリストから削除します。デフォルト: false。
  • prompt <string> 使用するプロンプト文字列。デフォルト: '> '。
  • crlfDelay <number> \r と \n の間の遅延が crlfDelay ミリ秒を超える場合、\r と \n の両方が別々の改行入力として扱われます。crlfDelay は 100 以上の数値に強制されます。Infinity に設定することもでき、その場合、\r に続く \n は常に単一の改行と見なされます (これは \r\n 行区切り文字でファイルを読み取る場合に合理的かもしれません)。デフォルト: 100。
  • escapeCodeTimeout <number> 曖昧なキーシーケンス (これまでの入力で完全なキーシーケンスを形成でき、かつより長いキーシーケンスを完成させるため追加の入力を受け取ることができるもの) を読み取る際に、readline が文字を待機する時間 (ミリ秒単位)。デフォルト: 500。
  • tabSize <integer> タブが等しいスペースの数 (最小 1)。デフォルト: 8。
  • signal <AbortSignal> AbortSignal を使用してインターフェースを閉じることができます。シグナルを中止すると、内部的にインターフェースで close が呼び出されます。
• 戻り値: <readline.Interface>

readline.createInterface() メソッドは、新しい readline.Interface インスタンスを作成します。

import { createInterface } from 'node:readline';
import { stdin, stdout } from 'node:process';
const rl = createInterface({
  input: stdin,
  output: stdout,
});const { createInterface } = require('node:readline');
const rl = createInterface({
  input: process.stdin,
  output: process.stdout,
});copy

readline.Interface インスタンスが作成されたら、最も一般的なケースは 'line' イベントをリッスンすることです。

rl.on('line', (line) => {
  console.log(`Received: ${line}`);
}); copy

このインスタンスで terminal が true の場合、output ストリームが output.columns プロパティを定義し、列が変更された場合に output で 'resize' イベントを発行すると、最高の互換性が得られます (process.stdout は TTY の場合、これを自動的に行います)。

stdin を入力として readline.Interface を作成する場合、プログラムは EOF 文字 を受け取るまで終了しません。ユーザー入力を待たずに終了するには、process.stdin.unref() を呼び出します。

function completer(line) {
  const completions = '.help .error .exit .quit .q'.split(' ');
  const hits = completions.filter((c) => c.startsWith(line));
  // Show all completions if none found
  return [hits.length ? hits : completions, line];
} copy

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

readline.cursorTo(stream, x[, y][, callback])#

• stream <stream.Writable>
• x <number>
• y <number>
• callback <Function> 操作が完了したときに呼び出されます。
• 戻り値: <boolean> stream が、追加のデータを書き続ける前に 'drain' イベントが発行されるのを呼び出し元コードに待機させたい場合は false。それ以外は true。

readline.cursorTo() メソッドは、指定された TTY stream 内でカーソルを指定された位置に移動します。

readline.moveCursor(stream, dx, dy[, callback])#

• stream <stream.Writable>
• dx <number>
• dy <number>
• callback <Function> 操作が完了したときに呼び出されます。
• 戻り値: <boolean> stream が、追加のデータを書き続ける前に 'drain' イベントが発行されるのを呼び出し元コードに待機させたい場合は false。それ以外は true。

readline.moveCursor() メソッドは、指定された TTY stream 内でカーソルを現在位置から *相対的に* 移動します。