blib/lib/Term/GetKey.pm untested

filter: Statementstmt 0.0% 0 / 174 Branchbran 0.0% 0 / 136 Conditioncond 0.0% 0 / 12 MC/DCmcdc 0.0% 0 / 7 Subroutinesub 0.0% 0 / 29 Podpod 0.0% 0 / 22 totaltotal 0.0% 0 / 380 CC 59 SCAR 52.4
CC
59
Cov
0%
qtty
506.0
Kmstatus
156.0
query
90.0
CRAP 188.3
1 =head1 NAME
2  
3 Term::GetKey - A perl module for quick easy simple key control
4  
5 =head1 SYNOPSIS
6  
7 perl Version 5.6.0 or higher is required because it uses the module warnings:
8  
9 use Term::GetKey;
10  
11 Term::ReadKey is used to change the terminal settings.
12  
13 =head1 DESCRIPTION
14  
15 This module changes the settings of Term::ReadKey using the `\' as a toggle key. qtty() makes a single character request to Term::ReadKey which is esential for the functionality of this module. `|' toggles the case of the output character to UPPERCase lowercase or off. qtty() and keypasswd() and query() use chomp on all input.
16  
17 use Term::Getkey;
18  
19 my $ch;#$ch can be any scalar variable
20  
21 $ch = qtty();#single character good for menus.
22 The methods in this module are dynamically loded so you do not need the full prefix Term::GetKey-> prefix to call a method.
23  
24 status();
25  
26 will announce the key strokes the module uses.
27  
28 The Term::ReadKey reserve words:
29  
30 ReadKey ReadMode ReadLine GetTerminalSize SetTerminalSize
31  
32 GetSpeed GetControlChars SetControlChars
33  
34 are still available and functional.
35  
36 qtty() keypasswd() query() status() setkeymode()
37  
38 keymode() setannounce() announcestatus() setcase() casestatus() Kmstatus() is the list of methods that do not require the full system path and module name before the method name.
39  
40 When you press `|' or `\' and then a `\\n' depending on the settings you cycle
41 through the settings of Term::ReadKey. The keys effected by Term::GetKey->qtty are disabled in noecho mode. When Term::GetKey is in (cbreak, raw or ultra-raw) modes the `\n' or enter key is not required.
42  
43 =head1 The following methods are called by qtty()
44  
45 setanounce() `~'
46  
47 setcase() `|'
48  
49 setkeymode() `\\' the backslash key
50 Terminat your program with '`' the grav accent key. warnings is used so the line number is announced so you know that Term::Getkey terminated your module fore you.
51  
52 keypasswd() calls qtty to create a password. This saves a call to stty - echo and stty echo.
53  
54 my $opt_passwd;
55  
56 $opt_passwd = keypasswd();
57  
58 query() calls setcase() `|'
59  
60 If you wish to have a `|' as the only character on the line: `\|' will cause query() to remove the `\\' and `|' will be sent as the string.
61  
62 The announcements are not disabled when you call qtty() or query() if they are waiting for a request and you press '|' or '\\'. You can disable the announcements with a call to set_announce(). The functions setcase() setkeymode() casestatus() and Kmstatus return the current value or the changed value of their called method.
63  
64 =head1 keymode Settings
65  
66 0 Restore original settings. 1 Change to normal mode.
67 2 Change to cooked mode with echo off. (Good for passwords) strings are uneffected
68 3 Change to cbreak mode. 4 Change to raw mode.
69 5 Change to ultra-raw mode. (LF to CR/LF translation turned off)
70  
71 =head1 GetKey announces the synonyms:
72  
73 restore
74 normal
75 noecho
76 cbreak
77 raw
78 ultra-raw
79  
80 The Default for qtty() is cbreak.
81  
82 qtty() handles each key individually. It returns to the `normal' mode after each key has been pressed so that you can continue with your programming allowing you flexability. When case conversion is activated with the `|' or called via a program it takes priority over your current case settings. It saves your current setting and sets itself so that other programs run normally. The default setting for its case conversion is off (no translation). You can toggle or query the settings with the following calls:
83  
84 status();
85  
86 my $myval;
87 $myval = casestatus();
88  
89 $myval = Kmstatus();
90  
91 #change the case of the key requested and announce the setting
92  
93 my $keymodeval;
94 setcase();
95  
96 #or
97  
98 $readval = setcase();
99  
100 query();#handles lines of text.
101  
102 my$opt_passwd = keypasswd();
103  
104 my $textline = query();
105  
106 The characters returned are set to the case setting that you set with `|'.
107  
108 announcestatus announces the status of the verbosity.
109  
110 The status of Term::GetKey is available by pressing `=' the equals key.
111  
112 setannounce toggles the setting verbosity. The calls to the keystrokes mentioned above are only present with a call to qtty() All the Term::GetKey commands except '\\' are disabled when Term::GetKey is in noecho mode.
113  
114 In noecaho mode, qtty() only has `\\' active. query() has case conversion disabled.
115  
116 =head1 Case and announcement values:
117  
118 setcase() casestatus() Kmstatus() setkeymode() return values only when announce mode is disabled with the default.
119  
120 Off 0
121 UPPERCASE and announcements active 1
122 lowercase 2
123  
124 Characters can be converted by Term::GetKey no matter what the capslock or case of the character sent by the terminal.
125  
126 =cut
127  
128  
129 #this module requires perl version 5.6.0 or better
130  
131 package Term::GetKey;
132 use Carp;
133 use warnings;
134 my $tmp = 0;
135 eval{
136 require Term::ReadKey};
137 $tmp++ if $@;
138 if ($tmp){
139 die "Term::ReadKey is required along with perl version 5.6.0 or better.\n";}
140  
141 else {
142 use Term::ReadKey}
143 my $version = "1.02";
144  
145 BEGIN
146 {
147 use Exporter ();
148 require AutoLoader;
149 require DynaLoader;
150  
151 our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS); #new in v5.6
152 $VERSION = 1.00;
153  
154 @ISA = (Exporter, AutoLoader, DynaLoader);
155  
156 @EXPORT=qw(
157 ReadKey ReadMode ReadLine GetTerminalSize SetTerminalSize
158 GetSpeed GetControlChars SetControlChars
159 keypasswd qtty query setcase casestatus setkeymode
160 announcestatus setannounce status Kmstatus
161 );
162  
163 @EXPORT_OK = qw($xy $case_val $tty_val $announce_val);
164 }#end BEGIN
165  
166 our @EXPORT_OK;
167 my $xy = '';
168 my $case_val = 0;
169 $DB::emacs = $DB::emacs; # To peacify -w
170 my $announce_val = 0;
171 my $announce_tmp = $announce_val;
172 my $case = "GetKey set to";
173 my $console;
174 my $tty_val = 3;
175  
176 # function declorations:
177  
178 sub status;
179 sub setcase;
180 sub setannounce;
181 sub keypasswd;
182 sub announcestatus;
183 sub casestatus;
184 sub Kmstatus;
185 sub setkeymode;
186 sub qtty;
187 sub query;
188  
189 END {close(TTY); } # module clean-up code here (global destructor)
190  
191 if (-e "/dev/tty") {
192 $console = "/dev/tty";
193 } elsif (-e "con" or $^O eq 'MSWin32') {
194 $console = "con";
195 } else {
196 $console = "sys\$command"; }
197  
198 if (($^O eq 'amigaos') || ($^O eq 'beos') || ($^O eq 'epoc')) {
199 $console = undef; }
200  
201 elsif ($^O eq 'os2') {
202  
203 if ($DB::emacs) {
204 $console = undef;
205 } else {
206 $console = "/dev/con"; }
207 }
208  
209 $consoleOUT = $console;
210 $console = "&STDIN" unless defined $console;
211  
212 if (!defined $consoleOUT) {
213 $consoleOUT = defined fileno(STDERR) ? "&STDERR" : "&STDOUT";
214 }
215  
216 open(TTY, "<$console");
217  
218 sub qtty
219 {#single character request using Term::ReadKey
220 ReadMode "restore" if $tty_val == 0;
221 ReadMode "normal" if $tty_val == 1;
222 ReadMode "noecho" if $tty_val == 2;
223 ReadMode "cbreak" if $tty_val == 3;
224 ReadMode "raw" if $tty_val == 4;
225 ReadMode "ultra-raw" if $tty_val == 5;
226 $xy = ReadKey 0, *TTY;
227 ReadMode "normal";#we needd the normal state to return the key
228 chomp $xy;
229 $announce_val = 1;
230 print "\n" if ($xy eq '\n' || $tty_val == 3);
231  
232 if ($xy eq '\\'){
233 $tty_val = setkeymode();
234 qtty() if $tty_val < 3;
235 qtty();
236  
237 }else {
238  
239 if ($tty_val != 2){
240 $xy=uc($xy) if $case_val == 1;
241 $xy=lc($xy) if $tty_val == 2; #do not translate in noecho
242 print"$xy\n" if ( $case_val);
243  
244 if ($xy eq '|'){
245 setcase();
246 $announce_val = $announce_tmp;
247 qtty() if $tty_val < 3;
248 qtty();
249 } elsif ($xy eq '+'){
250 my $qtty_call = caller();
251 print"$qtty_call\n";
252 qtty();
253 } elsif ($xy eq '~'){
254 setannounce();
255 $announce_val = $announce_tmp;
256 qtty() if $tty_val < 3;
257 qtty();
258 } elsif ($xy eq '='){
259 status();
260 $announce_val = $announce_tmp;
261 qtty() if $tty_val < 3;
262 qtty();
263 }
264 $announce_val = $announce_tmp;
265 croak("\nThank you for using $0: ") if $xy eq '`';
266 }#end else
267 }#end if
268  
269 $announce_val = $announce_tmp;
270 $xy;
271 }#end qtty
272  
273 sub Kmstatus
274 {#setting of Term::GetKey keymode
275  
276 if ($tty_val == 1){
277 print "$case normal:\n" if $announce_val;
278 } elsif ($tty_val == 2){
279 print "$case noecho:\n" if $announce_val;
280 } elsif ($tty_val == 3){
281 print "$case cbreak:\n" if $announce_val;
282 } elsif ($tty_val == 4){
283 print "$case raw:\n" if $announce_val;
284 } elsif ($tty_val == 5){
285 print "$case ultra-raw:\n" if $announce_val;
286 } else{
287  
288 print "$case restore:\n" if $announce_val;
289 }
290  
291 $tty_val;
292 }#end Kmstatus
293  
294 sub setkeymode
295 {#change setting of Term::ReadKey keymode
296  
297 if ($tty_val == 0){
298 $tty_val=1;
299 Kmstatus();
300 } elsif ($tty_val == 1){
301 $tty_val = 2;
302 Kmstatus();
303 } elsif ($tty_val == 2){
304 $tty_val = 3;
305 Kmstatus();
306 } elsif ($tty_val == 3){
307 $tty_val = 4;
308 Kmstatus();
309 } elsif ($tty_val == 4){
310 $tty_val = 5;
311 Kmstatus();
312 }else{
313 $tty_val = 0;
314 Kmstatus();
315 }
316  
317 $tty_val;
318 }#end set keymode
319  
320 sub setannounce
321 {#alter the setting verbosity announce is the default
322  
323 if ($announce_tmp == 1){
324 $announce_val = $announce_tmp = 0;
325 announcestatus();
326  
327 }else{
328  
329 $announce_val = $announce_tmp = 1;
330 announcestatus();
331 }
332  
333 return($announce_tmp,$announce_val);
334 }#end setannounce
335  
336 sub announcestatus
337 {#announce the setting of active announce on the default
338  
339 if ($announce_tmp == 0){
340 print "$ case announcement disabled: " if $announce_val == 0;
341  
342 }else{
343  
344 print "$case announcement active: " if $announce_val == 1;
345 }#end else
346  
347 $announce_tmp;
348 }#end announcestatus
349  
350 sub query
351 {#input line
352 chomp($xy=<STDIN>);
353 $announce_val = 1;
354  
355 if ($tty_val >= 2){
356 print "\n";
357 } else{
358  
359 if ($xy eq '|'){
360 setcase();
361 query();
362 }
363  
364 if (length($xy)){
365  
366 if ($xy =~ /\D/){
367 $xy = uc($xy) if $case_val == 1;
368 $xy = lc($xy) if $case_val == 2;
369 }#end if
370 $xy = ~ s/\\// if ($xy eq '\\|');
371 }#end if
372 }#end else
373 print "$xy\n" if $case_val;
374 $announce_val = $announce_tmp;
375 $xy;
376 }#end query
377  
378  
379 sub status
380 {#GetKey status
381 $announce_val = 1;
382 casestatus();
383 announcestatus();
384 Kmstatus();
385 print qq~Term::GetKey.pm $version. Commands from `$0'
386 when asked for a single character response when using qtty():
387 '`' quit the program '\~' toggle GetKey announcement
388 '|' toggle case conversion '\\' toggle the ReadKey settings
389 '=' read this announcement '+' list the caller function
390 ~;
391 $announce_val = $announce_tmp;
392 }#end status
393  
394 sub casestatus
395 {#announce the setting of active case off the default
396  
397 if ($case_val == 2){
398 print "$case lowercase: " if $announce_val;
399 } elsif ($case_val == 0){
400 print "$case case conversion disabled: " if $announce_val;
401 }else{
402 print "$case UPPERCASE: " if $announce_val;
403 }#end else
404  
405 $case_val;
406 }#end casestatus
407  
408 sub setcase
409 {#alter the setting of case conversion off is the default
410  
411 if ($case_val == 1){
412 $case_val = 2;
413 casestatus();
414 } elsif ($case_val == 2){
415 $case_val = 0;
416 casestatus();
417 }else{
418 $case_val = 1;
419 casestatus();
420 }
421  
422 $case_val;
423 }#end setcase
424  
425 sub keypasswd
426 {#get a password
427 my $xz;
428 my $qtty_call = caller();
429 my $xx = $tty_val;
430  
431 $tty_val = 2 if $qtty_call!~ /query/;
432  
433 for(;;){
434 $xy = qtty();
435 last if $xy eq "";
436 $xz .= "$xy";
437 }#end for
438 $tty_val = $xx;
439 print "\n";
440 $xz;
441 }#end keypasswd
442  
443  
444 1;
445  
446 __END__;