1N/A=head1 NAME
1N/A
1N/ATerm::ReadLine - Perl interface to various C<readline> packages.
1N/AIf no real package is found, substitutes stubs instead of basic functions.
1N/A
1N/A=head1 SYNOPSIS
1N/A
1N/A use Term::ReadLine;
1N/A my $term = new Term::ReadLine 'Simple Perl calc';
1N/A my $prompt = "Enter your arithmetic expression: ";
1N/A my $OUT = $term->OUT || \*STDOUT;
1N/A while ( defined ($_ = $term->readline($prompt)) ) {
1N/A my $res = eval($_);
1N/A warn $@ if $@;
1N/A print $OUT $res, "\n" unless $@;
1N/A $term->addhistory($_) if /\S/;
1N/A }
1N/A
1N/A=head1 DESCRIPTION
1N/A
1N/AThis package is just a front end to some other packages. At the moment
1N/Athis description is written, the only such package is Term-ReadLine,
1N/Aavailable on CPAN near you. The real target of this stub package is to
1N/Aset up a common interface to whatever Readline emerges with time.
1N/A
1N/A=head1 Minimal set of supported functions
1N/A
1N/AAll the supported functions should be called as methods, i.e., either as
1N/A
1N/A $term = new Term::ReadLine 'name';
1N/A
1N/Aor as
1N/A
1N/A $term->addhistory('row');
1N/A
1N/Awhere $term is a return value of Term::ReadLine-E<gt>new().
1N/A
1N/A=over 12
1N/A
1N/A=item C<ReadLine>
1N/A
1N/Areturns the actual package that executes the commands. Among possible
1N/Avalues are C<Term::ReadLine::Gnu>, C<Term::ReadLine::Perl>,
1N/AC<Term::ReadLine::Stub>.
1N/A
1N/A=item C<new>
1N/A
1N/Areturns the handle for subsequent calls to following
1N/Afunctions. Argument is the name of the application. Optionally can be
1N/Afollowed by two arguments for C<IN> and C<OUT> filehandles. These
1N/Aarguments should be globs.
1N/A
1N/A=item C<readline>
1N/A
1N/Agets an input line, I<possibly> with actual C<readline>
1N/Asupport. Trailing newline is removed. Returns C<undef> on C<EOF>.
1N/A
1N/A=item C<addhistory>
1N/A
1N/Aadds the line to the history of input, from where it can be used if
1N/Athe actual C<readline> is present.
1N/A
1N/A=item C<IN>, C<OUT>
1N/A
1N/Areturn the filehandles for input and output or C<undef> if C<readline>
1N/Ainput and output cannot be used for Perl.
1N/A
1N/A=item C<MinLine>
1N/A
1N/AIf argument is specified, it is an advice on minimal size of line to
1N/Abe included into history. C<undef> means do not include anything into
1N/Ahistory. Returns the old value.
1N/A
1N/A=item C<findConsole>
1N/A
1N/Areturns an array with two strings that give most appropriate names for
1N/Afiles for input and output using conventions C<"E<lt>$in">, C<"E<gt>out">.
1N/A
1N/A=item Attribs
1N/A
1N/Areturns a reference to a hash which describes internal configuration
1N/Aof the package. Names of keys in this hash conform to standard
1N/Aconventions with the leading C<rl_> stripped.
1N/A
1N/A=item C<Features>
1N/A
1N/AReturns a reference to a hash with keys being features present in
1N/Acurrent implementation. Several optional features are used in the
1N/Aminimal interface: C<appname> should be present if the first argument
1N/Ato C<new> is recognized, and C<minline> should be present if
1N/AC<MinLine> method is not dummy. C<autohistory> should be present if
1N/Alines are put into history automatically (maybe subject to
1N/AC<MinLine>), and C<addhistory> if C<addhistory> method is not dummy.
1N/A
1N/AIf C<Features> method reports a feature C<attribs> as present, the
1N/Amethod C<Attribs> is not dummy.
1N/A
1N/A=back
1N/A
1N/A=head1 Additional supported functions
1N/A
1N/AActually C<Term::ReadLine> can use some other package, that will
1N/Asupport reacher set of commands.
1N/A
1N/AAll these commands are callable via method interface and have names
1N/Awhich conform to standard conventions with the leading C<rl_> stripped.
1N/A
1N/AThe stub package included with the perl distribution allows some
1N/Aadditional methods:
1N/A
1N/A=over 12
1N/A
1N/A=item C<tkRunning>
1N/A
1N/Amakes Tk event loop run when waiting for user input (i.e., during
1N/AC<readline> method).
1N/A
1N/A=item C<ornaments>
1N/A
1N/Amakes the command line stand out by using termcap data. The argument
1N/Ato C<ornaments> should be 0, 1, or a string of a form
1N/AC<"aa,bb,cc,dd">. Four components of this string should be names of
1N/AI<terminal capacities>, first two will be issued to make the prompt
1N/Astandout, last two to make the input line standout.
1N/A
1N/A=item C<newTTY>
1N/A
1N/Atakes two arguments which are input filehandle and output filehandle.
1N/ASwitches to use these filehandles.
1N/A
1N/A=back
1N/A
1N/AOne can check whether the currently loaded ReadLine package supports
1N/Athese methods by checking for corresponding C<Features>.
1N/A
1N/A=head1 EXPORTS
1N/A
1N/ANone
1N/A
1N/A=head1 ENVIRONMENT
1N/A
1N/AThe environment variable C<PERL_RL> governs which ReadLine clone is
1N/Aloaded. If the value is false, a dummy interface is used. If the value
1N/Ais true, it should be tail of the name of the package to use, such as
1N/AC<Perl> or C<Gnu>.
1N/A
1N/AAs a special case, if the value of this variable is space-separated,
1N/Athe tail might be used to disable the ornaments by setting the tail to
1N/Abe C<o=0> or C<ornaments=0>. The head should be as described above, say
1N/A
1N/AIf the variable is not set, or if the head of space-separated list is
1N/Aempty, the best available package is loaded.
1N/A
1N/A export "PERL_RL=Perl o=0" # Use Perl ReadLine without ornaments
1N/A export "PERL_RL= o=0" # Use best available ReadLine without ornaments
1N/A
1N/A(Note that processing of C<PERL_RL> for ornaments is in the discretion of the
1N/Aparticular used C<Term::ReadLine::*> package).
1N/A
1N/A=head1 CAVEATS
1N/A
1N/AIt seems that using Term::ReadLine from Emacs minibuffer doesn't work
1N/Aquite right and one will get an error message like
1N/A
1N/A Cannot open /dev/tty for read at ...
1N/A
1N/AOne possible workaround for this is to explicitly open /dev/tty like this
1N/A
1N/A open (FH, "/dev/tty" )
1N/A or eval 'sub Term::ReadLine::findConsole { ("&STDIN", "&STDERR") }';
1N/A die $@ if $@;
1N/A close (FH);
1N/A
1N/Aor you can try using the 4-argument form of Term::ReadLine->new().
1N/A
1N/A=cut
1N/A
1N/Ause strict;
1N/A
1N/Apackage Term::ReadLine::Stub;
1N/Aour @ISA = qw'Term::ReadLine::Tk Term::ReadLine::TermCap';
1N/A
1N/A$DB::emacs = $DB::emacs; # To peacify -w
1N/Aour @rl_term_set;
1N/A*rl_term_set = \@Term::ReadLine::TermCap::rl_term_set;
1N/A
1N/Asub PERL_UNICODE_STDIN () { 0x0001 }
1N/A
1N/Asub ReadLine {'Term::ReadLine::Stub'}
1N/Asub readline {
1N/A my $self = shift;
1N/A my ($in,$out,$str) = @$self;
1N/A my $prompt = shift;
1N/A print $out $rl_term_set[0], $prompt, $rl_term_set[1], $rl_term_set[2];
1N/A $self->register_Tk
1N/A if not $Term::ReadLine::registered and $Term::ReadLine::toloop
1N/A and defined &Tk::DoOneEvent;
1N/A #$str = scalar <$in>;
1N/A $str = $self->get_line;
1N/A $str =~ s/^\s*\Q$prompt\E// if ($^O eq 'MacOS');
1N/A utf8::upgrade($str)
1N/A if (${^UNICODE} & PERL_UNICODE_STDIN || defined ${^ENCODING}) &&
1N/A utf8::valid($str);
1N/A print $out $rl_term_set[3];
1N/A # bug in 5.000: chomping empty string creats length -1:
1N/A chomp $str if defined $str;
1N/A $str;
1N/A}
1N/Asub addhistory {}
1N/A
1N/Asub findConsole {
1N/A my $console;
1N/A
1N/A if ($^O eq 'MacOS') {
1N/A $console = "Dev:Console";
1N/A } elsif (-e "/dev/tty") {
1N/A $console = "/dev/tty";
1N/A } elsif (-e "con" or $^O eq 'MSWin32') {
1N/A $console = "con";
1N/A } else {
1N/A $console = "sys\$command";
1N/A }
1N/A
1N/A if (($^O eq 'amigaos') || ($^O eq 'beos') || ($^O eq 'epoc')) {
1N/A $console = undef;
1N/A }
1N/A elsif ($^O eq 'os2') {
1N/A if ($DB::emacs) {
1N/A $console = undef;
1N/A } else {
1N/A $console = "/dev/con";
1N/A }
1N/A }
1N/A
1N/A my $consoleOUT = $console;
1N/A $console = "&STDIN" unless defined $console;
1N/A if (!defined $consoleOUT) {
1N/A $consoleOUT = defined fileno(STDERR) ? "&STDERR" : "&STDOUT";
1N/A }
1N/A ($console,$consoleOUT);
1N/A}
1N/A
1N/Asub new {
1N/A die "method new called with wrong number of arguments"
1N/A unless @_==2 or @_==4;
1N/A #local (*FIN, *FOUT);
1N/A my ($FIN, $FOUT, $ret);
1N/A if (@_==2) {
1N/A my($console, $consoleOUT) = $_[0]->findConsole;
1N/A
1N/A open(FIN, "<$console");
1N/A open(FOUT,">$consoleOUT");
1N/A #OUT->autoflush(1); # Conflicts with debugger?
1N/A my $sel = select(FOUT);
1N/A $| = 1; # for DB::OUT
1N/A select($sel);
1N/A $ret = bless [\*FIN, \*FOUT];
1N/A } else { # Filehandles supplied
1N/A $FIN = $_[2]; $FOUT = $_[3];
1N/A #OUT->autoflush(1); # Conflicts with debugger?
1N/A my $sel = select($FOUT);
1N/A $| = 1; # for DB::OUT
1N/A select($sel);
1N/A $ret = bless [$FIN, $FOUT];
1N/A }
1N/A if ($ret->Features->{ornaments}
1N/A and not ($ENV{PERL_RL} and $ENV{PERL_RL} =~ /\bo\w*=0/)) {
1N/A local $Term::ReadLine::termcap_nowarn = 1;
1N/A $ret->ornaments(1);
1N/A }
1N/A return $ret;
1N/A}
1N/A
1N/Asub newTTY {
1N/A my ($self, $in, $out) = @_;
1N/A $self->[0] = $in;
1N/A $self->[1] = $out;
1N/A my $sel = select($out);
1N/A $| = 1; # for DB::OUT
1N/A select($sel);
1N/A}
1N/A
1N/Asub IN { shift->[0] }
1N/Asub OUT { shift->[1] }
1N/Asub MinLine { undef }
1N/Asub Attribs { {} }
1N/A
1N/Amy %features = (tkRunning => 1, ornaments => 1, 'newTTY' => 1);
1N/Asub Features { \%features }
1N/A
1N/Apackage Term::ReadLine; # So late to allow the above code be defined?
1N/A
1N/Aour $VERSION = '1.01';
1N/A
1N/Amy ($which) = exists $ENV{PERL_RL} ? split /\s+/, $ENV{PERL_RL} : undef;
1N/Aif ($which) {
1N/A if ($which =~ /\bgnu\b/i){
1N/A eval "use Term::ReadLine::Gnu;";
1N/A } elsif ($which =~ /\bperl\b/i) {
1N/A eval "use Term::ReadLine::Perl;";
1N/A } else {
1N/A eval "use Term::ReadLine::$which;";
1N/A }
1N/A} elsif (defined $which and $which ne '') { # Defined but false
1N/A # Do nothing fancy
1N/A} else {
1N/A eval "use Term::ReadLine::Gnu; 1" or eval "use Term::ReadLine::Perl; 1";
1N/A}
1N/A
1N/A#require FileHandle;
1N/A
1N/A# To make possible switch off RL in debugger: (Not needed, work done
1N/A# in debugger).
1N/Aour @ISA;
1N/Aif (defined &Term::ReadLine::Gnu::readline) {
1N/A @ISA = qw(Term::ReadLine::Gnu Term::ReadLine::Stub);
1N/A} elsif (defined &Term::ReadLine::Perl::readline) {
1N/A @ISA = qw(Term::ReadLine::Perl Term::ReadLine::Stub);
1N/A} elsif (defined $which && defined &{"Term::ReadLine::$which\::readline"}) {
1N/A @ISA = "Term::ReadLine::$which";
1N/A} else {
1N/A @ISA = qw(Term::ReadLine::Stub);
1N/A}
1N/A
1N/Apackage Term::ReadLine::TermCap;
1N/A
1N/A# Prompt-start, prompt-end, command-line-start, command-line-end
1N/A# -- zero-width beautifies to emit around prompt and the command line.
1N/Aour @rl_term_set = ("","","","");
1N/A# string encoded:
1N/Aour $rl_term_set = ',,,';
1N/A
1N/Aour $terminal;
1N/Asub LoadTermCap {
1N/A return if defined $terminal;
1N/A
1N/A require Term::Cap;
1N/A $terminal = Tgetent Term::Cap ({OSPEED => 9600}); # Avoid warning.
1N/A}
1N/A
1N/Asub ornaments {
1N/A shift;
1N/A return $rl_term_set unless @_;
1N/A $rl_term_set = shift;
1N/A $rl_term_set ||= ',,,';
1N/A $rl_term_set = 'us,ue,md,me' if $rl_term_set eq '1';
1N/A my @ts = split /,/, $rl_term_set, 4;
1N/A eval { LoadTermCap };
1N/A unless (defined $terminal) {
1N/A warn("Cannot find termcap: $@\n") unless $Term::ReadLine::termcap_nowarn;
1N/A $rl_term_set = ',,,';
1N/A return;
1N/A }
1N/A @rl_term_set = map {$_ ? $terminal->Tputs($_,1) || '' : ''} @ts;
1N/A return $rl_term_set;
1N/A}
1N/A
1N/A
1N/Apackage Term::ReadLine::Tk;
1N/A
1N/Aour($count_handle, $count_DoOne, $count_loop);
1N/A$count_handle = $count_DoOne = $count_loop = 0;
1N/A
1N/Aour($giveup);
1N/Asub handle {$giveup = 1; $count_handle++}
1N/A
1N/Asub Tk_loop {
1N/A # Tk->tkwait('variable',\$giveup); # needs Widget
1N/A $count_DoOne++, Tk::DoOneEvent(0) until $giveup;
1N/A $count_loop++;
1N/A $giveup = 0;
1N/A}
1N/A
1N/Asub register_Tk {
1N/A my $self = shift;
1N/A $Term::ReadLine::registered++
1N/A or Tk->fileevent($self->IN,'readable',\&handle);
1N/A}
1N/A
1N/Asub tkRunning {
1N/A $Term::ReadLine::toloop = $_[1] if @_ > 1;
1N/A $Term::ReadLine::toloop;
1N/A}
1N/A
1N/Asub get_c {
1N/A my $self = shift;
1N/A $self->Tk_loop if $Term::ReadLine::toloop && defined &Tk::DoOneEvent;
1N/A return getc $self->IN;
1N/A}
1N/A
1N/Asub get_line {
1N/A my $self = shift;
1N/A $self->Tk_loop if $Term::ReadLine::toloop && defined &Tk::DoOneEvent;
1N/A my $in = $self->IN;
1N/A local ($/) = "\n";
1N/A return scalar <$in>;
1N/A}
1N/A
1N/A1;
1N/A