NAME

Term::TransKeys - Methods to read input while responding to special keys

DESCRIPTION

Provides methods for reading text input while responding to special keys.

 * Bind functionality to any key
 * Read STDIN for input
 * Input is preserved if a bound key is pressed during input.
 * Bound key functionality can manipulate the input buffer in real time
 * Bound key functionality runs when key is pressed, does not wait for input to be completely entered.

SYNOPSIS

use Term::TransKeys;

my $listener = Term::TransKeys->new(
    actions => {
        '<F1>' => sub {
            ... Do something when the F1 key is pressed
        }
    }
);

# Term::Screen is not a requirement, just used in example.
use Term::Screen;
my $scr = new Term::Screen;

$scr->clrscr;
while ( 1 ) {
    # Place to hold the line of input
    my $line;

    # print the buffer until we have a complete line of input, non-blocking IO, loop at 0.01 interval.
    while ( not defined ($line = $listener->ActionRead( mode => 0.01 ))) {

        # Lets provide a prompt
        my $prompt = "input: ";

        # Print our current position (from right) in the buffer.
        $scr->at( 15, 0 )->clreol->puts( $listener->BufferPosition );
        # Show the prompt as well as the text entered so far.
        $scr->at(10,0)->clreol->puts( "input: " . $listener->BufferString );
        # Move the cursor to the currect position in the text
        $scr->at( 10, $listener->BufferPosition + length( $prompt ));
    }

    # When we have a new completed line:
    #  * Delete the line at the top of the screen, moving other lines up.
    #  * Output the new line at row 9.
    chomp( $line );
    $scr->at(0,0)->dl;
    $scr->at(9,0)->clreol->puts( $line );
    exit(0) if $line eq 'exit';
}

Recognised Keys:

  Key           Default actions when using ActionRead(). These may be
                overriden in new, or in the method call.
-------------------------------------------------------------------------
<ESCAPE>        - Clear the buffer
<ENTER>         - Insert a newline into the buffer unless <ENTER> is the end character
<BACKSPACE>     - delete the character at the cursor

-------- Function Keys
<F1>
<F2>
<F3>
<F4>
<F5>
<F6>
<F7>
<F8>
<F9>
<F10>
<F11>
<F12>

-------- Arrow Keys
<UP>            - Buffer history, previous line of input
<DOWN>          - Buffer history, next line of input
<RIGHT>         - Move cursor position right
<LEFT>          - Move the cursor position left

-------- I do not know what to call this group
<INSERT>
<HOME>          - Move cursor to start of buffer
<DELETE>        - Delete the character after the cursor position
<END>           - Move curstor to end of buffer
<PAGE UP>
<PAGE DOWN>
    <CONTEXT>       # Note: This is the menu key usually next to the windows key.

-------- Control Keys
<CONTROL+[A-Z]> # Note: control+j and control+m both map to <ENTER>
    <CONTROL+C> - exit(0)
    <CONTROL+D> - Finished entering input
    <CONTROL+Z> - Same as at shell, stop the process.

-------- Regular keys
|Any Text key|  - adds that key to the current position in the buffer

TransKey() will act like readkey, except when one of the above keys is
pressed, in these cases it will return the string listed above under 'key'

Constructors and Accessor Methods

new()

Create a new TransKey object. Each object maintains it's own buffer, and
has its own bound functionality.

my $listener = Term::TransKeys->new(
    history_length => 20, #Default is 20, how much history to keep.
    history => [
        'A Line',
        "Another line",
        "so on...",
    ],
    # Actions are only used by ActionRead not TransKey.
    actions => {
        '<F1>' => sub { #Do something when F1 is pressed },
        'a' => sub { #do something when 'a' is pressed, as well as adding it to the buffer },
        '<CONTROL+Z>' => sub { #override control+z behavior },
    }
);

Actions()

Get the hash of key => action bindings.

you can override an action like so:
$listener->Actions->{ '<ESCAPE>' } = sub { ... };

Buffer Methods

BufferPosition()

Get the current cursor position in the buffer. (Where the next character
will be inserted). 0 means before the first character, 1 means before the
second character.

BufferEmpty()

Returns true if the buffer is empty.

BufferString()

Returns the contents of the buffer as a concatenated string.

Input Methods

TransKey()

Get a single input key.

Acts like ReadKey, except that when a special key is pressed it will return '<KEY>'

Takes one optional parameter, mode. -1 is non-blocking, 0 is blocking,
$mode > 0 is timed. Default is 0.

return undef if no input is recieved in non-blocking mode or before timeout.

ActionRead()

Obtain a line of input. Line is used liberally, if 'end' parameter is
specifed the 'line' may contain multiple lines.

Parameters:

$listener->ActionRead(
    actions => {
        <F1> => sub { ... }, #Action to run when F1 is pressed.
        ...
        # Actions overriden here remain overriden only for this method
        # call. Next method call they will be restored.
        # In order to override permanently override in the constructor, or
        # using the Actions() accessor.
    },
    mode => 0, #Default is 0, -1 is non-blocking, 0 is blocking, >0 is timed.
    end => '<ENTER>', #Return the line when this key is pressed.
        # You can use any printable character, or recognised ('<KEY>') key
        # here. Default is '<ENTER>'
        # Use something like '__TERM__' to force it to only return once
        # control+d has been pressed. *** NOTE: Do not override control+d if
        # you specify something other than a key here!. ***
);

Action Methods

I consider these methods because the first parameter should be the listener,
however they can just as easily be considered functions as they are called w/
the listener as a parameter and not as $listener->Action() in most cases.

ActionBS()

<BACKSPACE> default action.

ActionEsc()

<ESCAPE> default action.

ActionCC()

<CONTROL+C> default action.

ActionCD()

<CONTROL+D> default action.

ActionCZ()

<CONTROL+Z> default action.

ActionUp()

<UP> default action.

ActionDown()

<DOWN> default action.

ActionLeft()

<LEFT> default action.

ActionRight()

<RIGHT> default action.

ActionHome()

<HOME> default action.

ActionEnd()

<END> default action.

ActionDel()

<DELETE> default action.

ActionEnter()

<ENTER> default action.

Creating your own action

sub MyAction {
    # Get the Term::TransKeys object
    my $listener = shift;
    # Get a reference to the current array of keys, and the character used
    # to return the lien of input.
    my ( $keys, $endchar, $key ) = @_;

    # Add a character to the end of the key array
    push( @$keys, 'a' );
    # Change the key recieved from what it was to the end character forcing
    # the input to return
    $key is a scalar reference.
    $$key = $endchar;
}

Note

You can modify the @$keys array in any way you want, but remember it is a reference:
$keys = [ qw/ a b c /]; # Will do nothing useful, in fact we loose the
                        # ability to modify the input buffer.
@$keys = ( qw/ a b c /); # use this instead, modify the correct array.

Now to use the action

my $line = $listener->ActionRead(
    actions => {
        '<CONTROL+D>' => \&MyAction,
    },
    end => '__TERM__', #Input only ends when control+d is pressed.
);

History Methods

GetHistory()

Returns an arrayref to the history array.
Modifying the arrayref will bypass history_length. However the length will
be enforced again as sson as AddHistory() is called.

AddHistory()

Add item(s) to history. Use this instead of modifying the array from
GetHistory, this method enforces history_length.

HistoryLength()

Get/Set the length of the history.

AUTHOR

Chad Granum <exodist7@gmail.com>

COPYRIGHT

Copyright 2008 Chad Granum

You should have received a copy of the GNU General Public License along with this. If not, see <http://www.gnu.org/licenses/>.