Skip to content

Commit d5c95f0

Browse files
bnoordhuisbnoordhuis
committed
docs: rename readline.md to readline.markdown
1 parent 54bb53b commit d5c95f0

2 files changed

Lines changed: 109 additions & 170 deletions

File tree

‎doc/api/readline.markdown‎

Lines changed: 109 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,61 +1,133 @@
11
## Readline
22

3-
This module allows reading of a stream (such as STDIN) on a line-by-line basis.
3+
To use this module, do `require('readline')`. Readline allows reading of a
4+
stream (such as STDIN) on a line-by-line basis.
45

5-
Note that once you've invoked this module, your node program will not terminate
6-
until you've closed the interface, and the STDIN stream. Here's how to allow
7-
your program to gracefully terminate:
6+
Note that once you've invoked this module, your node program will not
7+
terminate until you've closed the interface, and the STDIN stream. Here's how
8+
to allow your program to gracefully terminate:
89

9-
<pre>
10-
var readline = require('readline');
10+
var rl = require('readline');
1111

12-
var i = readline.createInterface(process.sdtin, process.stdout, null);
13-
i.question("What do you think of node.js?", function(answer) {
14-
//TODO: Log the answer in a database
15-
console.log("Thank you for your valuable feedback.");
16-
i.close(); //These two lines together allow the program to
17-
process.stdin.destroy(); //terminate. Without them, it would run forever.
18-
});
19-
</pre>
12+
var i = rl.createInterface(process.sdtin, process.stdout, null);
13+
i.question("What do you think of node.js?", function(answer) {
14+
// TODO: Log the answer in a database
15+
console.log("Thank you for your valuable feedback.");
2016

21-
### createInterface(input, output, completer)
17+
// These two lines together allow the program to terminate. Without
18+
// them, it would run forever.
19+
i.close();
20+
process.stdin.destroy();
21+
});
2222

23-
Returns an interface object, which reads from input, and writes to output.
24-
TODO: I think "completer" is used for tab-completion, but not sure.
23+
### rl.createInterface(input, output, completer)
2524

26-
### interface.setPrompt(prompt, length)
25+
Takes two streams and creates a readline interface. The `completer` function
26+
is used for autocompletion. When given a substring, it returns `[[substr1,
27+
substr2, ...], originalsubstring]`.
2728

28-
TODO
29+
`createInterface` is commonly used with `process.stdin` and
30+
`process.stdout` in order to accept user input:
2931

30-
### interface.prompt()
32+
var readline = require('readline'),
33+
rl = readline.createInterface(process.stdin, process.stdout);
3134

32-
TODO: Appears to trigger showing the prompt.
35+
### rl.setPrompt(prompt, length)
3336

34-
### interface.question(query, cb)
37+
Sets the prompt, for example when you run `node` on the command line, you see
38+
`> `, which is node's prompt.
3539

36-
Displays the query to the user, and then calls the callback after the user
37-
has typed in their response.
40+
### rl.prompt()
41+
42+
Readies readline for input from the user, putting the current `setPrompt`
43+
options on a new line, giving the user a new spot to write.
44+
45+
<!-- ### rl.getColumns() Not available? -->
46+
47+
### rl.question(query, callback)
48+
49+
Prepends the prompt with `query` and invokes `callback` with the user's
50+
response. Displays the query to the user, and then invokes `callback` with the
51+
user's response after it has been typed.
3852

3953
Example usage:
4054

41-
<pre>
42-
interface.question("What is your favorite food?", function(answer) {
43-
console.log("Oh, so your favorite food is " + answer);
44-
});
45-
</pre>
55+
interface.question('What is your favorite food?', function(answer) {
56+
console.log('Oh, so your favorite food is ' + answer);
57+
});
58+
59+
### rl.close()
60+
61+
Closes tty.
62+
63+
### rl.pause()
64+
65+
Pauses tty.
66+
67+
### rl.resume()
68+
69+
Resumes tty.
70+
71+
### rl.write()
72+
73+
Writes to tty.
74+
75+
### Event: 'line'
76+
77+
`function (line) {}`
78+
79+
Emitted whenever the `in` stream receives a `\n`, usually received when the
80+
user hits enter, or return. This is a good hook to listen for user input.
81+
82+
Example of listening for `line`:
83+
84+
rl.on('line', function (cmd) {
85+
console.log('You just typed: '+cmd);
86+
});
87+
88+
### Event: 'close'
89+
90+
`function () {}`
4691

47-
### interface.close()
92+
Emitted whenever the `in` stream receives a `^C` or `^D`, respectively known
93+
as `SIGINT` and `EOT`. This is a good way to know the user is finished using
94+
your program.
4895

49-
TODO
96+
Example of listening for `close`, and exiting the program afterward:
5097

51-
### interface.pause()
98+
rl.on('close', function() {
99+
console.log('goodbye!');
100+
process.exit(0);
101+
});
52102

53-
TODO
103+
Here's an example of how to use all these together to craft a tiny command
104+
line interface:
54105

55-
### interface.resume()
106+
var readline = require('readline'),
107+
rl = readline.createInterface(process.stdin, process.stdout),
108+
prefix = 'OHAI> ';
56109

57-
TODO
110+
rl.on('line', function(line) {
111+
switch(line.trim()) {
112+
case 'hello':
113+
console.log('world!');
114+
break;
115+
default:
116+
console.log('Say what? I might have heard `' + line.trim() + '`');
117+
break;
118+
}
119+
rl.setPrompt(prefix, prefix.length);
120+
rl.prompt();
121+
}).on('close', function() {
122+
console.log('Have a great day!');
123+
process.exit(0);
124+
});
125+
console.log(prefix + 'Good to see you. Try typing stuff.');
126+
rl.setPrompt(prefix, prefix.length);
127+
rl.prompt();
58128

59-
### interface.write()
60129

61-
TODO
130+
Take a look at this slightly more complicated
131+
[example](https://gist.github.com/901104), and
132+
[http-console](http://github.com/cloudhead/http-console) for a real-life use
133+
case.

‎doc/api/readline.md‎

Lines changed: 0 additions & 133 deletions
This file was deleted.

0 commit comments

Comments
 (0)