1ReadKey(3) User Contributed Perl Documentation ReadKey(3)
2
6 Term::ReadKey - A perl module for simple terminal control
7
9 use Term::ReadKey;
10 ReadMode 4; # Turn off controls keys
11 while (not defined ($key = ReadKey(-1))) {
12 # No key yet
13 }
14 print "Get key $key\n";
15 ReadMode 0; # Reset tty mode before exiting
16
18 Term::ReadKey is a compiled perl module dedicated to providing simple
19 control over terminal driver modes (cbreak, raw, cooked, etc.,) support
20 for non-blocking reads, if the architecture allows, and some
21 generalized handy functions for working with terminals. One of the main
22 goals is to have the functions as portable as possible, so you can just
23 plug in "use Term::ReadKey" on any architecture and have a good
24 likelyhood of it working.
25 ReadMode MODE [, Filehandle]
27 Takes an integer argument, which can currently be one of the
28 following values:
29 0 Restore original settings.
31 1 Change to cooked mode.
32 2 Change to cooked mode with echo off.
33 (Good for passwords)
34 3 Change to cbreak mode.
35 4 Change to raw mode.
36 5 Change to ultra-raw mode.
37 (LF to CR/LF translation turned off)
38 Or, you may use the synonyms:
40 restore
42 normal
43 noecho
44 cbreak
45 raw
46 ultra-raw
47 These functions are automatically applied to the STDIN handle
49 if no other handle is supplied. Modes 0 and 5 have some special
50 properties worth mentioning: not only will mode 0 restore
51 original settings, but it cause the next ReadMode call to save
52 a new set of default settings. Mode 5 is similar to mode 4,
53 except no CR/LF translation is performed, and if possible,
54 parity will be disabled (only if not being used by the
55 terminal, however. It is no different from mode 4 under
56 Windows.)
57 If you are executing another program that may be changing the
59 terminal mode, you will either want to say
60 ReadMode 1
62 system('someprogram');
63 ReadMode 1;
64 which resets the settings after the program has run, or:
66 $somemode=1;
68 ReadMode 0;
69 system('someprogram');
70 ReadMode 1;
71 which records any changes the program may have made, before
73 resetting the mode.
74 ReadKey MODE [, Filehandle]
76 Takes an integer argument, which can currently be one of the
77 following values:
78 0 Perform a normal read using getc
80 -1 Perform a non-blocked read
81 >0 Perform a timed read
82 (If the filehandle is not supplied, it will default to STDIN.)
84 If there is nothing waiting in the buffer during a non-blocked
85 read, then undef will be returned. Note that if the OS does not
86 provide any known mechanism for non-blocking reads, then a
87 "ReadKey -1" can die with a fatal error. This will hopefully
88 not be common.
89 If MODE is greater then zero, then ReadKey will use it as a
91 timeout value in seconds (fractional seconds are allowed), and
92 won't return "undef" until that time expires. (Note, again,
93 that some OS's may not support this timeout behaviour.) If MODE
94 is less then zero, then this is treated as a timeout of zero,
95 and thus will return immediately if no character is waiting. A
96 MODE of zero, however, will act like a normal getc.
97 There are currently some limitations with this call under
99 Windows. It may be possible that non-blocking reads will fail
100 when reading repeating keys from more then one console.
101 ReadLine MODE [, Filehandle]
103 Takes an integer argument, which can currently be one of the
104 following values:
105 0 Perform a normal read using scalar(<FileHandle>)
107 -1 Perform a non-blocked read
108 >0 Perform a timed read
109 If there is nothing waiting in the buffer during a non-blocked
111 read, then undef will be returned. Note that if the OS does not
112 provide any known mechanism for non-blocking reads, then a
113 "ReadLine 1" can die with a fatal error. This will hopefully
114 not be common. Note that a non-blocking test is only performed
115 for the first character in the line, not the entire line. This
116 call will probably not do what you assume, especially with
117 ReadMode's higher then 1. For example, pressing Space and then
118 Backspace would appear to leave you where you started, but any
119 timeouts would now be suspended.
120 This call is currently not available under Windows.
122 GetTerminalSize [Filehandle]
124 Returns either an empty array if this operation is unsupported,
125 or a four element array containing: the width of the terminal
126 in characters, the height of the terminal in character, the
127 width in pixels, and the height in pixels. (The pixel size will
128 only be valid in some environments.)
129 Under Windows, this function must be called with an "output"
131 filehandle, such as STDOUT, or a handle opened to CONOUT$.
132 SetTerminalSize WIDTH,HEIGHT,XPIX,YPIX [, Filehandle]
134 Return -1 on failure, 0 otherwise. Note that this terminal size
135 is only for informative value, and changing the size via this
136 mechanism will not change the size of the screen. For example,
137 XTerm uses a call like this when it resizes the screen. If any
138 of the new measurements vary from the old, the OS will probably
139 send a SIGWINCH signal to anything reading that tty or pty.
140 This call does not work under Windows.
142 GetSpeeds [, Filehandle]
144 Returns either an empty array if the operation is unsupported,
145 or a two value array containing the terminal in and out speeds,
146 in decimal. E.g, an in speed of 9600 baud and an out speed of
147 4800 baud would be returned as (9600,4800). Note that currently
148 the in and out speeds will always be identical in some OS's. No
149 speeds are reported under Windows.
150 GetControlChars [, Filehandle]
152 Returns an array containing key/value pairs suitable for a
153 hash. The pairs consist of a key, the name of the control
154 character/signal, and the value of that character, as a single
155 character. This call does nothing under Windows.
156 Each key will be an entry from the following list:
158 DISCARD
160 DSUSPEND
161 EOF
162 EOL
163 EOL2
164 ERASE
165 ERASEWORD
166 INTERRUPT
167 KILL
168 MIN
169 QUIT
170 QUOTENEXT
171 REPRINT
172 START
173 STATUS
174 STOP
175 SUSPEND
176 SWITCH
177 TIME
178 Thus, the following will always return the current interrupt
180 character, regardless of platform.
181 %keys = GetControlChars;
183 $int = $keys{INTERRUPT};
184 SetControlChars [, Filehandle]
186 Takes an array containing key/value pairs, as a hash will
187 produce. The pairs should consist of a key that is the name of
188 a legal control character/signal, and the value should be
189 either a single character, or a number in the range 0-255.
190 SetControlChars will die with a runtime error if an invalid
191 character name is passed or there is an error changing the
192 settings. The list of valid names is easily available via
193 %cchars = GetControlChars();
195 @cnames = keys %cchars;
196 This call does nothing under Windows.
198
200 Kenneth Albanowski <kjahds@kjahds.com>
201 Currently maintained by Jonathan Stowe <jns@gellyfish.com>
203perl v5.16.3 2005-01-11 ReadKey(3)