NAME

Term::Form::ReadLine - Read a line from STDIN.

VERSION

Version 0.562

SYNOPSIS

    # Object-oriented interface:
    use Term::Form::ReadLine;
    my $new = Term::Form::ReadLine->new();
    my $line = $new->readline( 'Prompt: ', { default => 'abc' } );
    # Functional interface:
    use Term::Form::ReadLine qw( read_line );
    $line = read_line( 'Prompt: ', { default => 'abc' } );

DESCRIPTION

"readline" reads a line from STDIN. As soon as "Return" is pressed, "readline" returns the read string without a trailing newline character.

The output is removed after leaving the method, so the user can decide what remains on the screen.

Keys

"BackSpace" or "Ctrl-H": Delete the character behind the cursor.

"Delete" or "Ctrl-D": Delete the character at point.

"Ctrl-U": Delete the text backward from the cursor to the beginning of the line.

"Ctrl-K": Delete the text from the cursor to the end of the line.

"Right-Arrow" or "Ctrl-F": Move forward a character.

"Left-Arrow" or "Ctrl-B": Move back a character.

"Home" or "Ctrl-A": Move to the start of the line.

"End" or "Ctrl-E": Move to the end of the line.

"Page-Up" or "Ctrl-P": Move back 10 characters.

"Page-Down" or "Ctrl-N": Move forward 10 characters.

"Ctrl-X": If the input puffer is not empty, the input puffer is cleared, else "Ctrl-X" returns nothing (undef).

"Up-Arrow" or "Ctrl-S": History up.

"Down-Arrow" or "Ctrl-T": History down.

METHODS

new

The "new" method returns a "Term::Form::ReadLine" object.

    my $new = Term::Form::ReadLine->new();

To set the different options it can be passed a reference to a hash as an optional argument.

readline

"readline" reads a line from STDIN.

    $line = $new->readline( $prompt, \%options );

The fist argument is the prompt string. A prompt is truncated if the length of the prompt exceeds one third of the terminal width. A truncated prompt is marked with a trailing "~".

The optional second argument is the default string (see option default) if it is not a reference. If the second argument is a hash-reference, the hash is used to set the different options. The hash-keys/options are:

clear_screen

0 - clears from the current position to the end of screen

1 - clears the entire screen

2 - clears only the rows used by readline

default: 0

codepage_mapping

This option has only meaning if the operating system is MSWin32.

If the OS is MSWin32, Win32::Console::ANSI is used. By default "Win32::Console::ANSI" converts the characters from Windows code page to DOS code page (the so-called ANSI to OEM conversion). This conversation is disabled by default in "Term::Choose", but one can enable it by setting this option.

0 - disables the automatic codepage mapping (default)

1 - keeps the automatic codepage mapping

default: 0

color

Enables the support for color and text formatting escape sequences for the prompt string and the info text.

0 - off

1 - on

default: 0

default

Set a initial value of input.

hide_cursor

0 - disabled

1 - enabled

default: 1

history

This option allows one to pass a "readline" history as a reference to an array.

If the entered string matches the beginning of one or more history entries, only these matched history entries are offered.

See "Keys" for how to move through the history.

default: empty

info

Expects as is value a string. If set, the string is printed on top of the output of "readline".

no_echo

0 - the input is echoed on the screen.

1 - ""*"" are displayed instead of the characters.

2 - no output is shown apart from the prompt string.

default: 0

show_context

Display the input that does not fit into the "readline" before or after the "readline".

0 - disabled

1 - enabled

default: 0

REQUIREMENTS

Perl version

Requires Perl version 5.10.1 or greater.

Terminal

It is required a terminal which uses a monospaced font.

Unless the OS is MSWin32 the terminal has to understand ANSI escape sequences.

Encoding layer

It is required to use appropriate I/O encoding layers. If the encoding layer for STDIN doesn't match the terminal's character set, "readline" will break if a non ascii character is entered.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Term::Form::ReadLine

AUTHOR

Matthäus Kiem <cuer2s@gmail.com>

CREDITS

Thanks to the Perl-Community.de <http://www.perl-community.de> and the people form stackoverflow <http://stackoverflow.com> for the help.

LICENSE AND COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For details, see the full text of the licenses in the file LICENSE.