home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / share / perl / 5.8.8 / Term / ReadLine.pm < prev   
Encoding:
Perl POD Document  |  2006-07-07  |  10.7 KB  |  400 lines
  1. =head1 NAME
  2.  
  3. Term::ReadLine - Perl interface to various C<readline> packages.
  4. If no real package is found, substitutes stubs instead of basic functions.
  5.  
  6. =head1 SYNOPSIS
  7.  
  8.   use Term::ReadLine;
  9.   my $term = new Term::ReadLine 'Simple Perl calc';
  10.   my $prompt = "Enter your arithmetic expression: ";
  11.   my $OUT = $term->OUT || \*STDOUT;
  12.   while ( defined ($_ = $term->readline($prompt)) ) {
  13.     my $res = eval($_);
  14.     warn $@ if $@;
  15.     print $OUT $res, "\n" unless $@;
  16.     $term->addhistory($_) if /\S/;
  17.   }
  18.  
  19. =head1 DESCRIPTION
  20.  
  21. This package is just a front end to some other packages. It's a stub to
  22. set up a common interface to the various ReadLine implementations found on
  23. CPAN (under the C<Term::ReadLine::*> namespace).
  24.  
  25. =head1 Minimal set of supported functions
  26.  
  27. All the supported functions should be called as methods, i.e., either as 
  28.  
  29.   $term = new Term::ReadLine 'name';
  30.  
  31. or as 
  32.  
  33.   $term->addhistory('row');
  34.  
  35. where $term is a return value of Term::ReadLine-E<gt>new().
  36.  
  37. =over 12
  38.  
  39. =item C<ReadLine>
  40.  
  41. returns the actual package that executes the commands. Among possible
  42. values are C<Term::ReadLine::Gnu>, C<Term::ReadLine::Perl>,
  43. C<Term::ReadLine::Stub>.
  44.  
  45. =item C<new>
  46.  
  47. returns the handle for subsequent calls to following
  48. functions. Argument is the name of the application. Optionally can be
  49. followed by two arguments for C<IN> and C<OUT> filehandles. These
  50. arguments should be globs.
  51.  
  52. =item C<readline>
  53.  
  54. gets an input line, I<possibly> with actual C<readline>
  55. support. Trailing newline is removed. Returns C<undef> on C<EOF>.
  56.  
  57. =item C<addhistory>
  58.  
  59. adds the line to the history of input, from where it can be used if
  60. the actual C<readline> is present.
  61.  
  62. =item C<IN>, C<OUT>
  63.  
  64. return the filehandles for input and output or C<undef> if C<readline>
  65. input and output cannot be used for Perl.
  66.  
  67. =item C<MinLine>
  68.  
  69. If argument is specified, it is an advice on minimal size of line to
  70. be included into history.  C<undef> means do not include anything into
  71. history. Returns the old value.
  72.  
  73. =item C<findConsole>
  74.  
  75. returns an array with two strings that give most appropriate names for
  76. files for input and output using conventions C<"E<lt>$in">, C<"E<gt>out">.
  77.  
  78. =item Attribs
  79.  
  80. returns a reference to a hash which describes internal configuration
  81. of the package. Names of keys in this hash conform to standard
  82. conventions with the leading C<rl_> stripped.
  83.  
  84. =item C<Features>
  85.  
  86. Returns a reference to a hash with keys being features present in
  87. current implementation. Several optional features are used in the
  88. minimal interface: C<appname> should be present if the first argument
  89. to C<new> is recognized, and C<minline> should be present if
  90. C<MinLine> method is not dummy.  C<autohistory> should be present if
  91. lines are put into history automatically (maybe subject to
  92. C<MinLine>), and C<addhistory> if C<addhistory> method is not dummy.
  93.  
  94. If C<Features> method reports a feature C<attribs> as present, the
  95. method C<Attribs> is not dummy.
  96.  
  97. =back
  98.  
  99. =head1 Additional supported functions
  100.  
  101. Actually C<Term::ReadLine> can use some other package, that will
  102. support a richer set of commands.
  103.  
  104. All these commands are callable via method interface and have names
  105. which conform to standard conventions with the leading C<rl_> stripped.
  106.  
  107. The stub package included with the perl distribution allows some
  108. additional methods: 
  109.  
  110. =over 12
  111.  
  112. =item C<tkRunning>
  113.  
  114. makes Tk event loop run when waiting for user input (i.e., during
  115. C<readline> method).
  116.  
  117. =item C<ornaments>
  118.  
  119. makes the command line stand out by using termcap data.  The argument
  120. to C<ornaments> should be 0, 1, or a string of a form
  121. C<"aa,bb,cc,dd">.  Four components of this string should be names of
  122. I<terminal capacities>, first two will be issued to make the prompt
  123. standout, last two to make the input line standout.
  124.  
  125. =item C<newTTY>
  126.  
  127. takes two arguments which are input filehandle and output filehandle.
  128. Switches to use these filehandles.
  129.  
  130. =back
  131.  
  132. One can check whether the currently loaded ReadLine package supports
  133. these methods by checking for corresponding C<Features>.
  134.  
  135. =head1 EXPORTS
  136.  
  137. None
  138.  
  139. =head1 ENVIRONMENT
  140.  
  141. The environment variable C<PERL_RL> governs which ReadLine clone is
  142. loaded. If the value is false, a dummy interface is used. If the value
  143. is true, it should be tail of the name of the package to use, such as
  144. C<Perl> or C<Gnu>.  
  145.  
  146. As a special case, if the value of this variable is space-separated,
  147. the tail might be used to disable the ornaments by setting the tail to
  148. be C<o=0> or C<ornaments=0>.  The head should be as described above, say
  149.  
  150. If the variable is not set, or if the head of space-separated list is
  151. empty, the best available package is loaded.
  152.  
  153.   export "PERL_RL=Perl o=0"    # Use Perl ReadLine without ornaments
  154.   export "PERL_RL= o=0"        # Use best available ReadLine without ornaments
  155.  
  156. (Note that processing of C<PERL_RL> for ornaments is in the discretion of the 
  157. particular used C<Term::ReadLine::*> package).
  158.  
  159. =head1 CAVEATS
  160.  
  161. It seems that using Term::ReadLine from Emacs minibuffer doesn't work
  162. quite right and one will get an error message like
  163.  
  164.     Cannot open /dev/tty for read at ...
  165.  
  166. One possible workaround for this is to explicitly open /dev/tty like this
  167.  
  168.     open (FH, "/dev/tty" )
  169.       or eval 'sub Term::ReadLine::findConsole { ("&STDIN", "&STDERR") }';
  170.     die $@ if $@;
  171.     close (FH);
  172.  
  173. or you can try using the 4-argument form of Term::ReadLine->new().
  174.  
  175. =cut
  176.  
  177. use strict;
  178.  
  179. package Term::ReadLine::Stub;
  180. our @ISA = qw'Term::ReadLine::Tk Term::ReadLine::TermCap';
  181.  
  182. $DB::emacs = $DB::emacs;    # To peacify -w
  183. our @rl_term_set;
  184. *rl_term_set = \@Term::ReadLine::TermCap::rl_term_set;
  185.  
  186. sub PERL_UNICODE_STDIN () { 0x0001 }
  187.  
  188. sub ReadLine {'Term::ReadLine::Stub'}
  189. sub readline {
  190.   my $self = shift;
  191.   my ($in,$out,$str) = @$self;
  192.   my $prompt = shift;
  193.   print $out $rl_term_set[0], $prompt, $rl_term_set[1], $rl_term_set[2]; 
  194.   $self->register_Tk 
  195.      if not $Term::ReadLine::registered and $Term::ReadLine::toloop
  196.     and defined &Tk::DoOneEvent;
  197.   #$str = scalar <$in>;
  198.   $str = $self->get_line;
  199.   $str =~ s/^\s*\Q$prompt\E// if ($^O eq 'MacOS');
  200.   utf8::upgrade($str)
  201.       if (${^UNICODE} & PERL_UNICODE_STDIN || defined ${^ENCODING}) &&
  202.          utf8::valid($str);
  203.   print $out $rl_term_set[3]; 
  204.   # bug in 5.000: chomping empty string creats length -1:
  205.   chomp $str if defined $str;
  206.   $str;
  207. }
  208. sub addhistory {}
  209.  
  210. sub findConsole {
  211.     my $console;
  212.  
  213.     if ($^O eq 'MacOS') {
  214.         $console = "Dev:Console";
  215.     } elsif (-e "/dev/tty") {
  216.     $console = "/dev/tty";
  217.     } elsif (-e "con" or $^O eq 'MSWin32') {
  218.     $console = "con";
  219.     } else {
  220.     $console = "sys\$command";
  221.     }
  222.  
  223.     if (($^O eq 'amigaos') || ($^O eq 'beos') || ($^O eq 'epoc')) {
  224.     $console = undef;
  225.     }
  226.     elsif ($^O eq 'os2') {
  227.       if ($DB::emacs) {
  228.     $console = undef;
  229.       } else {
  230.     $console = "/dev/con";
  231.       }
  232.     }
  233.  
  234.     my $consoleOUT = $console;
  235.     $console = "&STDIN" unless defined $console;
  236.     if (!defined $consoleOUT) {
  237.       $consoleOUT = defined fileno(STDERR) ? "&STDERR" : "&STDOUT";
  238.     }
  239.     ($console,$consoleOUT);
  240. }
  241.  
  242. sub new {
  243.   die "method new called with wrong number of arguments" 
  244.     unless @_==2 or @_==4;
  245.   #local (*FIN, *FOUT);
  246.   my ($FIN, $FOUT, $ret);
  247.   if (@_==2) {
  248.     my($console, $consoleOUT) = $_[0]->findConsole;
  249.  
  250.     open(FIN, "<$console"); 
  251.     open(FOUT,">$consoleOUT");
  252.     #OUT->autoflush(1);        # Conflicts with debugger?
  253.     my $sel = select(FOUT);
  254.     $| = 1;                # for DB::OUT
  255.     select($sel);
  256.     $ret = bless [\*FIN, \*FOUT];
  257.   } else {            # Filehandles supplied
  258.     $FIN = $_[2]; $FOUT = $_[3];
  259.     #OUT->autoflush(1);        # Conflicts with debugger?
  260.     my $sel = select($FOUT);
  261.     $| = 1;                # for DB::OUT
  262.     select($sel);
  263.     $ret = bless [$FIN, $FOUT];
  264.   }
  265.   if ($ret->Features->{ornaments} 
  266.       and not ($ENV{PERL_RL} and $ENV{PERL_RL} =~ /\bo\w*=0/)) {
  267.     local $Term::ReadLine::termcap_nowarn = 1;
  268.     $ret->ornaments(1);
  269.   }
  270.   return $ret;
  271. }
  272.  
  273. sub newTTY {
  274.   my ($self, $in, $out) = @_;
  275.   $self->[0] = $in;
  276.   $self->[1] = $out;
  277.   my $sel = select($out);
  278.   $| = 1;                # for DB::OUT
  279.   select($sel);
  280. }
  281.  
  282. sub IN { shift->[0] }
  283. sub OUT { shift->[1] }
  284. sub MinLine { undef }
  285. sub Attribs { {} }
  286.  
  287. my %features = (tkRunning => 1, ornaments => 1, 'newTTY' => 1);
  288. sub Features { \%features }
  289.  
  290. package Term::ReadLine;        # So late to allow the above code be defined?
  291.  
  292. our $VERSION = '1.02';
  293.  
  294. my ($which) = exists $ENV{PERL_RL} ? split /\s+/, $ENV{PERL_RL} : undef;
  295. if ($which) {
  296.   if ($which =~ /\bgnu\b/i){
  297.     eval "use Term::ReadLine::Gnu;";
  298.   } elsif ($which =~ /\bperl\b/i) {
  299.     eval "use Term::ReadLine::Perl;";
  300.   } else {
  301.     eval "use Term::ReadLine::$which;";
  302.   }
  303. } elsif (defined $which and $which ne '') {    # Defined but false
  304.   # Do nothing fancy
  305. } else {
  306.   eval "use Term::ReadLine::Gnu; 1" or eval "use Term::ReadLine::Perl; 1";
  307. }
  308.  
  309. #require FileHandle;
  310.  
  311. # To make possible switch off RL in debugger: (Not needed, work done
  312. # in debugger).
  313. our @ISA;
  314. if (defined &Term::ReadLine::Gnu::readline) {
  315.   @ISA = qw(Term::ReadLine::Gnu Term::ReadLine::Stub);
  316. } elsif (defined &Term::ReadLine::Perl::readline) {
  317.   @ISA = qw(Term::ReadLine::Perl Term::ReadLine::Stub);
  318. } elsif (defined $which && defined &{"Term::ReadLine::$which\::readline"}) {
  319.   @ISA = "Term::ReadLine::$which";
  320. } else {
  321.   @ISA = qw(Term::ReadLine::Stub);
  322. }
  323.  
  324. package Term::ReadLine::TermCap;
  325.  
  326. # Prompt-start, prompt-end, command-line-start, command-line-end
  327. #     -- zero-width beautifies to emit around prompt and the command line.
  328. our @rl_term_set = ("","","","");
  329. # string encoded:
  330. our $rl_term_set = ',,,';
  331.  
  332. our $terminal;
  333. sub LoadTermCap {
  334.   return if defined $terminal;
  335.   
  336.   require Term::Cap;
  337.   $terminal = Tgetent Term::Cap ({OSPEED => 9600}); # Avoid warning.
  338. }
  339.  
  340. sub ornaments {
  341.   shift;
  342.   return $rl_term_set unless @_;
  343.   $rl_term_set = shift;
  344.   $rl_term_set ||= ',,,';
  345.   $rl_term_set = 'us,ue,md,me' if $rl_term_set eq '1';
  346.   my @ts = split /,/, $rl_term_set, 4;
  347.   eval { LoadTermCap };
  348.   unless (defined $terminal) {
  349.     warn("Cannot find termcap: $@\n") unless $Term::ReadLine::termcap_nowarn;
  350.     $rl_term_set = ',,,';
  351.     return;
  352.   }
  353.   @rl_term_set = map {$_ ? $terminal->Tputs($_,1) || '' : ''} @ts;
  354.   return $rl_term_set;
  355. }
  356.  
  357.  
  358. package Term::ReadLine::Tk;
  359.  
  360. our($count_handle, $count_DoOne, $count_loop);
  361. $count_handle = $count_DoOne = $count_loop = 0;
  362.  
  363. our($giveup);
  364. sub handle {$giveup = 1; $count_handle++}
  365.  
  366. sub Tk_loop {
  367.   # Tk->tkwait('variable',\$giveup);    # needs Widget
  368.   $count_DoOne++, Tk::DoOneEvent(0) until $giveup;
  369.   $count_loop++;
  370.   $giveup = 0;
  371. }
  372.  
  373. sub register_Tk {
  374.   my $self = shift;
  375.   $Term::ReadLine::registered++ 
  376.     or Tk->fileevent($self->IN,'readable',\&handle);
  377. }
  378.  
  379. sub tkRunning {
  380.   $Term::ReadLine::toloop = $_[1] if @_ > 1;
  381.   $Term::ReadLine::toloop;
  382. }
  383.  
  384. sub get_c {
  385.   my $self = shift;
  386.   $self->Tk_loop if $Term::ReadLine::toloop && defined &Tk::DoOneEvent;
  387.   return getc $self->IN;
  388. }
  389.  
  390. sub get_line {
  391.   my $self = shift;
  392.   $self->Tk_loop if $Term::ReadLine::toloop && defined &Tk::DoOneEvent;
  393.   my $in = $self->IN;
  394.   local ($/) = "\n";
  395.   return scalar <$in>;
  396. }
  397.  
  398. 1;
  399.  
  400.