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

NAME

Term::Form - Read lines from STDIN.

VERSION

Version 0.558

SYNOPSIS

my $aoa = [
    [ 'name'           ],
    [ 'year'           ],
    [ 'color', 'green' ],
    [ 'city'           ]
];

# Object-oriented interface:

use Term::Form;

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

my $modified_list = $new->fill_form( $aoa );

# Functional interface:

use Term::Form qw( fill_form );

$modified_list = fill_form( $aoa );

DESCRIPTION

fill_form reads a list of lines from STDIN.

To close the form and get the modified list (reference to an array of arrays) as a return value, select the confirm menu item. If the back menu item is chosen instead to close the form, fill_form returns nothing.

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

readline has been moved to Term::Form::ReadLine.

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.

Up-Arrow or Ctrl-S: Move up one row.

Down-Arrow or Ctrl-T: Move down one row.

Ctrl-X: Delete the text of the line.

Page-Up or Ctrl-P: Move to the previous page.

Page-Down or Ctrl-N: Move to the next page.

METHODS

new

The new method returns a Term::Form object.

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

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

fill_form

fill_form reads a list of lines from STDIN.

$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).

Strings that have been shortened to fit into the terminal width are marked with a trailing ~. This does not affect the returned data.

When $aoa is return values of rows where nothing has been entered are set to the empty string.

The optional second argument is a hash-reference. The hash-keys/options are:

auto_up

0 - if the cursor is on a data row (that means not on the "back" or "confirm" menu entry), pressing ENTER moves the cursor to the next row. If ENTER is pressed when the cursor is on the last data row, the cursor jumps to the first data row. The initially cursor position is on the first data row.

1 - if the cursor is on a data row, pressing ENTER moves the cursor to the next row unless the cursor is on the last data row. Then pressing ENTER moves the cursor to the "back" menu entry (the menu entry on the top of the menu). The initially cursor position is on the "back" menu entry.

2 - if the cursor is on a data row, pressing ENTER moves the cursor to the "back" menu entry. The initially cursor position is on the "back" menu entry.

default: 1

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

clear_screen

If enabled, the screen is cleared before the output.

0 - off

1 - on

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.

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

default: 0

color

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.

0 - off

1 - on

default: 0

confirm

Set the name of the "confirm" menu entry.

default: Confirm

hide_cursor

0 - disabled

1 - enabled

default: 1

info

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

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

skip_items

When navigating the form, lines whose key string matches the regex pattern passed with this option will be skipped. Passed values are ignored. It's up to the user to remove these elements from the returned array.

The expected value is a regex quoted with the qr operator.

REQUIREMENTS

Perl version

Requires Perl version 5.10.0 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, fill_from will break if a non ascii character is entered.

SUPPORT

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

perldoc Term::Form

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 2014-2024 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.