Term::ReadKey 2.36 - Change terminal modes, and perform non-blocking reads.

 Copyright (C) 1994-1999 Kenneth Albanowski.

               2001-2016 Jonathan Stowe and others

This package is dual licensed.  You can either choose to license it under

the original terms which were:

 Unlimited distribution and/or modification is allowed as long as this

 copyright notice remains intact.

Or the standard Perl terms:

  This module is free software; you can redistribute it and/or modify it

  under the terms of the Artistic License. For details, see the full

  text of the license in the file "Artistic" that should have been provided

  with the version of perl you are using.

  This program is distributed in the hope that it will be useful, but

  without any warranty; without even the implied warranty of merchantability

  or fitness for a particular purpose.

This module, ReadKey, provides ioctl control for terminals and Win32

consoles so the input modes can be changed (thus allowing reads of a single

character at a time), and also provides non-blocking reads of stdin, as well

as several other terminal related features, including retrieval/modification

of the screen size, and retrieval/modification of the control characters.

Installation requires MakeMaker 3.5 or higher (MakeMaker 3.7 is included

with perl 5.001, so now is a good time to upgrade if you haven't already.)

To install, unpack somewhere, type "perl Makefile.PL", and then "make test".

If the compilation and the tests are successful, then change to root and run

"make install".

As of 2.17 the interactive test has been removed as the default for the

convenience of automated installers, CPAN-Testers and so on.  The non

interactive tests whilst confirming that the module has built correctly

and has a good chance of working correctly cannot determine whether the

effect as observed on the screen is correct so you might want to run:

   perl -Mblib example/test.pl interactive

before you run 'make install'.

Also from 2.17 this module has to provide its own support for compilers

that can't take function prototypes as with Perl 5.8.0 this last vestige

of support for non-ANSI compilers will disappear.  The requirement for

an ANSI C compiler has been present since Perl 5.005 so it is likely that

at some point in the future this module will follow that requirement too.

If you have any difficulties with older Perl's please contact the maintainer.

The module has support for Win32 since version 2.10. Version 2.17 has been

tested with ActivePerl build 623 and Visual Studio 6 and found to work

as expected, but do not be surprised if it fails with another compiler

or distribution.  There are  some limitations, with the ReadLine call

being unavailable, and ReadKey possibly generating bad results if you

are reading from multiple consoles, and key repeat is used.  For Win32

users without a C compiler there is a precompiled version of this module

available as a package for ActivePerl, it is probably a few versions

behind the latest release but has been reported to work well.

VERY IMPORTANT: In 2.00, the ReadKey/ReadLine arguments changed. Now, if

you want a call that is non-blocking and returns immediately if no

character is waiting, please call it with -1, instead of 1. Positive

arguments now indicate a timeout, so 1 would wait a second before timing

out.

As older versions will accept -1, it is reccomended to change all code

that uses ReadMode.

The terminal mode function is controlled by the "ReadMode" function, which

takes a single numeric argument, and an optional filehandle. This argument

should be one of the following:

	0: (Reset) Restore original settings.

	1: (Cooked) Change to what is commonly the default mode, echo on,

           buffered, signals enabled, Xon/Xoff possibly enabled, and 8-bit mode

	   possibly disabled.

	2: (Cooked-Invisible) Same as 1, just with echo off. Nice for reading

           passwords.

	3: (CBreak) Echo off, unbuffered, signals enabled, Xon/Xoff possibly

           enabled, and 8-bit mode possibly enabled.

	4: (Raw) Echo off, unbuffered, signals disabled, Xon/Xoff disabled,

           and 8-bit mode possibly disabled.

	5: (Really-Raw) Echo off, unbuffered, signals disabled, Xon/Xoff

           disabled, 8-bit mode enabled if parity permits, and CR to CR/LF

           translation turned off.

If you just need to read a key at a time, then modes 3 or 4 are probably

sufficient. Mode 4 is a tad more flexible, but needs a bit more work to

control. If you use ReadMode 3, then you should install a SIGINT or END

handler to reset the terminal (via ReadMode 0) if the user aborts the

program via ^C. (For any mode, an END handler consisting of "ReadMode 0" is

actually a good idea.)

Non-blocking support is provided via the ReadKey and ReadLine functions. If

they are passed no argument, or an argument of zero, they will act like a

normal getc(STDIN) or scalar(<STDIN>). If they are passed a negative

argument, then they will immediatly return undef if no input is present. If

passed a positive argument, then they will wait until that time in seconds

has passed before returning undef. In most situations, you will probably

want to use "ReadKey -1".

Note that a non-blocking ReadLine probably won't do what you expect,

although it is perfectly predictable, and that the ReadMode will have to be

1 or 0 for it to make sense at all.

A routine is also provided to get the current terminal size,

"GetTerminalSize". This will either return a four value array containing the

width and height of the screen in characters and then in pixels, or nothing

( if the OS can't return that info). SetTerminalSize allows the stored

settings to be modified. Note that this does _not_ change the physical size

of the screen, it will only change the size reported by GetTerminalSize, and

other programs that check the terminal size in the same manner.

GetControlChars returns a hash containing all of the valid control

characters, such as ("INTERRUPT" => "\x3", etc.). SetControlChars takes an

array (or a hash) as a parameter that should consist of similar name/value

pairs and will modify the control character settings.

Note that it is entirely possible that there are portability problems with

the routines in ReadKey.xs. If you find any problems, including compilation

failures, or control characters not supported by Set/GetControlChars,

_please_ tell me about them, by mailing the maintainer at jns@gellyfish.co.uk,

 or lastly contacting perl5-porters@perl.org. Any problems

will get fixed if at all possible, but that's not going to happen if I don't

know about them.

The code is available at https://github.com/jonathanstowe/TermReadKey so

as ever patches are kindly welcomed, especially for platforms such as

Windows that I am unable to test on.

Oh, you may also be interested in the Configure.pm module. It provides tools

to make porting stuff easier -- calling the compiler, finding headers, etc.

It contains documentation inside it, and you are welcome to use it in your

own modules. If you make use of it, I'd be grateful for a message sent to

the above address.