The Perl Toolchain Summit 2025 Needs You: You can help 🙏 Learn more

 / 
Term-Form-0.561
River stage one • 2 direct dependents • 2 total dependents
/ Term::Form::ReadLine

NAME

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

VERSION

Version 0.561

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 and the people form stackoverflow for the help.

LICENSE AND COPYRIGHT

Copyright 2022-2025 Matthäus Kiem.

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.