Provided by: libpoe-perl_1.3580-1_all bug

NAME

       POE::Wheel::ReadLine - non-blocking Term::ReadLine for POE

SYNOPSIS

         #!perl

         use warnings;
         use strict;

         use POE qw(Wheel::ReadLine);

         POE::Session->create(
           inline_states=> {
             _start => \&setup_console,
             got_user_input => \&handle_user_input,
           }
         );

         POE::Kernel->run();
         exit;

         sub handle_user_input {
           my ($input, $exception) = @_[ARG0, ARG1];
           my $console = $_[HEAP]{console};

           unless (defined $input) {
             $console->put("$exception caught.  B'bye!");
             $_[KERNEL]->signal($_[KERNEL], "UIDESTROY");
             $console->write_history("./test_history");
             return;
           }

           $console->put("  You entered: $input");
           $console->addhistory($input);
           $console->get("Go: ");
         }

         sub setup_console {
           $_[HEAP]{console} = POE::Wheel::ReadLine->new(
             InputEvent => 'got_user_input'
           );
           $_[HEAP]{console}->read_history("./test_history");
           $_[HEAP]{console}->clear();
           $_[HEAP]{console}->put(
             "Enter some text.",
             "Ctrl+C or Ctrl+D exits."
           );
           $_[HEAP]{console}->get("Go: ");
         }

DESCRIPTION

       POE::Wheel::ReadLine is a non-blocking form of Term::ReadLine that's compatible with POE.
       It uses Term::Cap to interact with the terminal display and Term::ReadKey to interact with
       the keyboard.

       POE::Wheel::ReadLine handles almost all common input editing keys.  It provides an input
       history list.  It has both vi and emacs modes.  It supports incremental input search.
       It's fully customizable, and it's compatible with standard readline(3) implementations
       such as Term::ReadLine::Gnu.

       POE::Wheel::ReadLine is configured by placing commands in an "inputrc" initialization
       file.  The file's name is taken from the "INPUTRC" environment variable, or ~/.inputrc by
       default.  POE::Wheel::ReadLine will read the inputrc file and configure itself according
       to the commands and variables therein.  See readline(3) for details about inputrc files.

       The default editing mode will be emacs-style, although this can be configured by setting
       the 'editing-mode' variable within an inputrc file.  If all else fails,
       POE::Wheel::ReadLine will determine the user's favorite editor by examining the EDITOR
       environment variable.

