{ "source": "doc/api/readline.markdown", "modules": [ { "textRaw": "Readline", "name": "readline", "stability": 3, "stabilityText": "Stable", "desc": "

To use this module, do require('readline'). Readline allows reading of a\nstream (such as STDIN) on a line-by-line basis.\n\n

\n

Note that once you've invoked this module, your node program will not\nterminate until you've closed the interface, and the STDIN stream. Here's how\nto allow your program to gracefully terminate:\n\n

\n
var rl = require('readline');\n\nvar i = rl.createInterface(process.stdin, process.stdout, null);\ni.question("What do you think of node.js?", function(answer) {\n  // TODO: Log the answer in a database\n  console.log("Thank you for your valuable feedback.");\n\n  // These two lines together allow the program to terminate. Without\n  // them, it would run forever.\n  i.close();\n  process.stdin.destroy();\n});
\n", "methods": [ { "textRaw": "rl.createInterface(input, output, completer)", "type": "method", "name": "createInterface", "desc": "

Takes two streams and creates a readline interface. The completer function\nis used for autocompletion. When given a substring, it returns [[substr1,\nsubstr2, ...], originalsubstring].\n\n

\n

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

\n

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

\n

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

\n
var readline = require('readline'),\n  rl = readline.createInterface(process.stdin, process.stdout);
\n", "signatures": [ { "params": [ { "name": "input" }, { "name": "output" }, { "name": "completer" } ] } ] } ], "classes": [ { "textRaw": "Class: Interface", "type": "class", "name": "Interface", "desc": "

The class that represents a readline interface with a stdin and stdout\nstream.\n\n

\n", "methods": [ { "textRaw": "rl.setPrompt(prompt, length)", "type": "method", "name": "setPrompt", "desc": "

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

\n", "signatures": [ { "params": [ { "name": "prompt" }, { "name": "length" } ] } ] }, { "textRaw": "rl.prompt()", "type": "method", "name": "prompt", "desc": "

Readies readline for input from the user, putting the current setPrompt\noptions on a new line, giving the user a new spot to write.\n\n

\n", "signatures": [ { "params": [] } ] }, { "textRaw": "rl.question(query, callback)", "type": "method", "name": "question", "desc": "

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

\n

Example usage:\n\n

\n
interface.question('What is your favorite food?', function(answer) {\n  console.log('Oh, so your favorite food is ' + answer);\n});
\n", "signatures": [ { "params": [ { "name": "query" }, { "name": "callback" } ] } ] }, { "textRaw": "rl.close()", "type": "method", "name": "close", "desc": "

Closes tty.\n\n

\n", "signatures": [ { "params": [] } ] }, { "textRaw": "rl.pause()", "type": "method", "name": "pause", "desc": "

Pauses tty.\n\n

\n", "signatures": [ { "params": [] } ] }, { "textRaw": "rl.resume()", "type": "method", "name": "resume", "desc": "

Resumes tty.\n\n

\n", "signatures": [ { "params": [] } ] }, { "textRaw": "rl.write()", "type": "method", "name": "write", "desc": "

Writes to tty.\n\n

\n", "signatures": [ { "params": [] } ] } ], "events": [ { "textRaw": "Event: 'line'", "type": "event", "name": "line", "desc": "

function (line) {}\n\n

\n

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

\n

Example of listening for line:\n\n

\n
rl.on('line', function (cmd) {\n  console.log('You just typed: '+cmd);\n});
\n", "params": [] }, { "textRaw": "Event: 'close'", "type": "event", "name": "close", "desc": "

function () {}\n\n

\n

Emitted whenever the in stream receives a ^C or ^D, respectively known\nas SIGINT and EOT. This is a good way to know the user is finished using\nyour program.\n\n

\n

Example of listening for close, and exiting the program afterward:\n\n

\n
rl.on('close', function() {\n  console.log('goodbye!');\n  process.exit(0);\n});
\n

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

\n
var readline = require('readline'),\n  rl = readline.createInterface(process.stdin, process.stdout),\n  prefix = 'OHAI> ';\n\nrl.on('line', function(line) {\n  switch(line.trim()) {\n    case 'hello':\n      console.log('world!');\n  break;\n    default:\n      console.log('Say what? I might have heard `' + line.trim() + '`');\n      break;\n  }\n  rl.setPrompt(prefix, prefix.length);\n  rl.prompt();\n}).on('close', function() {\n  console.log('Have a great day!');\n  process.exit(0);\n});\nconsole.log(prefix + 'Good to see you. Try typing stuff.');\nrl.setPrompt(prefix, prefix.length);\nrl.prompt();
\n

Take a look at this slightly more complicated\nexample, and\nhttp-console for a real-life use\ncase.\n

\n", "params": [] } ] } ], "type": "module", "displayName": "Readline" } ] }