=begin html =end html =encoding utf8 =head1 NAME Term::ReadLine::Perl5 - A Perl5 implementation GNU Readline =head1 SYNOPSIS use Term::ReadLine::Perl5; $term = new Term::ReadLine::Perl5 'ProgramName'; while ( defined ($_ = $term->readline('prompt>')) ) { ... } =head1 DESCRIPTION =head2 Overview This is a implementation of the GNU Readline/History Library written in Perl5. GNU Readline reads lines from an interactive terminal with I or I editing capabilities. It provides as mechanism for saving history of previous input. This package typically used in command-line interfaces and REPLs (Read, Eval, Print, Loop). =head2 SUBROUTINES =head3 Cnew($name, [*IN, [*OUT])> Returns a handle for subsequent calls to readline functions. C<$name> is the name of the application. Optionally you can add two arguments for input and output filehandles. These arguments should be globs. This routine might also be called via Cnew($term_name)> if other Term::ReadLine packages like L is not available or if you have C<$ENV{PERL_RL}> set to 'Perl5'; At present, because this code has lots of global state, we currently don't support more than one readline instance. Somebody please volunteer to rewrite this code! =head3 stifle_history C Stifle or put a cap on the history list, remembering only C<$max> number of lines. =head3 Minline C If C<$minlength> is given, set C<$readline::minlength> the minimum length a $line for it to go into the readline history. The previous value is returned. =head3 remove_history C Remove history element C<$which> from the history. The removed element is returned. =head2 Variables Following GNU Readline/History Library variables can be accessed from Perl program. See 'GNU Readline Library Manual' and ' GNU History Library Manual' for each variable. You can access them via the C method. Names of keys in this hash conform to standard conventions with the leading C stripped. Example: $term = new Term::ReadLine::Perl5 'ReadLineTest' $attribs = $term->Attribs; $v = $attribs->{history_base}; # history_base =head3 Attribute Names completion_suppress_append (bool) history_base (int) history_stifled (int) history_length (int) max_input_history (int) outstream (file handle) =head1 INSTALL To install this module type: perl Build.PL make # for interactive testing: make test # for non-interactive testing AUTOMATED_TESTING=1 make test make install # might need sudo make install =head1 DEVELOPMENT HISTORY The first implementation was in Perl4 (mostly) by Jeffrey Friedl. He referenced FSF the code Roland Schemers F. Ilya Zakharevich turned this into a Perl5 module called L. Some of the changes he made include using L if present, and made this work under I. The file F up to but not including version 1.04 contains a list of his changes. Starting with version 1.04 Rocky Bernstein forked the code, adding GNU readline history. He put it into a public git repository (git) and also started modernizing it by doing the things CPAN prefers, including adding POD documentation, non-interactive tests, and respecting CPAN module namespaces. =head1 BUGS Bugs are accepted via the L. =head1 LICENSE Copyright (c) 2013 Rocky Bernstein. Copyright (c) 1995 Ilya Zakharevich. This program is distributed WITHOUT ANY WARRANTY, including but not limited to the implied warranties of merchantability or fitness for a particular purpose. The program is free software. You may distribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation (either version 2 or any later version) and the Perl Artistic License as published by O’Reilly Media, Inc. Please open the files named gpl-2.0.txt and Artistic for a copy of these licenses. =cut