PUBLIC METHODS

   Constructor
       Most of POE::Wheel::ReadLine's interaction is through its constructor, new().

       new

       new() creates and returns a new POE::Wheel::ReadLine object.  Be sure to instantiate only
       one, as multiple console readers would conflict.

       InputEvent

       "InputEvent" names the event that will indicate a new line of console input.  See "PUBLIC
       EVENTS" for more details.

       PutMode

       "PutMode" controls how output is displayed when put() is called during user input.

       When set to "immediate", put() pre-empts the user immediately.  The input prompt and
       user's input to date are redisplayed after put() is done.

       The "after" "PutMode" tells put() to wait until after the user enters or cancels her
       input.

       Finally, "idle" will allow put() to pre-empt user input if the user stops typing for
       "IdleTime" seconds.  This mode behaves like "after" if the user can't stop typing long
       enough.  This is POE::Wheel::ReadLine's default mode.

       IdleTime

       "IdleTime" tells POE::Wheel::ReadLine how long the keyboard must be idle before "put()"
       becomes immediate or buffered text is flushed to the display.  It is only meaningful when
       "PutMode" is "idle".  "IdleTime" defaults to 2 seconds.

       AppName

       "AppName" registers an application name which is used to retrieve application-specific key
       bindings from the inputrc file.  The default "AppName" is "poe-readline".

         # If using POE::Wheel::ReadLine, set
         # the key mapping to emacs mode and
         # trigger debugging output on a certain
         # key sequence.
         $if poe-readline
         set keymap emacs
         Control-xP: poe-wheel-debug
         $endif

   History List Management
       POE::Wheel::ReadLine supports an input history, with searching.

       add_history

       add_history() accepts a list of lines to add to the input history.  Generally it's called
       with a single line: the last line of input received from the terminal.  The "SYNOPSIS"
       shows add_history() in action.

       get_history

       get_history() returns a list containing POE::Wheel::ReadLine's current input history.  It
       may not contain everything entered into the wheel

       write_history

       write_history() writes the current input history to a file.  It accepts one optional
       parameter: the name of the file where the input history will be written.  write_history()
       will write to ~/.history if no file name is specified.

       Returns true on success, or false if not.

       The "SYNOPSIS" shows an example of write_history() and the corresponding read_history().

       read_history

       read_history(FILENAME, START, END) reads a previously saved input history from a named
       file, or from ~/.history if no file name is specified.  It may also read a subset of the
       history file if it's given optional START and END parameters.  The file will be read from
       the beginning if START is omitted or zero.  It will be read to the end if END is omitted
       or earlier than START.

       Returns true on success, or false if not.

       The "SYNOPSIS" shows an example of read_history() and the corresponding write_history().

       Read the first ten history lines:

         $_[HEAP]{console}->read_history("filename", 0, 9);

       history_truncate_file

       history_truncate_file() truncates a history file to a certain number of lines.  It accepts
       two parameters: the name of the file to truncate, and the maximum number of history lines
       to leave in the file.  The history file will be cleared entirely if the line count is zero
       or omitted.

       The file to be truncated defaults to ~/.history.  So calling history_truncate_file() with
       no parameters clears ~/.history.

       Returns true on success, or false if not.

       Note that history_trucate_file() removes the earliest lines from the file.  The later
       lines remain intact since they were the ones most recently entered.

       Keep ~/.history down to a manageable 100 lines:

         $_[HEAP]{console}->history_truncate_file(undef, 100);

   Key Binding Methods
       bind_key

       bind_key(KEYSTROKE, FUNCTION) binds a FUNCTION to a named KEYSTROKE sequence.  The
       keystroke sequence can be in any of the forms defined within readline(3).  The function
       should either be a pre-defined name, such as "self-insert" or a function reference.  The
       binding is made in the current keymap.  Use the rl_set_keymap() method to change keymaps,
       if desired.

       add_defun NAME FN

       add_defun(NAME, FUNCTION) defines a new global FUNCTION, giving it a specific NAME.  The
       function may then be bound to keystrokes by that NAME.

   Console I/O Methods
       clear

       Clears the terminal.

       terminal_size

       Returns what POE::Wheel::ReadLine thinks are the current dimensions of the terminal.
       Returns a list of two values: the number of columns and number of rows, respectively.

         sub some_event_handler {
           my ($columns, $rows) = $_[HEAP]{console}->terminal_size;
           $_[HEAP]{console}->put(
             "Terminal columns: $columns",
             "Terminal rows: $rows",
           );
         }

       get

       get() causes POE::Wheel::ReadLine to display a prompt and then wait for input.  Input is
       not noticed unless get() has enabled the wheel's internal I/O watcher.

       After get() is called, the next line of input or exception on the console will trigger an
       "InputEvent" with the appropriate parameters.  POE::Wheel::ReadLine will then enter an
       inactive state until get() is called again.

       Calls to get() without an argument will preserve the current prompt.  Calling get() with
       an argument before a whole line of input is received will change the prompt on the fly.

       See the "SYNOPSIS" for sample usage.

       put

       put() accepts a list of lines to put on the terminal.  POE::Wheel::ReadLine is line-based.
       See POE::Wheel::Curses for more funky display options.

       Please do not use print() with POE::Wheel::ReadLine.  print() invariably gets the newline
       wrong, leaving an application's output to stairstep down the terminal.  Also, put()
       understands when a user is entering text, and "PutMode" may be used to avoid interrupting
       the user.

   ReadLine Option Methods
       attribs

       attribs() returns a reference to a hash of readline options.  The returned hash may be
       used to query or modify POE::Wheel::ReadLine's behavior.

       option

       option(NAME) returns a specific member of the hash returned by attribs().  It's a more
       convenient way to query POE::Wheel::ReadLine options.

