Matthäus Kiem


Term::Form - Read lines from STDIN.


Version 0.310


    use Term::Form;

    my $new = Term::Form->new( 'name' );
    my $line = $new->readline( 'Prompt: ', { default => 'abc' } );

    my $aoa = [
        [ 'name'           ],
        [ 'year'           ],
        [ 'color', 'green' ],
        [ 'city'           ]
    my $modified_list = $new->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.

fill_form reads a list of lines from STDIN.

This module is intended to cope with Unicode (multibyte character/grapheme cluster).


BackSpace or Strg-H: Delete the character behind the cursor.

Delete or Strg-D: Delete the character at point. Return nothing if the input puffer is empty.

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

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

Right-Arrow: Move forward a character.

Left-Arrow: Move back a character.

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

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

Only in fill_form:

Up-Arrow: Move up one row.

Down-Arrow: Move down one row.

Page-Up or Strg-B: Move back one page.

Page-Down or Strg-F: Move forward one page.



The new method returns a Term::Form object.

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


The method config overwrites the defaults for the current Term::Form object.

    $new->config( \%options );

The available options are: the options from readline and fill_form and

  • compat

    If compat is set to 1, the return value of readline is not decoded else the return value of readline is decoded. With fill_form the second elements (values) of the arrays are returned encoded if compat is set to 1, else they are returned decoded.

    Setting the environment variable READLINE_SIMPLE_COMPAT to a true value has the same effect as setting compat to 1 unless compat is defined. If compat is defined, READLINE_SIMPLE_COMPAT has no meaning.

    Allowed values: 0 or 1.

    default: no set

  • reinit_encoding

    To get the right encoding Term::Form uses Encode::Locale. Passing an encoding to reinit_encoding changes the encoding reported by Encode::Locale. See "reinit-encoding" in Encode::Locale for more details.

    Allowed values: an encoding which is recognized by the Encode module.

    default: not set


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

  • 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.

    - if set to 2, no output is shown apart from the prompt string.

    default: 0


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

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

  • 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 on a "readline". If the last "readline" row is reached, the cursor jumps to the first "readline" row if ENTER was pressed. If after an ENTER the cursor has jumped to the first "readline" row and auto_up is set to 1, ENTER doesn't move the cursor to the next row until the cursor is moved with another key. If auto_up is set to 0 or 1 the initially cursor position is on the first "readline" menu entry.

    With auto_up set to 2 ENTER goes to the top menu entry if the cursor is on a "readline". The initially cursor position is on the first menu entry.

    default: 0

  • ro

    Set a form-row to readonly.

    Expected value: a reference to an array with the indexes of the rows which should be readonly.

    default: empty array

  • confirm

    Set the name of the "confirm" menu entry.

    default: <<

  • back

    Set the name of the "back" menu entry.

    The "back" menu entry is not available if back is not defined or set to an empty string.

    default: undefined

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.


Perl version

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.

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.


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

    perldoc Term::Form


Matthäus Kiem <>


Thanks to the and the people form stackoverflow for the help.


Copyright 2014-2016 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.