=begin html

<a href="https://travis-ci.org/rocky/p5-Term-ReadLine-Perl5"><img src="https://travis-ci.org/rocky/p5-Term-ReadLine-Perl5.png"></a>

=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<emacs> or
I<vi> 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

C<Term::ReadLine::Perl-E<gt>new($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
C<Term::ReadLine-E<gt>new($term_name)> if other Term::ReadLine packages
like L<Term::ReadLine::Gnu> 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_history($max)>

Stifle or put a cap on the history list, remembering only C<$max>
number of lines.

=head3 Minline

C<MinLine([$minlength])>

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($which)>

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<Attribs> method.  Names of keys in this hash conform to standard
conventions with the leading C<rl_> 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<line_edit.pl>.

Ilya Zakharevich turned this into a Perl5 module called
L<Term::ReadLine::Perl>. Some of the changes he made include using
L<Term::ReadKey> if present, and made this work under I<xterm>. The
file F<Term/ReadLine/Perl5/CHANGES> 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 (github) 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<github issues
tracker|https://github.com/rocky/p5-Term-ReadLine-Perl5/issues>.

=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