PUBLIC EVENTS

       POE::Wheel::ReadLine emits only a single event.

   InputEvent
       "InputEvent" names the event that will be emitted upon any kind of complete terminal
       input.  Every "InputEvent" handler receives three parameters:

       $_[ARG0] contains a line of input.  It may be an empty string if the user entered an empty
       line.  An undefined $_[ARG0] indicates some exception such as end-of-input or the fact
       that the user canceled their input or pressed C-c (^C).

       $_[ARG1] describes an exception, if one occurred.  It may contain one of the following
       strings:

       cancel
         The "cancel" exception indicates when a user has canceled a line of input.  It's sent
         when the user triggers the "abort" function, which is bound to C-g (^G) by default.

       eot
         "eot" is the ASCII code for "end of tape".  It's emitted when the user requests that the
         terminal be closed.  By default, it's triggered when the user presses C-d (^D) on an
         empty line.

       interrupt
         "interrupt" is sent as a result of the user pressing C-c (^C) or otherwise triggering
         the "interrupt" function.

       Finally, $_[ARG2] contains the ID for the POE::Wheel::ReadLine object that sent the
       "InputEvent".

CUSTOM BINDINGS

       POE::Wheel::ReadLine allows custom functions to be bound to keystrokes.  The function must
       be made visible to the wheel before it can be bound.  To register a function, use
       POE::Wheel::ReadLine's add_defun() method:

         POE::Wheel::ReadLine->add_defun('reverse-line', \&reverse_line);

       When adding a new defun, an optional third parameter may be provided which is a key
       sequence to bind to.  This should be in the same format as that understood by the inputrc
       parsing.

       Bound functions receive three parameters: A reference to the wheel object itself, the key
       sequence that triggered the function (in printable form), and the raw key sequence.  The
       bound function is expected to dig into the POE::Wheel::ReadLine data members to do its
       work and display the new line contents itself.

       This is less than ideal, and it may change in the future.

CUSTOM COMPLETION

       An application may modify POE::Wheel::ReadLine's "completion_function" in order to
       customize how input should be completed.  The new completion function must accept three
       scalar parameters: the word being completed, the entire input text, and the position
       within the input text of the word being completed.

       The completion function should return a list of possible matches.  For example:

         my $attribs = $wheel->attribs();
         $attribs->{completion_function} = sub {
           my ($text, $line, $start) = @_;
           return qw(a list of candidates to complete);
         }

       This is the only form of completion currently supported.

IMPLEMENTATION DIFFERENCES

       Although POE::Wheel::ReadLine is modeled after the readline(3) library, there are some
       areas which have not been implemented.  The only option settings which have effect in this
       implementation are: bell-style, editing-mode, isearch-terminators, comment-begin, print-
       completions-horizontally, show-all-if-ambiguous and completion_function.

       The function 'tab-insert' is not implemented, nor are tabs displayed properly.

SEE ALSO

       POE::Wheel describes the basic operations of all wheels in more depth.  You need to know
       this.

       readline(3), Term::Cap, Term::ReadKey.

       The SEE ALSO section in POE contains a table of contents covering the entire POE
       distribution.

       Term::Visual is an alternative to POE::Wheel::ReadLine.  It provides scrollback and a
       status bar in addition to editable user input.  Term::Visual supports POE despite the lack
       of "POE" in its name.

