This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Change 'continuing anyway' to 'probably harmless'
[perl5.git] / lib / Term / ReadLine.pm
CommitLineData
cb31d310 1=head1 NAME
2
c07a80fd 3Term::ReadLine - Perl interface to various C<readline> packages. If
cb31d310 4no real package is found, substitutes stubs instead of basic functions.
5
6=head1 SYNOPSIS
7
8 use Term::ReadLine;
9 $term = new Term::ReadLine 'Simple Perl calc';
10 $prompt = "Enter your arithmetic expression: ";
11 $OUT = $term->OUT || STDOUT;
12 while ( defined ($_ = $term->readline($prompt)) ) {
13 $res = eval($_), "\n";
14 warn $@ if $@;
15 print $OUT $res, "\n" unless $@;
16 $term->addhistory($_) if /\S/;
17 }
18
c07a80fd 19=head1 DESCRIPTION
20
21This package is just a front end to some other packages. At the moment
22this description is written, the only such package is Term-ReadLine,
23available on CPAN near you. The real target of this stub package is to
24set up a common interface to whatever Readline emerges with time.
25
cb31d310 26=head1 Minimal set of supported functions
27
28All the supported functions should be called as methods, i.e., either as
29
30 $term = new Term::ReadLine 'name';
31
32or as
33
34 $term->addhistory('row');
35
1fef88e7 36where $term is a return value of Term::ReadLine-E<gt>Init.
cb31d310 37
38=over 12
39
40=item C<ReadLine>
41
42returns the actual package that executes the commands. Among possible
43values are C<Term::ReadLine::Gnu>, C<Term::ReadLine::Perl>,
44C<Term::ReadLine::Stub Exporter>.
45
46=item C<new>
47
48returns the handle for subsequent calls to following
49functions. Argument is the name of the application. Optionally can be
50followed by two arguments for C<IN> and C<OUT> filehandles. These
51arguments should be globs.
52
53=item C<readline>
54
55gets an input line, I<possibly> with actual C<readline>
56support. Trailing newline is removed. Returns C<undef> on C<EOF>.
57
58=item C<addhistory>
59
60adds the line to the history of input, from where it can be used if
61the actual C<readline> is present.
62
63=item C<IN>, $C<OUT>
64
65return the filehandles for input and output or C<undef> if C<readline>
66input and output cannot be used for Perl.
67
68=item C<MinLine>
69
70If argument is specified, it is an advice on minimal size of line to
71be included into history. C<undef> means do not include anything into
72history. Returns the old value.
73
74=item C<findConsole>
75
76returns an array with two strings that give most appropriate names for
1fef88e7 77files for input and output using conventions C<"E<lt>$in">, C<"E<gt>out">.
cb31d310 78
79=item C<Features>
80
81Returns a reference to a hash with keys being features present in
82current implementation. Several optional features are used in the
83minimal interface: C<appname> should be present if the first argument
84to C<new> is recognized, and C<minline> should be present if
85C<MinLine> method is not dummy. C<autohistory> should be present if
86lines are put into history automatically (maybe subject to
87C<MinLine>), and C<addhistory> if C<addhistory> method is not dummy.
88
89=back
90
91Actually C<Term::ReadLine> can use some other package, that will
92support reacher set of commands.
93
94=head1 EXPORTS
95
96None
97
98=cut
99
100package Term::ReadLine::Stub;
101
102$DB::emacs = $DB::emacs; # To peacify -w
103
104sub ReadLine {'Term::ReadLine::Stub'}
105sub readline {
385588b3 106 my ($in,$out,$str) = @{shift()};
cb31d310 107 print $out shift;
385588b3 108 $str = scalar <$in>;
cb31d310 109 # bug in 5.000: chomping empty string creats length -1:
110 chomp $str if defined $str;
111 $str;
112}
113sub addhistory {}
114
115sub findConsole {
116 my $console;
117
118 if (-e "/dev/tty") {
119 $console = "/dev/tty";
120 } elsif (-e "con") {
121 $console = "con";
122 } else {
123 $console = "sys\$command";
124 }
125
126 if (defined $ENV{'OS2_SHELL'}) { # In OS/2
127 if ($DB::emacs) {
128 $console = undef;
129 } else {
130 $console = "/dev/con";
131 }
132 }
133
134 $consoleOUT = $console;
135 $console = "&STDIN" unless defined $console;
136 if (!defined $consoleOUT) {
137 $consoleOUT = defined fileno(STDERR) ? "&STDERR" : "&STDOUT";
138 }
139 ($console,$consoleOUT);
140}
141
142sub new {
143 die "method new called with wrong number of arguments"
144 unless @_==2 or @_==4;
145 #local (*FIN, *FOUT);
146 my ($FIN, $FOUT);
147 if (@_==2) {
148 ($console, $consoleOUT) = findConsole;
149
150 open(FIN, "<$console");
151 open(FOUT,">$consoleOUT");
152 #OUT->autoflush(1); # Conflicts with debugger?
153 $sel = select(FOUT);
154 $| = 1; # for DB::OUT
155 select($sel);
156 bless [\*FIN, \*FOUT];
157 } else { # Filehandles supplied
158 $FIN = $_[2]; $FOUT = $_[3];
159 #OUT->autoflush(1); # Conflicts with debugger?
160 $sel = select($FOUT);
161 $| = 1; # for DB::OUT
162 select($sel);
163 bless [$FIN, $FOUT];
164 }
165}
166sub IN { shift->[0] }
167sub OUT { shift->[1] }
168sub MinLine { undef }
385588b3 169sub Features { {} }
cb31d310 170
171package Term::ReadLine; # So late to allow the above code be defined?
385588b3 172eval "use Term::ReadLine::Gnu;" or eval "use Term::ReadLine::Perl;";
cb31d310 173
174#require FileHandle;
175
176# To make possible switch off RL in debugger: (Not needed, work done
177# in debugger).
178
179if (defined &Term::ReadLine::Gnu::readline) {
180 @ISA = qw(Term::ReadLine::Gnu Term::ReadLine::Stub);
181} elsif (defined &Term::ReadLine::Perl::readline) {
182 @ISA = qw(Term::ReadLine::Perl Term::ReadLine::Stub);
183} else {
184 @ISA = qw(Term::ReadLine::Stub);
185}
186
187
1881;
189