Term::Form - Read lines from STDIN.
Version 0.534
my $aoa = [ [ 'name' ], [ 'year' ], [ 'color', 'green' ], [ 'city' ] ]; # Object-oriented interface: use Term::Form; my $new = Term::Form->new(); my $line = $new->readline( 'Prompt: ', { default => 'abc' } ); my $modified_list = $new->fill_form( $aoa ); # Functional interface: use Term::Form qw( read_line fill_form ); my $line = read_line( 'Prompt: ', { default => 'abc' } ); my $modified_list = fill_form( $aoa );
readline reads a line from STDIN. As soon as Return is pressed readline returns the read string without the newline character - so no chomp is required.
readline
Return
chomp
fill_form reads a list of lines from STDIN.
fill_form
This module is intended to cope with Unicode (multibyte character/grapheme cluster).
The output is removed after leaving the method, so the user can decide what remains on the screen.
BackSpace or Ctrl-H: Delete the character behind the cursor.
BackSpace
Ctrl-H
Delete or Ctrl-D: Delete the character at point.
Delete
Ctrl-D
Ctrl-U: Delete the text backward from the cursor to the beginning of the line.
Ctrl-U
Ctrl-K: Delete the text from the cursor to the end of the line.
Ctrl-K
Right-Arrow: Move forward a character.
Right-Arrow
Left-Arrow: Move back a character.
Left-Arrow
Home or Ctrl-A: Move to the start of the line.
Home
Ctrl-A
End or Ctrl-E: Move to the end of the line.
End
Ctrl-E
Up-Arrow: in fill_form move up one row, in readline move back 10 characters.
Up-Arrow
Down-Arrow: in fill_form move down one row, in readline move forward 10 characters.
Down-Arrow
Ctrl-X: If the input puffer is not empty, the input puffer is cleared, else Ctrl-X returns nothing (undef).
Ctrl-X
Only in fill_form:
Page-Up or Ctrl-B: Move back one page.
Page-Up
Ctrl-B
Page-Down or Ctrl-F: Move forward one page.
Page-Down
Ctrl-F
The new method returns a Term::Form object.
new
Term::Form
my $new = Term::Form->new();
To set the different options it can be passed a reference to a hash as an optional argument.
readline reads a line from STDIN.
$line = $new->readline( $prompt, \%options );
The fist argument is the prompt string.
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 keys/options are
clear_screen
If enabled, the screen is cleared before the output.
0 - clears from the current position to the end of screen
1 - clears the entire screen
2 - if show_context is disabled, clears only the current (readline) row. If show_context is enabled behaves like clear_screen where set to 0.
default: 0
0
color
Enables the support for color and text formatting escape sequences for the prompt string and the info text.
0 - off
1 - on
info
Expects as is value a string. If set, the string is printed on top of the output of readline.
default
Set a initial value of input.
no_echo
- if set to 0, the input is echoed on the screen.
- if set to 1, "*" are displayed instead of the characters.
1
*
- if set to 2, no output is shown apart from the prompt string.
2
show_context
Display the input that does not fit into the "readline" before or after the "readline".
0 - disable show_context
1 - enable show_context
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.
Win32::Console::ANSI
Term::Choose
Setting this option to 1 enables the codepage mapping offered by Win32::Console::ANSI.
0 - disable automatic codepage mapping (default)
1 - keep automatic codepage mapping
hide_cursor
0 - disabled
1 - enabled
default: 1
$new_list = $new->fill_form( $aoa, { prompt => 'Required:' } );
The first argument is a reference to an array of arrays. The arrays have 1 or 2 elements: the first element is the key and the optional second element is the value. The key is used as the prompt string for the "readline", the value is used as the default value for the "readline" (initial value of input).
The optional second argument is a hash-reference. The keys/options are
Enables the support for color and text formatting escape sequences for the form-keys, the "back"-string, the "confirm"-string, the info text and the prompt text.
Expects as is value a string. If set, the string is printed on top of the output of fill_form.
prompt
If prompt is set, a main prompt string is shown on top of the output.
default: undefined
auto_up
With auto_up set to 0 or 1 pressing ENTER moves the cursor to the next line (if the cursor is not on the "back" or "confirm" row). If the last row is reached, the cursor jumps to the first data row if ENTER is pressed. While with auto_up set to 0 the cursor loops through the rows until a key other than ENTER is pressed with auto_up set to 1 after one loop an ENTER moves the cursor to the top menu entry ("back") if no other key than ENTER was pressed.
ENTER
With auto_up set to 2 an ENTER moves the cursor to the top menu entry (except the cursor is on the "confirm" row).
If auto_up is set to 0 or 1 the initially cursor position is on the first data row while when set to 2 the initially cursor position is on the first menu entry ("back").
default: disabled
read_only
Set a form-row to read only.
Expected value: a reference to an array with the indexes of the rows which should be read only.
default: empty array
confirm
Set the name of the "confirm" menu entry.
default: Confirm
Confirm
back
Set the name of the "back" menu entry.
The "back" menu entry can be disabled by setting back to an empty string.
default: Back
Back
To close the form and get the modified list (reference to an array or arrays) as the return value select the "confirm" menu entry. If the "back" menu entry is chosen to close the form, fill_form returns nothing.
Requires Perl version 5.8.3 or greater.
It is required a terminal which uses a monospaced font.
Unless the OS is MSWin32 the terminal has to understand ANSI escape sequences.
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.
You can find documentation for this module with the perldoc command.
perldoc Term::Form
Matthäus Kiem <cuer2s@gmail.com>
Thanks to the Perl-Community.de and the people form stackoverflow for the help.
Copyright 2014-2021 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.
To install Term::Form, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Term::Form
CPAN shell
perl -MCPAN -e shell install Term::Form
For more information on module installation, please visit the detailed CPAN module installation guide.