BUGS

       POE::Wheel::ReadLine has some known issues:

   Perl 5.8.0 is Broken
       Non-blocking input with Term::ReadKey does not work with Perl 5.8.0, especially on Linux
       systems for some reason.  Upgrading Perl will fix things.  If you can't upgrade Perl,
       consider alternative input methods, such as Term::Visual.

       <http://rt.cpan.org/Ticket/Display.html?id=4524> and related tickets explain the issue in
       detail.  If you suspect your system is one where Term::ReadKey fails, you can run this
       test program to be sure.

         #!/usr/bin/perl
         use Term::ReadKey;
         print "Press 'q' to quit this test.\n";
         ReadMode 5; # Turns off controls keys
         while (1) {
           while (not defined ($key = ReadKey(-1))) {
             print "Didn't get a key.  Sleeping 1 second.\015\012";
             sleep (1);
           }
           print "Got key: $key\015\012";
           ($key eq 'q') and last;
         }
         ReadMode 0; # Reset tty mode before exiting
         exit;

   Non-Optimal Code
       Dissociating the input and display cursors introduced a lot of code.  Much of this code
       was thrown in hastily, and things can probably be done with less work.

   Unimplemented Features
       Input editing is not kept on one line.  If it wraps, and a terminal cannot wrap back
       through a line division, the cursor will become lost.

       Unicode support.  I feel real bad about throwing away native representation of all the
       8th-bit-set characters.  I also have no idea how to do this, and I don't have a system to
       test this.  Patches are very much welcome.

GOTCHAS / FAQ

   Lost Prompts
       Q: Why do I lose my prompt every time I send output to the screen?

       A: You probably are using print or printf to write screen output.  ReadLine doesn't track
       STDOUT itself, so it doesn't know when to refresh the prompt after you do this.  Use
       ReadLine's put() method to write lines to the console.

   Edit Keystrokes Display as ^C
       Q: None of the editing keystrokes work.  Ctrl-C displays "^c" rather than generating an
       interrupt.  The arrow keys don't scroll through my input history.  It's generally a bad
       experience.

       A: You're probably a vi/vim user.  In the absence of a ~/.inputrc file,
       POE::Wheel::ReadLine checks your EDITOR environment variable for clues about your editing
       preference.  If it sees /vi/ in there, it starts in vi mode.  You can override this by
       creating a ~/.inputrc file containing the line "set editing-mode emacs", or adding that
       line to your existing ~/.inputrc.  While you're in there, you should totally get
       acquainted with all the other cool stuff you can do with .inputrc files.

   Lack of Windows Support
       Q: Why doesn't POE::Wheel::ReadLine work on Windows?  Term::ReadLine does.

       A: POE::Wheel::ReadLine requires select(), because that's what POE uses by default to
       detect keystrokes without blocking.  About half the flavors of Perl on Windows implement
       select() in terms of the same function in the WinSock library, which limits select() to
       working only with sockets.  Your console isn't a socket, so select() doesn't work with
       your version of Perl on Windows.

       Really good workarounds are possible but don't exist as of this writing.  They involve
       writing a special POE::Loop for Windows that either uses a Win32-specific module for
       better multiplexing, that polls for input, or that uses blocking I/O watchers in separate
       threads.

   Cygwin Support
       Q: Why does POE::Wheel::ReadLine complain about my "dumb" terminal?

       A: Do you have Strawberry Perl installed? Due to the way it works, on installation it sets
       a global environment variable in MSWin32 for TERM=dumb. ( it may be fixed in a future
       version, but it's here to stay for now, ha! ) In this case, logging into the Cygwin shell
       via the cygwin.bat launcher results in a nonfunctional readline.

       Normally, Cygwin will set TERM=cygwin in the launcher. However, if the TERM was already
       set it will not alter the value. Hence, the "bug" appears! What you can do is to hack the
       cygwin.bat file to add this line:

         SET TERM=cygwin

       Other users reported that you can have better results by editing the ~/.bash_profile file
       to set TERM=cygwin because on a Cygwin upgrade it overwrites the cygwin.bat file.

       Alternatively, you could install different terminals like "xterm" or "rxvt" as shown here:
       <http://c2.com/cgi/wiki?BetterCygwinTerminal>. Please let us know if you encounter
       problems using any terminal other than "dumb".

       If you feel brave, you can peruse the RT ticket at
       <http://rt.cpan.org/Ticket/Display.html?id=55365> for more information on this problem.

AUTHORS & COPYRIGHTS

       POE::Wheel::ReadLine was originally written by Rocco Caputo.

       Nick Williams virtually rewrote it to support a larger subset of GNU readline.

       Please see POE for more information about other authors and contributors.