1 Term::ReadKey 2.36 - Change terminal modes, and perform non-blocking reads. 2 3 Copyright (C) 1994-1999 Kenneth Albanowski. 4 2001-2016 Jonathan Stowe and others 5 6This package is dual licensed. You can either choose to license it under 7the original terms which were: 8 9 Unlimited distribution and/or modification is allowed as long as this 10 copyright notice remains intact. 11 12Or the standard Perl terms: 13 14 This module is free software; you can redistribute it and/or modify it 15 under the terms of the Artistic License. For details, see the full 16 text of the license in the file "Artistic" that should have been provided 17 with the version of perl you are using. 18 19 This program is distributed in the hope that it will be useful, but 20 without any warranty; without even the implied warranty of merchantability 21 or fitness for a particular purpose. 22 23 24 25This module, ReadKey, provides ioctl control for terminals and Win32 26consoles so the input modes can be changed (thus allowing reads of a single 27character at a time), and also provides non-blocking reads of stdin, as well 28as several other terminal related features, including retrieval/modification 29of the screen size, and retrieval/modification of the control characters. 30Installation requires MakeMaker 3.5 or higher (MakeMaker 3.7 is included 31with perl 5.001, so now is a good time to upgrade if you haven't already.) 32 33To install, unpack somewhere, type "perl Makefile.PL", and then "make test". 34If the compilation and the tests are successful, then change to root and run 35"make install". 36 37As of 2.17 the interactive test has been removed as the default for the 38convenience of automated installers, CPAN-Testers and so on. The non 39interactive tests whilst confirming that the module has built correctly 40and has a good chance of working correctly cannot determine whether the 41effect as observed on the screen is correct so you might want to run: 42 43 perl -Mblib example/test.pl interactive 44 45before you run 'make install'. 46 47Also from 2.17 this module has to provide its own support for compilers 48that can't take function prototypes as with Perl 5.8.0 this last vestige 49of support for non-ANSI compilers will disappear. The requirement for 50an ANSI C compiler has been present since Perl 5.005 so it is likely that 51at some point in the future this module will follow that requirement too. 52If you have any difficulties with older Perl's please contact the maintainer. 53 54The module has support for Win32 since version 2.10. Version 2.17 has been 55tested with ActivePerl build 623 and Visual Studio 6 and found to work 56as expected, but do not be surprised if it fails with another compiler 57or distribution. There are some limitations, with the ReadLine call 58being unavailable, and ReadKey possibly generating bad results if you 59are reading from multiple consoles, and key repeat is used. For Win32 60users without a C compiler there is a precompiled version of this module 61available as a package for ActivePerl, it is probably a few versions 62behind the latest release but has been reported to work well. 63 64VERY IMPORTANT: In 2.00, the ReadKey/ReadLine arguments changed. Now, if 65you want a call that is non-blocking and returns immediately if no 66character is waiting, please call it with -1, instead of 1. Positive 67arguments now indicate a timeout, so 1 would wait a second before timing 68out. 69 70As older versions will accept -1, it is reccomended to change all code 71that uses ReadMode. 72 73 74The terminal mode function is controlled by the "ReadMode" function, which 75takes a single numeric argument, and an optional filehandle. This argument 76should be one of the following: 77 78 0: (Reset) Restore original settings. 79 80 1: (Cooked) Change to what is commonly the default mode, echo on, 81 buffered, signals enabled, Xon/Xoff possibly enabled, and 8-bit mode 82 possibly disabled. 83 84 2: (Cooked-Invisible) Same as 1, just with echo off. Nice for reading 85 passwords. 86 87 3: (CBreak) Echo off, unbuffered, signals enabled, Xon/Xoff possibly 88 enabled, and 8-bit mode possibly enabled. 89 90 4: (Raw) Echo off, unbuffered, signals disabled, Xon/Xoff disabled, 91 and 8-bit mode possibly disabled. 92 93 5: (Really-Raw) Echo off, unbuffered, signals disabled, Xon/Xoff 94 disabled, 8-bit mode enabled if parity permits, and CR to CR/LF 95 translation turned off. 96 97If you just need to read a key at a time, then modes 3 or 4 are probably 98sufficient. Mode 4 is a tad more flexible, but needs a bit more work to 99control. If you use ReadMode 3, then you should install a SIGINT or END 100handler to reset the terminal (via ReadMode 0) if the user aborts the 101program via ^C. (For any mode, an END handler consisting of "ReadMode 0" is 102actually a good idea.) 103 104Non-blocking support is provided via the ReadKey and ReadLine functions. If 105they are passed no argument, or an argument of zero, they will act like a 106normal getc(STDIN) or scalar(<STDIN>). If they are passed a negative 107argument, then they will immediatly return undef if no input is present. If 108passed a positive argument, then they will wait until that time in seconds 109has passed before returning undef. In most situations, you will probably 110want to use "ReadKey -1". 111 112Note that a non-blocking ReadLine probably won't do what you expect, 113although it is perfectly predictable, and that the ReadMode will have to be 1141 or 0 for it to make sense at all. 115 116A routine is also provided to get the current terminal size, 117"GetTerminalSize". This will either return a four value array containing the 118width and height of the screen in characters and then in pixels, or nothing 119( if the OS can't return that info). SetTerminalSize allows the stored 120settings to be modified. Note that this does _not_ change the physical size 121of the screen, it will only change the size reported by GetTerminalSize, and 122other programs that check the terminal size in the same manner. 123 124GetControlChars returns a hash containing all of the valid control 125characters, such as ("INTERRUPT" => "\x3", etc.). SetControlChars takes an 126array (or a hash) as a parameter that should consist of similar name/value 127pairs and will modify the control character settings. 128 129Note that it is entirely possible that there are portability problems with 130the routines in ReadKey.xs. If you find any problems, including compilation 131failures, or control characters not supported by Set/GetControlChars, 132_please_ tell me about them, by mailing the maintainer at jns@gellyfish.co.uk, 133 or lastly contacting perl5-porters@perl.org. Any problems 134will get fixed if at all possible, but that's not going to happen if I don't 135know about them. 136 137The code is available at https://github.com/jonathanstowe/TermReadKey so 138as ever patches are kindly welcomed, especially for platforms such as 139Windows that I am unable to test on. 140 141Oh, you may also be interested in the Configure.pm module. It provides tools 142to make porting stuff easier -- calling the compiler, finding headers, etc. 143It contains documentation inside it, and you are welcome to use it in your 144own modules. If you make use of it, I'd be grateful for a message sent to 145the above address. 146