home *** CD-ROM | disk | FTP | other *** search
/ PC World 2005 June / PCWorld_2005-06_cd.bin / software / vyzkuste / firewally / firewally.exe / framework-2.3.exe / Gnu.pm < prev    next >
Text File  |  2003-03-16  |  47KB  |  1,859 lines
  1. #
  2. #    Gnu.pm --- The GNU Readline/History Library wrapper module
  3. #
  4. #    $Id: Gnu.pm,v 1.92 2003-03-16 20:29:39-05 hiroo Exp $
  5. #
  6. #    Copyright (c) 2001 Hiroo Hayashi.  All rights reserved.
  7. #
  8. #    This program is free software; you can redistribute it and/or
  9. #    modify it under the same terms as Perl itself.
  10. #
  11. #    Some of documentation strings in this file are cited from the
  12. #    GNU Readline/History Library Manual.
  13.  
  14. package Term::ReadLine::Gnu;
  15.  
  16. =head1 NAME
  17.  
  18. Term::ReadLine::Gnu - Perl extension for the GNU Readline/History Library
  19.  
  20. =head1 SYNOPSIS
  21.  
  22.   use Term::ReadLine;
  23.   $term = new Term::ReadLine 'ProgramName';
  24.   while ( defined ($_ = $term->readline('prompt>')) ) {
  25.     ...
  26.   }
  27.  
  28. =head1 DESCRIPTION
  29.  
  30. =head2 Overview
  31.  
  32. This is an implementation of Term::ReadLine using the GNU
  33. Readline/History Library.
  34.  
  35. For basic functions object oriented interface is provided. These are
  36. described in the section L<"Standard Methods"|"Standard Methods"> and
  37. L<"C<Term::ReadLine::Gnu> Functions"|"C<Term::ReadLine::Gnu> Functions">.
  38.  
  39. This package also has the interface with the almost all functions and
  40. variables which are documented in the GNU Readline/History Library
  41. Manual.  They are documented in the section
  42. L<"C<Term::ReadLine::Gnu> Functions"|"C<Term::ReadLine::Gnu> Functions">
  43. and
  44. L<"C<Term::ReadLine::Gnu> Variables"|"C<Term::ReadLine::Gnu> Variables">
  45. briefly.  For more detail of the GNU Readline/History Library, see
  46. 'GNU Readline Library Manual' and 'GNU History Library Manual'.
  47.  
  48. The sample programs under C<eg/> directory and test programs under
  49. C<t/> directory in the C<Term::ReadLine::Gnu> distribution include
  50. many example of this module.
  51.  
  52. =head2 Standard Methods
  53.  
  54. These methods are standard methods defined by B<Term::ReadLine>.
  55.  
  56. =cut
  57.  
  58. use strict;
  59. use Carp;
  60.  
  61. {
  62.     use Exporter ();
  63.     use DynaLoader;
  64.     use vars qw($VERSION @ISA @EXPORT_OK);
  65.  
  66.     $VERSION = '1.14';
  67.  
  68.     # Term::ReadLine::Gnu::AU makes a function in
  69.     # `Term::ReadLine::Gnu::XS' as a method.
  70.     # The namespace of Term::ReadLine::Gnu::AU is searched before ones
  71.     # of other classes
  72.     @ISA = qw(Term::ReadLine::Gnu::AU Term::ReadLine::Stub
  73.           Exporter DynaLoader);
  74.  
  75.     @EXPORT_OK = qw(RL_PROMPT_START_IGNORE RL_PROMPT_END_IGNORE
  76.             NO_MATCH SINGLE_MATCH MULT_MATCH
  77.             ISFUNC ISKMAP ISMACR
  78.             UNDO_DELETE UNDO_INSERT UNDO_BEGIN UNDO_END
  79.             RL_STATE_NONE RL_STATE_INITIALIZING
  80.             RL_STATE_INITIALIZED RL_STATE_TERMPREPPED
  81.             RL_STATE_READCMD RL_STATE_METANEXT
  82.             RL_STATE_DISPATCHING RL_STATE_MOREINPUT
  83.             RL_STATE_ISEARCH RL_STATE_NSEARCH
  84.             RL_STATE_SEARCH RL_STATE_NUMERICARG
  85.             RL_STATE_MACROINPUT RL_STATE_MACRODEF
  86.             RL_STATE_OVERWRITE RL_STATE_COMPLETING
  87.             RL_STATE_SIGHANDLER RL_STATE_UNDOING
  88.             RL_STATE_DONE);
  89.  
  90.     bootstrap Term::ReadLine::Gnu $VERSION; # DynaLoader
  91. }
  92. require Term::ReadLine::Gnu::XS;
  93.  
  94. #    Global Variables
  95.  
  96. use vars qw(%Attribs %Features);
  97.  
  98. # Each variable in the GNU Readline Library is tied to an entry of
  99. # this hash (%Attribs).  By accessing the hash entry, you can read
  100. # and/or write the variable in the GNU Readline Library.  See the
  101. # package definition of Term::ReadLine::Gnu::Var and following code
  102. # for more details.
  103.  
  104. # Normal (non-tied) entries
  105. %Attribs  = (
  106.          MinLength => 1,
  107.          do_expand => 0,
  108.          completion_word => [],
  109.          term_set => ['', '', '', ''],
  110.         );
  111. %Features = (
  112.          appname => 1, minline => 1, autohistory => 1,
  113.          getHistory => 1, setHistory => 1, addHistory => 1,
  114.          readHistory => 1, writeHistory => 1,
  115.          preput => 1, attribs => 1, newTTY => 1,
  116.          tkRunning => Term::ReadLine::Stub->Features->{'tkRunning'},
  117.          ornaments => Term::ReadLine::Stub->Features->{'ornaments'},
  118.          stiflehistory => 1,
  119.         );
  120.  
  121. sub Attribs { \%Attribs; }
  122. sub Features { \%Features; }
  123.  
  124. #
  125. #    GNU Readline/History Library constant definition
  126. #    These are included in @EXPORT_OK.
  127.  
  128. # I can define these variables in XS code to use the value defined in
  129. # readline.h, etc.  But it needs some calling convention change and
  130. # will cause compatiblity problem. I hope the definition of these
  131. # constant value will not be changed.
  132.  
  133. # for non-printing characters in prompt string
  134. sub RL_PROMPT_START_IGNORE    { "\001"; }
  135. sub RL_PROMPT_END_IGNORE    { "\002"; }
  136.  
  137. # for rl_filename_quoting_function
  138. sub NO_MATCH     { 0; }
  139. sub SINGLE_MATCH { 1; }
  140. sub MULT_MATCH   { 2; }
  141.  
  142. # for rl_generic_bind, rl_function_of_keyseq
  143. sub ISFUNC    { 0; }
  144. sub ISKMAP    { 1; }
  145. sub ISMACR    { 2; }
  146.  
  147. # for rl_add_undo
  148. sub UNDO_DELETE    { 0; }
  149. sub UNDO_INSERT    { 1; }
  150. sub UNDO_BEGIN    { 2; }
  151. sub UNDO_END    { 3; }
  152.  
  153. # for rl_readline_state
  154. sub RL_STATE_NONE        { 0x00000; } # no state; before first call
  155. sub RL_STATE_INITIALIZING    { 0x00001; } # initializing
  156. sub RL_STATE_INITIALIZED    { 0x00002; } # initialization done
  157. sub RL_STATE_TERMPREPPED    { 0x00004; } # terminal is prepped
  158. sub RL_STATE_READCMD        { 0x00008; } # reading a command key
  159. sub RL_STATE_METANEXT        { 0x00010; } # reading input after ESC
  160. sub RL_STATE_DISPATCHING    { 0x00020; } # dispatching to a command
  161. sub RL_STATE_MOREINPUT        { 0x00040; } # reading more input in a command function
  162. sub RL_STATE_ISEARCH        { 0x00080; } # doing incremental search
  163. sub RL_STATE_NSEARCH        { 0x00100; } # doing non-inc search
  164. sub RL_STATE_SEARCH        { 0x00200; } # doing a history search
  165. sub RL_STATE_NUMERICARG        { 0x00400; } # reading numeric argument
  166. sub RL_STATE_MACROINPUT        { 0x00800; } # getting input from a macro
  167. sub RL_STATE_MACRODEF        { 0x01000; } # defining keyboard macro
  168. sub RL_STATE_OVERWRITE        { 0x02000; } # overwrite mode
  169. sub RL_STATE_COMPLETING        { 0x04000; } # doing completion
  170. sub RL_STATE_SIGHANDLER        { 0x08000; } # in readline sighandler
  171. sub RL_STATE_UNDOING        { 0x10000; } # doing an undo
  172. sub RL_STATE_DONE        { 0x80000; } # done; accepted line
  173.  
  174. #
  175. #    Methods Definition
  176. #
  177.  
  178. =over 4
  179.  
  180. =item C<ReadLine>
  181.  
  182. returns the actual package that executes the commands. If you have
  183. installed this package,  possible value is C<Term::ReadLine::Gnu>.
  184.  
  185. =cut
  186.  
  187. sub ReadLine { 'Term::ReadLine::Gnu'; }
  188.  
  189. =item C<new(NAME,[IN[,OUT]])>
  190.  
  191. returns the handle for subsequent calls to following functions.
  192. Argument is the name of the application.  Optionally can be followed
  193. by two arguments for C<IN> and C<OUT> file handles. These arguments
  194. should be globs.
  195.  
  196. =cut
  197.  
  198. # The origin of this function is Term::ReadLine::Perl.pm by Ilya Zakharevich.
  199. sub new {
  200.     my $this = shift;        # Package
  201.     my $class = ref($this) || $this;
  202.  
  203.     my $name = shift;
  204.  
  205.     my $self = \%Attribs;
  206.     bless $self, $class;
  207.  
  208.     # set rl_readline_name before .inputrc is read in rl_initialize()
  209.     $Attribs{readline_name} = $name;
  210.  
  211.     # some version of Perl cause segmentation fault, if XS module
  212.     # calls setenv() before the 1st assignment to $ENV{}.
  213.     $ENV{_TRL_DUMMY} = '';
  214.  
  215.     # initialize the GNU Readline Library and termcap library
  216.     $self->initialize();
  217.  
  218.     # enable ornaments to be compatible with perl5.004_05(?)
  219.     unless ($ENV{PERL_RL} and $ENV{PERL_RL} =~ /\bo\w*=0/) {
  220.     local $^W = 0;        # Term::ReadLine is not warning flag free
  221.     # Without the next line Term::ReadLine::Stub::ornaments is used.
  222.     # Why does Term::ReadLine::Gnu::AU selects it at first?!!!
  223.     # If you know why this happens, please let me know.  Thanks.
  224.     undef &Term::ReadLine::Gnu::ornaments;
  225.     $self->ornaments(1);
  226.     }
  227.  
  228.     if (!@_) {
  229.     my ($IN,$OUT) = $self->findConsole();
  230.     open(IN,"<$IN")   || croak "Cannot open $IN for read";
  231.     open(OUT,">$OUT") || croak "Cannot open $OUT for write";
  232.     # borrowed from Term/ReadLine.pm
  233.     my $sel = select(OUT);
  234.     $| = 1;                # for DB::OUT
  235.     select($sel);
  236.     $Attribs{instream} = \*IN;
  237.     $Attribs{outstream} = \*OUT;
  238.     } else {
  239.     $Attribs{instream} = shift;
  240.     $Attribs{outstream} = shift;
  241.     }
  242.  
  243.     $self;
  244. }
  245.  
  246. sub DESTROY {}
  247.  
  248. =item C<readline(PROMPT[,PREPUT])>
  249.  
  250. gets an input line, with actual C<GNU Readline> support.  Trailing
  251. newline is removed.  Returns C<undef> on C<EOF>.  C<PREPUT> is an
  252. optional argument meaning the initial value of input.
  253.  
  254. The optional argument C<PREPUT> is granted only if the value C<preput>
  255. is in C<Features>.
  256.  
  257. C<PROMPT> may include some escape sequences.  Use
  258. C<RL_PROMPT_START_IGNORE> to begin a sequence of non-printing
  259. characters, and C<RL_PROMPT_END_IGNORE> to end of such a sequence.
  260.  
  261. =cut
  262.  
  263. # to peacify -w
  264. $Term::ReadLine::registered = $Term::ReadLine::registered;
  265.  
  266. sub readline {            # should be ReadLine
  267.     my $self = shift;
  268.     my ($prompt, $preput) = @_;
  269.  
  270.     # ornament support (now prompt only)
  271.     $prompt = ${$Attribs{term_set}}[0] . $prompt . ${$Attribs{term_set}}[1];
  272.  
  273.     # `completion_function' support for compatibility with
  274.     # Term:ReadLine::Perl.  Prefer $completion_entry_function, since a
  275.     # program which uses $completion_entry_function should know
  276.     # Term::ReadLine::Gnu and have better completion function using
  277.     # the variable.
  278.     $Attribs{completion_entry_function} = $Attribs{_trp_completion_function}
  279.     if (!defined $Attribs{completion_entry_function}
  280.         && defined $Attribs{completion_function});
  281.  
  282.     # TkRunning support
  283.     if (not $Term::ReadLine::registered and $Term::ReadLine::toloop
  284.     and defined &Tk::DoOneEvent) {
  285.     $self->register_Tk;
  286.     $Attribs{getc_function} = $Attribs{Tk_getc};
  287.     }
  288.  
  289.     # call readline()
  290.     my $line;
  291.     if (defined $preput) {
  292.     my $saved_startup_hook = $Attribs{startup_hook};
  293.     $Attribs{startup_hook} = sub {
  294.         $self->rl_insert_text($preput);
  295.         &$saved_startup_hook
  296.         if defined $saved_startup_hook;
  297.     };
  298.     $line = $self->rl_readline($prompt);
  299.     $Attribs{startup_hook} = $saved_startup_hook;
  300.     } else {
  301.     $line = $self->rl_readline($prompt);
  302.     }
  303.     return undef unless defined $line;
  304.  
  305.     # history expansion
  306.     if ($Attribs{do_expand}) {
  307.     my $result;
  308.     ($result, $line) = $self->history_expand($line);
  309.     my $outstream = $Attribs{outstream};
  310.     print $outstream "$line\n" if ($result);
  311.  
  312.     # return without adding line into history
  313.     if ($result < 0 || $result == 2) {
  314.         return '';        # don't return `undef' which means EOF.
  315.     }
  316.     }
  317.  
  318.     # add to history buffer
  319.     $self->add_history($line) 
  320.     if (defined $self->{MinLength} && $self->{MinLength} > 0
  321.         && length($line) >= $self->{MinLength});
  322.  
  323.     return $line;
  324. }
  325.  
  326. =item C<AddHistory(LINE1, LINE2, ...)>
  327.  
  328. adds the lines to the history of input, from where it can be used if
  329. the actual C<readline> is present.
  330.  
  331. =cut
  332.  
  333. use vars '*addhistory';
  334. *addhistory = \&AddHistory;    # for backward compatibility
  335.  
  336. sub AddHistory {
  337.     my $self = shift;
  338.     foreach (@_) {
  339.     $self->add_history($_);
  340.     }
  341. }
  342.  
  343. =item C<IN>, C<OUT>
  344.  
  345. return the file handles for input and output or C<undef> if
  346. C<readline> input and output cannot be used for Perl.
  347.  
  348. =cut
  349.  
  350. sub IN  { $Attribs{instream}; }
  351. sub OUT { $Attribs{outstream}; }
  352.  
  353. =item C<MinLine([MAX])>
  354.  
  355. If argument C<MAX> is specified, it is an advice on minimal size of
  356. line to be included into history.  C<undef> means do not include
  357. anything into history.  Returns the old value.
  358.  
  359. =cut
  360.  
  361. sub MinLine {
  362.     my $self = shift;
  363.     my $old_minlength = $self->{MinLength};
  364.     $self->{MinLength} = shift;
  365.     $old_minlength;
  366. }
  367.  
  368. # findConsole is defined in ReadLine.pm.
  369.  
  370. =item C<findConsole>
  371.  
  372. returns an array with two strings that give most appropriate names for
  373. files for input and output using conventions C<"E<lt>$in">, C<"E<gt>$out">.
  374.  
  375. =item C<Attribs>
  376.  
  377. returns a reference to a hash which describes internal configuration
  378. (variables) of the package.  Names of keys in this hash conform to
  379. standard conventions with the leading C<rl_> stripped.
  380.  
  381. See section "Variables" for supported variables.
  382.  
  383. =item C<Features>
  384.  
  385. Returns a reference to a hash with keys being features present in
  386. current implementation. Several optional features are used in the
  387. minimal interface: C<appname> should be present if the first argument
  388. to C<new> is recognized, and C<minline> should be present if
  389. C<MinLine> method is not dummy.  C<autohistory> should be present if
  390. lines are put into history automatically (maybe subject to
  391. C<MinLine>), and C<addHistory> if C<AddHistory> method is not dummy. 
  392. C<preput> means the second argument to C<readline> method is processed.
  393. C<getHistory> and C<setHistory> denote that the corresponding methods are 
  394. present. C<tkRunning> denotes that a Tk application may run while ReadLine
  395. is getting input.
  396.  
  397. =cut
  398.  
  399. # Not tested yet.  How do I use this?
  400. sub newTTY {
  401.     my ($self, $in, $out) = @_;
  402.     $Attribs{instream}  = $in;
  403.     $Attribs{outstream} = $out;
  404.     my $sel = select($out);
  405.     $| = 1;            # for DB::OUT
  406.     select($sel);
  407. }
  408.  
  409. =back
  410.  
  411. =cut
  412.  
  413. # documented later
  414. sub CallbackHandlerInstall {
  415.     my $self = shift;
  416.     my ($prompt, $lhandler) = @_;
  417.  
  418.     $Attribs{_callback_handler} = $lhandler;
  419.  
  420.     # ornament support (now prompt only)
  421.     $prompt = ${$Attribs{term_set}}[0] . $prompt . ${$Attribs{term_set}}[1];
  422.  
  423.     $Attribs{completion_entry_function} = $Attribs{_trp_completion_function}
  424.     if (!defined $Attribs{completion_entry_function}
  425.         && defined $Attribs{completion_function});
  426.  
  427.     $self->rl_callback_handler_install($prompt,
  428.                        \&Term::ReadLine::Gnu::XS::_ch_wrapper);
  429. }
  430.  
  431.  
  432. #
  433. #    Additional Supported Methods
  434. #
  435.  
  436. # Documentation is after '__END__' for efficiency.
  437.  
  438. # for backward compatibility
  439. use vars qw(*AddDefun *BindKey *UnbindKey *ParseAndBind *StifleHistory);
  440. *AddDefun = \&add_defun;
  441. *BindKey = \&bind_key;
  442. *UnbindKey = \&unbind_key;
  443. *ParseAndBind = \&parse_and_bind;
  444. *StifleHistory = \&stifle_history;
  445.  
  446. sub SetHistory {
  447.     my $self = shift;
  448.     $self->clear_history();
  449.     $self->AddHistory(@_);
  450. }
  451.  
  452. sub GetHistory {
  453.     my $self = shift;
  454.     $self->history_list();
  455. }
  456.  
  457. sub ReadHistory {
  458.     my $self = shift;
  459.     ! $self->read_history_range(@_);
  460. }
  461.  
  462. sub WriteHistory {
  463.     my $self = shift;
  464.     ! $self->write_history(@_);
  465. }
  466.  
  467. #
  468. #    Access Routines for GNU Readline/History Library Variables
  469. #
  470. package Term::ReadLine::Gnu::Var;
  471. use Carp;
  472. use strict;
  473. use vars qw(%_rl_vars);
  474.  
  475. %_rl_vars
  476.     = (
  477.        rl_line_buffer                => ['S', 0],
  478.        rl_prompt                => ['S', 1],
  479.        rl_library_version            => ['S', 2],
  480.        rl_terminal_name                => ['S', 3],
  481.        rl_readline_name                => ['S', 4],
  482.        rl_basic_word_break_characters        => ['S', 5],
  483.        rl_basic_quote_characters        => ['S', 6],
  484.        rl_completer_word_break_characters    => ['S', 7],
  485.        rl_completer_quote_characters        => ['S', 8],
  486.        rl_filename_quote_characters        => ['S', 9],
  487.        rl_special_prefixes            => ['S', 10],
  488.        history_no_expand_chars            => ['S', 11],
  489.        history_search_delimiter_chars        => ['S', 12],
  490.        rl_executing_macro            => ['S', 13], # GRL4.2
  491.        history_word_delimiters            => ['S', 14], # GRL4.2
  492.  
  493.        rl_point                    => ['I', 0],
  494.        rl_end                    => ['I', 1],
  495.        rl_mark                    => ['I', 2],
  496.        rl_done                    => ['I', 3],
  497.        rl_pending_input                => ['I', 4],
  498.        rl_completion_query_items        => ['I', 5],
  499.        rl_completion_append_character        => ['C', 6],
  500.        rl_ignore_completion_duplicates        => ['I', 7],
  501.        rl_filename_completion_desired        => ['I', 8],
  502.        rl_filename_quoting_desired        => ['I', 9],
  503.        rl_inhibit_completion            => ['I', 10],
  504.        history_base                => ['I', 11],
  505.        history_length                => ['I', 12],
  506.        history_max_entries            => ['I', 13],
  507.        max_input_history            => ['I', 13], # before GRL 4.2
  508.        history_expansion_char            => ['C', 14],
  509.        history_subst_char            => ['C', 15],
  510.        history_comment_char            => ['C', 16],
  511.        history_quotes_inhibit_expansion        => ['I', 17],
  512.        rl_erase_empty_line            => ['I', 18], # GRL 4.0
  513.        rl_catch_signals                => ['I', 19], # GRL 4.0
  514.        rl_catch_sigwinch            => ['I', 20], # GRL 4.0
  515.        rl_already_prompted            => ['I', 21], # GRL 4.1
  516.        rl_num_chars_to_read            => ['I', 22], # GRL 4.2
  517.        rl_dispatching                => ['I', 23], # GRL 4.2
  518.        rl_gnu_readline_p            => ['I', 24], # GRL 4.2
  519.        rl_readline_state            => ['I', 25], # GRL 4.2
  520.        rl_explicit_arg                => ['I', 26], # GRL 4.2
  521.        rl_numeric_arg                => ['I', 27], # GRL 4.2
  522.        rl_editing_mode                => ['I', 28], # GRL 4.2
  523.        rl_attempted_completion_over        => ['I', 29], # GRL 4.2
  524.        rl_completion_type            => ['I', 30], # GRL 4.2
  525.        rl_readline_version            => ['I', 31], # GRL 4.2a
  526.        rl_completion_suppress_append        => ['I', 32], # GRL 4.3
  527.        rl_completion_mark_symlink_dirs        => ['I', 33], # GRL 4.3
  528.  
  529.        rl_startup_hook                => ['F', 0],
  530.        rl_event_hook                => ['F', 1],
  531.        rl_getc_function                => ['F', 2],
  532.        rl_redisplay_function            => ['F', 3],
  533.        rl_completion_entry_function        => ['F', 4],
  534.        rl_attempted_completion_function        => ['F', 5],
  535.        rl_filename_quoting_function        => ['F', 6],
  536.        rl_filename_dequoting_function        => ['F', 7],
  537.        rl_char_is_quoted_p            => ['F', 8],
  538.        rl_ignore_some_completions_function    => ['F', 9],
  539.        rl_directory_completion_hook        => ['F', 10],
  540.        history_inhibit_expansion_function    => ['F', 11],
  541.        rl_pre_input_hook            => ['F', 12], # GRL 4.0
  542.        rl_completion_display_matches_hook    => ['F', 13], # GRL 4.0
  543.        rl_prep_term_function            => ['F', 14], # GRL 4.2
  544.        rl_deprep_term_function            => ['F', 15], # GRL 4.2
  545.  
  546.        rl_instream                => ['IO', 0],
  547.        rl_outstream                => ['IO', 1],
  548.  
  549.        rl_executing_keymap            => ['K', 0],
  550.        rl_binding_keymap            => ['K', 1],
  551.  
  552.        rl_last_func                             => ['LF', 0],
  553.       );
  554.  
  555. sub TIESCALAR {
  556.     my $class = shift;
  557.     my $name = shift;
  558.     return bless \$name, $class;
  559. }
  560.  
  561. sub FETCH {
  562.     my $self = shift;
  563.     confess "wrong type" unless ref $self;
  564.  
  565.     my $name = $$self;
  566.     if (! defined $_rl_vars{$name}) {
  567.     confess "Term::ReadLine::Gnu::Var::FETCH: Unknown variable name `$name'\n";
  568.     return undef ;
  569.     }
  570.  
  571.     my ($type, $id) = @{$_rl_vars{$name}};
  572.     if ($type eq 'S') {
  573.     return _rl_fetch_str($id);
  574.     } elsif ($type eq 'I') {
  575.     return _rl_fetch_int($id);
  576.     } elsif ($type eq 'C') {
  577.     return chr(_rl_fetch_int($id));
  578.     } elsif ($type eq 'F') {
  579.     return _rl_fetch_function($id);
  580.     } elsif ($type eq 'IO') {
  581.     return _rl_fetch_iostream($id);
  582.     } elsif ($type eq 'K') {
  583.     return _rl_fetch_keymap($id);
  584.     } elsif ($type eq 'LF') {
  585.         return _rl_fetch_last_func();
  586.     } else {
  587.     carp "Term::ReadLine::Gnu::Var::FETCH: Illegal type `$type'\n";
  588.     return undef;
  589.     }
  590. }
  591.  
  592. sub STORE {
  593.     my $self = shift;
  594.     confess "wrong type" unless ref $self;
  595.  
  596.     my $name = $$self;
  597.     if (! defined $_rl_vars{$name}) {
  598.     confess "Term::ReadLine::Gnu::Var::STORE: Unknown variable name `$name'\n";
  599.     return undef ;
  600.     }
  601.  
  602.     my $value = shift;
  603.     my ($type, $id) = @{$_rl_vars{$name}};
  604.     if ($type eq 'S') {
  605.     if ($name eq 'rl_line_buffer') {
  606.         return _rl_store_rl_line_buffer($value);
  607.     } else {
  608.         return _rl_store_str($value, $id);
  609.     }
  610.     } elsif ($type eq 'I') {
  611.     return _rl_store_int($value, $id);
  612.     } elsif ($type eq 'C') {
  613.     return chr(_rl_store_int(ord($value), $id));
  614.     } elsif ($type eq 'F') {
  615.     return _rl_store_function($value, $id);
  616.     } elsif ($type eq 'IO') {
  617.     return _rl_store_iostream($value, $id);
  618.     } elsif ($type eq 'K' || $type eq 'LF') {
  619.     carp "Term::ReadLine::Gnu::Var::STORE: read only variable `$name'\n";
  620.     return undef;
  621.     } else {
  622.     carp "Term::ReadLine::Gnu::Var::STORE: Illegal type `$type'\n";
  623.     return undef;
  624.     }
  625. }
  626.  
  627. package Term::ReadLine::Gnu;
  628. use Carp;
  629. use strict;
  630.  
  631. #
  632. #    set value of %Attribs
  633. #
  634.  
  635. #    Tie all Readline/History variables
  636. foreach (keys %Term::ReadLine::Gnu::Var::_rl_vars) {
  637.     my $name;
  638.     ($name = $_) =~ s/^rl_//;    # strip leading `rl_'
  639.     tie $Attribs{$name},  'Term::ReadLine::Gnu::Var', $_;
  640. }
  641.  
  642. #    add reference to some functions
  643. {
  644.     my ($name, $fname);
  645.     no strict 'refs';        # allow symbolic reference
  646.     map {
  647.     ($name = $_) =~ s/^rl_//; # strip leading `rl_'
  648.     $fname = 'Term::ReadLine::Gnu::XS::' . $_;
  649.     $Attribs{$name} = \&$fname; # symbolic reference
  650.     } qw(rl_getc
  651.      rl_redisplay
  652.      rl_callback_read_char
  653.      rl_display_match_list
  654.      rl_filename_completion_function
  655.      rl_username_completion_function
  656.      list_completion_function
  657.          _trp_completion_function);
  658.     # auto-split subroutine cannot be processed in the map loop above
  659.     use strict 'refs';
  660.     $Attribs{shadow_redisplay} = \&Term::ReadLine::Gnu::XS::shadow_redisplay;
  661.     $Attribs{Tk_getc} = \&Term::ReadLine::Gnu::XS::Tk_getc;
  662.     $Attribs{list_completion_function} = \&Term::ReadLine::Gnu::XS::list_completion_function;
  663. }
  664.  
  665. package Term::ReadLine::Gnu::AU;
  666. use Carp;
  667. no strict qw(refs vars);
  668.  
  669. sub AUTOLOAD {
  670.     { $AUTOLOAD =~ s/.*:://; }    # preserve match data
  671.     my $name;
  672.     if (exists $Term::ReadLine::Gnu::XS::{"rl_$AUTOLOAD"}) {
  673.     $name = "Term::ReadLine::Gnu::XS::rl_$AUTOLOAD";
  674.     } elsif (exists $Term::ReadLine::Gnu::XS::{"$AUTOLOAD"}) {
  675.     $name = "Term::ReadLine::Gnu::XS::$AUTOLOAD";
  676.     } else {
  677.     croak "Cannot do `$AUTOLOAD' in Term::ReadLine::Gnu";
  678.     }
  679.     local $^W = 0;        # Why is this line necessary ?
  680.     *$AUTOLOAD = sub { shift; &$name(@_); };
  681.     goto &$AUTOLOAD;
  682. }
  683. 1;
  684. __END__
  685.  
  686.  
  687. =head2 C<Term::ReadLine::Gnu> Functions
  688.  
  689. All these GNU Readline/History Library functions are callable via
  690. method interface and have names which conform to standard conventions
  691. with the leading C<rl_> stripped.
  692.  
  693. Almost methods have lower level functions in
  694. C<Term::ReadLine::Gnu::XS> package.  To use them full qualified name
  695. is required.  Using method interface is preferred.
  696.  
  697. =over 4
  698.  
  699. =item Readline Convenience Functions
  700.  
  701. =over 4
  702.  
  703. =item Naming Function
  704.  
  705. =over 4
  706.  
  707. =item C<add_defun(NAME, FUNC [,KEY=-1])>
  708.  
  709. Add name to the Perl function C<FUNC>.  If optional argument C<KEY> is
  710. specified, bind it to the C<FUNC>.  Returns reference to
  711. C<FunctionPtr>.
  712.  
  713.   Example:
  714.     # name name `reverse-line' to a function reverse_line(),
  715.     # and bind it to "\C-t"
  716.     $term->add_defun('reverse-line', \&reverse_line, ord "\ct");
  717.  
  718. =back
  719.  
  720. =item Selecting a Keymap
  721.  
  722. =over 4
  723.  
  724. =item C<make_bare_keymap>
  725.  
  726.     Keymap    rl_make_bare_keymap()
  727.  
  728. =item C<copy_keymap(MAP)>
  729.  
  730.     Keymap    rl_copy_keymap(Keymap|str map)
  731.  
  732. =item C<make_keymap>
  733.  
  734.     Keymap    rl_make_keymap()
  735.  
  736. =item C<discard_keymap(MAP)>
  737.  
  738.     Keymap    rl_discard_keymap(Keymap|str map)
  739.  
  740. =item C<get_keymap>
  741.  
  742.     Keymap    rl_get_keymap()
  743.  
  744. =item C<set_keymap(MAP)>
  745.  
  746.     Keymap    rl_set_keymap(Keymap|str map)
  747.  
  748. =item C<get_keymap_by_name(NAME)>
  749.  
  750.     Keymap    rl_get_keymap_by_name(str name)
  751.  
  752. =item C<get_keymap_name(MAP)>
  753.  
  754.     str    rl_get_keymap_name(Keymap map)
  755.  
  756. =back
  757.  
  758. =item Binding Keys
  759.  
  760. =over 4
  761.  
  762. =item C<bind_key(KEY, FUNCTION [,MAP])>
  763.  
  764.     int    rl_bind_key(int key, FunctionPtr|str function,
  765.                 Keymap|str map = rl_get_keymap())
  766.  
  767. Bind C<KEY> to the C<FUNCTION>.  C<FUNCTION> is the name added by the
  768. C<add_defun> method.  If optional argument C<MAP> is specified, binds
  769. in C<MAP>.  Returns non-zero in case of error.
  770.  
  771. =item C<unbind_key(KEY [,MAP])>
  772.  
  773.     int    rl_unbind_key(int key, Keymap|str map = rl_get_keymap())
  774.  
  775. Bind C<KEY> to the null function.  Returns non-zero in case of error.
  776.  
  777. =item C<unbind_function(FUNCTION [,MAP])>
  778.  
  779.     int    rl_unbind_function(FunctionPtr|str function,
  780.                    Keymap|str map = rl_get_keymap())
  781.  
  782. =item C<unbind_command(COMMAND [,MAP])>
  783.  
  784.     int    rl_unbind_command(str command,
  785.                   Keymap|str map = rl_get_keymap())
  786.  
  787. =item C<set_key(KEYSEQ, FUNCTION [,MAP])>
  788.  
  789.     int    rl_set_key(str keyseq, FunctionPtr|str function,
  790.                   Keymap|str map = rl_get_keymap())
  791.  
  792. =item C<generic_bind(TYPE, KEYSEQ, DATA, [,MAP])>
  793.  
  794.     int    rl_generic_bind(int type, str keyseq,
  795.                 FunctionPtr|Keymap|str data,
  796.                 Keymap|str map = rl_get_keymap())
  797.  
  798. =item C<parse_and_bind(LINE)>
  799.  
  800.     void    rl_parse_and_bind(str line)
  801.  
  802. Parse C<LINE> as if it had been read from the F<~/.inputrc> file and
  803. perform any key bindings and variable assignments found.  For more
  804. detail see 'GNU Readline Library Manual'.
  805.  
  806. =item C<read_init_file([FILENAME])>
  807.  
  808.     int    rl_read_init_file(str filename = '~/.inputrc')
  809.  
  810. =back
  811.  
  812. =item Associating Function Names and Bindings
  813.  
  814. =over 4
  815.  
  816. =item C<named_function(NAME)>
  817.  
  818.     FunctionPtr rl_named_function(str name)
  819.  
  820. =item C<get_function_name(FUNCTION)>
  821.  
  822.     str    rl_get_function_name(FunctionPtr function)
  823.  
  824. =item C<function_of_keyseq(KEYMAP [,MAP])>
  825.  
  826.     (FunctionPtr|Keymap|str data, int type)
  827.         rl_function_of_keyseq(str keyseq,
  828.                       Keymap|str map = rl_get_keymap())
  829.  
  830. =item C<invoking_keyseqs(FUNCTION [,MAP])>
  831.  
  832.     (@str)    rl_invoking_keyseqs(FunctionPtr|str function,
  833.                     Keymap|str map = rl_get_keymap())
  834.  
  835. =item C<function_dumper([READABLE])>
  836.  
  837.     void    rl_function_dumper(int readable = 0)
  838.  
  839. =item C<list_funmap_names>
  840.  
  841.     void    rl_list_funmap_names()
  842.  
  843. =item C<funmap_names>
  844.  
  845.     (@str)    rl_funmap_names()
  846.  
  847. =item C<add_funmap_entry(NAME, FUNCTION)>
  848.  
  849.     int    rl_add_funmap_entry(char *name, FunctionPtr|str function)
  850.  
  851. =back
  852.  
  853. =item Allowing Undoing
  854.  
  855. =over 4
  856.  
  857. =item C<begin_undo_group>
  858.  
  859.     int    rl_begin_undo_group()
  860.  
  861. =item C<end_undo_group>
  862.  
  863.     int    rl_end_undo_group()
  864.  
  865. =item C<add_undo(WHAT, START, END, TEXT)>
  866.  
  867.     int    rl_add_undo(int what, int start, int end, str text)
  868.  
  869. =item C<free_undo_list>
  870.  
  871.     void    rl_free_undo_list()
  872.  
  873. =item C<do_undo>
  874.  
  875.     int    rl_do_undo()
  876.  
  877. =item C<modifying([START [,END]])>
  878.  
  879.     int    rl_modifying(int start = 0, int end = rl_end)
  880.  
  881. =back
  882.  
  883. =item Redisplay
  884.  
  885. =over 4
  886.  
  887. =item C<redisplay>
  888.  
  889.     void    rl_redisplay()
  890.  
  891. =item C<forced_update_display>
  892.  
  893.     int    rl_forced_update_display()
  894.  
  895. =item C<on_new_line>
  896.  
  897.     int    rl_on_new_line()
  898.  
  899. =item C<on_new_line_with_prompt>
  900.  
  901.     int    rl_on_new_line_with_prompt()    # GRL 4.1
  902.  
  903. =item C<reset_line_state>
  904.  
  905.     int    rl_reset_line_state()
  906.  
  907. =item C<rl_show_char(C)>
  908.  
  909.     int    rl_show_char(int c)
  910.  
  911. =item C<message(FMT[, ...])>
  912.  
  913.     int    rl_message(str fmt, ...)
  914.  
  915. =item C<crlf>
  916.  
  917.     int    rl_crlf()            # GRL 4.2
  918.  
  919. =item C<clear_message>
  920.  
  921.     int    rl_clear_message()
  922.  
  923. =item C<save_prompt>
  924.  
  925.     void    rl_save_prompt()
  926.  
  927. =item C<restore_prompt>
  928.  
  929.     void    rl_restore_prompt()
  930.  
  931. =item C<expand_prompt(PROMPT)>
  932.  
  933.     int    rl_expand_prompt(str prompt)    # GRL 4.2
  934.  
  935. =item C<set_prompt(PROMPT)>
  936.  
  937.     int    rl_set_prompt(const str prompt)    # GRL 4.2
  938.  
  939. =back
  940.  
  941. =item Modifying Text
  942.  
  943. =over 4
  944.  
  945. =item C<insert_text(TEXT)>
  946.  
  947.     int    rl_insert_text(str text)
  948.  
  949. =item C<delete_text([START [,END]])>
  950.  
  951.     int    rl_delete_text(int start = 0, int end = rl_end)
  952.  
  953. =item C<copy_text([START [,END]])>
  954.  
  955.     str    rl_copy_text(int start = 0, int end = rl_end)
  956.  
  957. =item C<kill_text([START [,END]])>
  958.  
  959.     int    rl_kill_text(int start = 0, int end = rl_end)
  960.  
  961. =item C<push_macro_input(MACRO)>
  962.  
  963.     int    rl_push_macro_input(str macro)
  964.  
  965. =back
  966.  
  967. =item Character Input
  968.  
  969. =over 4
  970.  
  971. =item C<read_key>
  972.  
  973.     int    rl_read_key()
  974.  
  975. =item C<getc(STREAM)>
  976.  
  977.     int    rl_getc(FILE *STREAM)
  978.  
  979. =item C<stuff_char(C)>
  980.  
  981.     int    rl_stuff_char(int c)
  982.  
  983. =item C<execute_next(C)>
  984.  
  985.     int    rl_execute_next(int c)        # GRL 4.2
  986.  
  987. =item C<clear_pending_input()>
  988.  
  989.     int    rl_clear_pending_input()    # GRL 4.2
  990.  
  991. =item C<set_keyboard_input_timeout(uSEC)>
  992.  
  993.     int    rl_set_keyboard_input_timeout(int usec)    # GRL 4.2
  994.  
  995. =back
  996.  
  997. =item Terminal Management
  998.  
  999. =over 4
  1000.  
  1001. =item C<prep_terminal(META_FLAG)>
  1002.  
  1003.     void    rl_prep_terminal(int META_FLAG)    # GRL 4.2
  1004.  
  1005. =item C<deprep_terminal()>
  1006.  
  1007.     void    rl_deprep_terminal()        # GRL 4.2
  1008.  
  1009. =item C<tty_set_default_bindings(KMAP)>
  1010.  
  1011.     void    rl_tty_set_default_bindings([Keymap KMAP])    # GRL 4.2
  1012.  
  1013. =item C<reset_terminal([TERMINAL_NAME])>
  1014.  
  1015.     int    rl_reset_terminal(str terminal_name = getenv($TERM)) # GRL 4.2
  1016.  
  1017. =back
  1018.  
  1019. =item Utility Functions
  1020.  
  1021. =over 4
  1022.  
  1023. =item C<replace_line(TEXT [,CLEAR_UNDO]>
  1024.  
  1025.     int    rl_replace_line(str text, int clear_undo)    # GRL 4.3
  1026.  
  1027. =item C<initialize>
  1028.  
  1029.     int    rl_initialize()
  1030.  
  1031. =item C<ding>
  1032.  
  1033.     int    rl_ding()
  1034.  
  1035. =item C<alphabetic(C)>
  1036.  
  1037.     int    rl_alphabetic(int C)
  1038.  
  1039. =item C<display_match_list(MATCHES [,LEN [,MAX]])>
  1040.  
  1041.     void    rl_display_match_list(\@matches, len = $#maches, max) # GRL 4.0
  1042.  
  1043. Since the first element of an array @matches as treated as a possible
  1044. completion, it is not displayed.  See the descriptions of
  1045. C<completion_matches()>.
  1046.  
  1047. When C<MAX> is ommited, the max length of an item in @matches is used.
  1048.  
  1049. =back
  1050.  
  1051. =item Miscellaneous Functions
  1052.  
  1053. =over 4
  1054.  
  1055. =item C<macro_bind(KEYSEQ, MACRO [,MAP])>
  1056.  
  1057.     int    rl_macro_bind(const str keyseq, const str macro, Keymap map)
  1058.  
  1059. =item C<macro_dumper(READABLE)>
  1060.  
  1061.     int    rl_macro_dumper(int readline)
  1062.  
  1063. =item C<variable_bind(VARIABLE, VALUE)>
  1064.  
  1065.     int    rl_variable_bind(const str variable, const str value)
  1066.  
  1067. =item C<variable_dumper(READABLE)>
  1068.  
  1069.     int    rl_variable_dumper(int readline)
  1070.  
  1071. =item C<set_paren_blink_timeout(uSEC)>
  1072.  
  1073.     int    rl_set_paren_blink_timeout(usec)    # GRL 4.2
  1074.  
  1075. =item C<get_termcap(cap)>
  1076.  
  1077.     str    rl_get_termcap(cap)
  1078.  
  1079. =back
  1080.  
  1081. =item Alternate Interface
  1082.  
  1083. =over 4
  1084.  
  1085. =item C<callback_handler_install(PROMPT, LHANDLER)>
  1086.  
  1087.     void    rl_callback_handler_install(str prompt, pfunc lhandler)
  1088.  
  1089. =item C<callback_read_char>
  1090.  
  1091.     void    rl_callback_read_char()
  1092.  
  1093. =item C<callback_handler_remove>
  1094.  
  1095.     void    rl_callback_handler_remove()
  1096.  
  1097. =back
  1098.  
  1099. =back
  1100.  
  1101. =item Readline Signal Handling
  1102.  
  1103. =over 4
  1104.  
  1105. =item C<cleanup_after_signal>
  1106.  
  1107.     void    rl_cleanup_after_signal()    # GRL 4.0
  1108.  
  1109. =item C<free_line_state>
  1110.  
  1111.     void    rl_free_line_state()    # GRL 4.0
  1112.  
  1113. =item C<reset_after_signal>
  1114.  
  1115.     void    rl_reset_after_signal()    # GRL 4.0
  1116.  
  1117. =item C<resize_terminal>
  1118.  
  1119.     void    rl_resize_terminal()    # GRL 4.0
  1120.  
  1121. =item C<set_screen_size(ROWS, COLS)>
  1122.  
  1123.     void    rl_set_screen_size(int ROWS, int COLS)    # GRL 4.2
  1124.  
  1125. =item C<get_screen_size()>
  1126.  
  1127.     (int rows, int cols)    rl_get_screen_size()    # GRL 4.2
  1128.  
  1129. =item C<set_signals>
  1130.  
  1131.     int    rl_set_signals()    # GRL 4.0
  1132.  
  1133. =item C<clear_signals>
  1134.  
  1135.     int    rl_clear_signals()    # GRL 4.0
  1136.  
  1137. =back
  1138.  
  1139. =item Completion Functions
  1140.  
  1141. =over 4
  1142.  
  1143. =item C<complete_internal([WHAT_TO_DO])>
  1144.  
  1145.     int    rl_complete_internal(int what_to_do = TAB)
  1146.  
  1147. =item C<completion_mode(FUNCTION)>
  1148.  
  1149.     int    rl_completion_mode(FunctionPtr|str function)
  1150.  
  1151. =item C<completion_matches(TEXT [,FUNC])>
  1152.  
  1153.     (@str)    rl_completion_matches(str text,
  1154.                       pfunc func = filename_completion_function)
  1155.  
  1156. =item C<filename_completion_function(TEXT, STATE)>
  1157.  
  1158.     str    rl_filename_completion_function(str text, int state)
  1159.  
  1160. =item C<username_completion_function(TEXT, STATE)>
  1161.  
  1162.     str    rl_username_completion_function(str text, int state)
  1163.  
  1164. =item C<list_completion_function(TEXT, STATE)>
  1165.  
  1166.     str    list_completion_function(str text, int state)
  1167.  
  1168. =back
  1169.  
  1170. =item History Functions
  1171.  
  1172. =over 4
  1173.  
  1174. =item Initializing History and State Management
  1175.  
  1176. =over 4
  1177.  
  1178. =item C<using_history>
  1179.  
  1180.     void    using_history()
  1181.  
  1182. =back
  1183.  
  1184. =item History List Management
  1185.  
  1186. =over 4
  1187.  
  1188. =item C<addhistory(STRING[, STRING, ...])>
  1189.  
  1190.     void    add_history(str string)
  1191.  
  1192. =item C<StifleHistory(MAX)>
  1193.  
  1194.     int    stifle_history(int max|undef)
  1195.  
  1196. stifles the history list, remembering only the last C<MAX> entries.
  1197. If C<MAX> is undef, remembers all entries.  This is a replacement
  1198. of unstifle_history().
  1199.  
  1200. =item C<unstifle_history>
  1201.  
  1202.     int    unstifle_history()
  1203.  
  1204. This is equivalent with 'stifle_history(undef)'.
  1205.  
  1206. =item C<SetHistory(LINE1 [, LINE2, ...])>
  1207.  
  1208. sets the history of input, from where it can be used if the actual
  1209. C<readline> is present.
  1210.  
  1211. =item C<remove_history(WHICH)>
  1212.  
  1213.     str    remove_history(int which)
  1214.  
  1215. =item C<replace_history_entry(WHICH, LINE)>
  1216.  
  1217.     str    replace_history_entry(int which, str line)
  1218.  
  1219. =item C<clear_history>
  1220.  
  1221.     void    clear_history()
  1222.  
  1223. =item C<history_is_stifled>
  1224.  
  1225.     int    history_is_stifled()
  1226.  
  1227. =back
  1228.  
  1229. =item Information About the History List
  1230.  
  1231. =over 4
  1232.  
  1233. =item C<where_history>
  1234.  
  1235.     int    where_history()
  1236.  
  1237. =item C<current_history>
  1238.  
  1239.     str    current_history()
  1240.  
  1241. =item C<history_get(OFFSET)>
  1242.  
  1243.     str    history_get(offset)
  1244.  
  1245. =item C<history_total_bytes>
  1246.  
  1247.     int    history_total_bytes()
  1248.  
  1249. =item C<GetHistory>
  1250.  
  1251. returns the history of input as a list, if actual C<readline> is present.
  1252.  
  1253. =back
  1254.  
  1255. =item Moving Around the History List
  1256.  
  1257. =over 4
  1258.  
  1259. =item C<history_set_pos(POS)>
  1260.  
  1261.     int    history_set_pos(int pos)
  1262.  
  1263. =item C<previous_history>
  1264.  
  1265.     str    previous_history()
  1266.  
  1267. =item C<next_history>
  1268.  
  1269.     str    next_history()
  1270.  
  1271. =back
  1272.  
  1273. =item Searching the History List
  1274.  
  1275. =over 4
  1276.  
  1277. =item C<history_search(STRING [,DIRECTION])>
  1278.  
  1279.     int    history_search(str string, int direction = -1)
  1280.  
  1281. =item C<history_search_prefix(STRING [,DIRECTION])>
  1282.  
  1283.     int    history_search_prefix(str string, int direction = -1)
  1284.  
  1285. =item C<history_search_pos(STRING [,DIRECTION [,POS]])>
  1286.  
  1287.     int    history_search_pos(str string,
  1288.                    int direction = -1,
  1289.                    int pos = where_history())
  1290.  
  1291. =back
  1292.  
  1293. =item Managing the History File
  1294.  
  1295. =over 4
  1296.  
  1297. =item C<ReadHistory([FILENAME [,FROM [,TO]]])>
  1298.  
  1299.     int    read_history(str filename = '~/.history',
  1300.                  int from = 0, int to = -1)
  1301.  
  1302.     int    read_history_range(str filename = '~/.history',
  1303.                    int from = 0, int to = -1)
  1304.  
  1305. adds the contents of C<FILENAME> to the history list, a line at a
  1306. time.  If C<FILENAME> is false, then read from F<~/.history>.  Start
  1307. reading at line C<FROM> and end at C<TO>.  If C<FROM> is omitted or
  1308. zero, start at the beginning.  If C<TO> is omitted or less than
  1309. C<FROM>, then read until the end of the file.  Returns true if
  1310. successful, or false if not.  C<read_history()> is an aliase of
  1311. C<read_history_range()>.
  1312.  
  1313. =item C<WriteHistory([FILENAME])>
  1314.  
  1315.     int    write_history(str filename = '~/.history')
  1316.  
  1317. writes the current history to C<FILENAME>, overwriting C<FILENAME> if
  1318. necessary.  If C<FILENAME> is false, then write the history list to
  1319. F<~/.history>.  Returns true if successful, or false if not.
  1320.  
  1321.  
  1322. =item C<append_history(NELEMENTS [,FILENAME])>
  1323.  
  1324.     int    append_history(int nelements, str filename = '~/.history')
  1325.  
  1326. =item C<history_truncate_file([FILENAME [,NLINES]])>
  1327.  
  1328.     int    history_truncate_file(str filename = '~/.history',
  1329.                       int nlines = 0)
  1330.  
  1331. =back
  1332.  
  1333. =item History Expansion
  1334.  
  1335. =over 4
  1336.  
  1337. =item C<history_expand(LINE)>
  1338.  
  1339.     (int result, str expansion) history_expand(str line)
  1340.  
  1341. Note that this function returns C<expansion> in scalar context.
  1342.  
  1343. =item C<get_history_event(STRING, CINDEX [,QCHAR])>
  1344.  
  1345.     (str text, int cindex) = get_history_event(str  string,
  1346.                            int  cindex,
  1347.                            char qchar = '\0')
  1348.  
  1349. =item C<history_tokenize(LINE)>
  1350.  
  1351.     (@str)    history_tokenize(str line)
  1352.  
  1353. =item C<history_arg_extract(LINE, [FIRST [,LAST]])>
  1354.  
  1355.     str history_arg_extract(str line, int first = 0, int last = '$')
  1356.  
  1357. =back
  1358.  
  1359. =back
  1360.  
  1361. =back
  1362.  
  1363. =head2 C<Term::ReadLine::Gnu> Variables
  1364.  
  1365. Following GNU Readline/History Library variables can be accessed from
  1366. Perl program.  See 'GNU Readline Library Manual' and ' GNU History
  1367. Library Manual' for each variable.  You can access them with
  1368. C<Attribs> methods.  Names of keys in this hash conform to standard
  1369. conventions with the leading C<rl_> stripped.
  1370.  
  1371. Examples:
  1372.  
  1373.     $attribs = $term->Attribs;
  1374.     $v = $attribs->{library_version};    # rl_library_version
  1375.     $v = $attribs->{history_base};    # history_base
  1376.  
  1377. =over 4
  1378.  
  1379. =item Readline Variables
  1380.  
  1381.     str rl_line_buffer
  1382.     int rl_point
  1383.     int rl_end
  1384.     int rl_mark
  1385.     int rl_done        
  1386.     int rl_num_chars_to_read (GRL 4.2)
  1387.     int rl_pending_input
  1388.     int rl_dispatching (GRL 4.2)
  1389.     int rl_erase_empty_line (GRL 4.0)
  1390.     str rl_prompt (read only)
  1391.     int rl_already_prompted (GRL 4.1)
  1392.     str rl_library_version (read only)
  1393.     int rl_readline_version (read only)
  1394.     int rl_gnu_readline_p (GRL 4.2)
  1395.     str rl_terminal_name
  1396.     str rl_readline_name
  1397.     filehandle rl_instream
  1398.     filehandle rl_outstream
  1399.     pfunc rl_startup_hook
  1400.     pfunc rl_pre_input_hook (GRL 4.0)
  1401.     pfunc rl_event_hook
  1402.     pfunc rl_getc_function
  1403.     pfunc rl_redisplay_function
  1404.     pfunc rl_prep_term_function (GRL 4.2)
  1405.     pfunc rl_deprep_term_function (GRL 4.2)
  1406.     pfunc rl_last_func (GRL 4.2)
  1407.     Keymap rl_executing_keymap (read only)
  1408.     Keymap rl_binding_keymap (read only)
  1409.     str rl_executing_macro (GRL 4.2)
  1410.     int rl_readline_state (GRL 4.2)
  1411.     int rl_explicit_arg (GRL 4.2)
  1412.     int rl_numeric_arg (GRL 4.2)
  1413.     int rl_editing_mode (GRL 4.2)
  1414.  
  1415. =item Signal Handling Variables
  1416.  
  1417.     int rl_catch_signals (GRL 4.0)
  1418.     int rl_catch_sigwinch (GRL 4.0)
  1419.  
  1420. =item Completion Variables
  1421.  
  1422.     pfunc rl_completion_entry_function
  1423.     pfunc rl_attempted_completion_function
  1424.     pfunc rl_filename_quoting_function
  1425.     pfunc rl_filename_dequoting_function
  1426.     pfunc rl_char_is_quoted_p
  1427.     int rl_completion_query_items
  1428.     str rl_basic_word_break_characters
  1429.     str rl_basic_quote_characters
  1430.     str rl_completer_word_break_characters
  1431.     str rl_completer_quote_characters
  1432.     str rl_filename_quote_characters
  1433.     str rl_special_prefixes
  1434.     int rl_completion_append_character
  1435.     int rl_completion_suppress_append (GRL 4.3)
  1436.     int rl_completion_mark_symlink_dirs (GRL 4.3)
  1437.     int rl_ignore_completion_duplicates
  1438.     int rl_filename_completion_desired
  1439.     int rl_filename_quoting_desired
  1440.     int rl_attempted_completion_over (GRL 4.2)
  1441.     int rl_completion_type (GRL 4.2)
  1442.     int rl_inhibit_completion
  1443.     pfunc rl_ignore_some_completion_function
  1444.     pfunc rl_directory_completion_hook
  1445.     pfunc rl_completion_display_matches_hook (GRL 4.0)
  1446.  
  1447. =item History Variables
  1448.  
  1449.     int history_base
  1450.     int history_length
  1451.     int history_max_entries (called `max_input_history'. read only)
  1452.     char history_expansion_char
  1453.     char history_subst_char
  1454.     char history_comment_char
  1455.     str history_word_delimiters (GRL 4.2)
  1456.     str history_no_expand_chars
  1457.     str history_search_delimiter_chars
  1458.     int history_quotes_inhibit_expansion
  1459.     pfunc history_inhibit_expansion_function
  1460.  
  1461. =item Function References
  1462.  
  1463.     rl_getc
  1464.     rl_redisplay
  1465.     rl_callback_read_char
  1466.     rl_display_match_list
  1467.     rl_filename_completion_function
  1468.     rl_username_completion_function
  1469.     list_completion_function
  1470.     shadow_redisplay
  1471.     Tk_getc
  1472.  
  1473. =back
  1474.  
  1475. =head2 Custom Completion
  1476.  
  1477. In this section variables and functions for custom completion is
  1478. described with examples.
  1479.  
  1480. Most of descriptions in this section is cited from GNU Readline
  1481. Library manual.
  1482.  
  1483. =over 4
  1484.  
  1485. =item C<rl_completion_entry_function>
  1486.  
  1487. This variable holds reference refers to a generator function for
  1488. C<completion_matches()>.
  1489.  
  1490. A generator function is called repeatedly from
  1491. C<completion_matches()>, returning a string each time.  The arguments
  1492. to the generator function are C<TEXT> and C<STATE>.  C<TEXT> is the
  1493. partial word to be completed.  C<STATE> is zero the first time the
  1494. function is called, allowing the generator to perform any necessary
  1495. initialization, and a positive non-zero integer for each subsequent
  1496. call.  When the generator function returns C<undef> this signals
  1497. C<completion_matches()> that there are no more possibilities left.
  1498.  
  1499. If the value is undef, built-in C<filename_completion_function> is
  1500. used.
  1501.  
  1502. A sample generator function, C<list_completion_function>, is defined
  1503. in Gnu.pm.  You can use it as follows;
  1504.  
  1505.     use Term::ReadLine;
  1506.     ...
  1507.     my $term = new Term::ReadLine 'sample';
  1508.     my $attribs = $term->Attribs;
  1509.     ...
  1510.     $attribs->{completion_entry_function} =
  1511.     $attribs->{list_completion_function};
  1512.     ...
  1513.     $attribs->{completion_word} =
  1514.     [qw(reference to a list of words which you want to use for completion)];
  1515.     $term->readline("custom completion>");
  1516.  
  1517. See also C<completion_matches>.
  1518.  
  1519. =item C<rl_attempted_completion_function>
  1520.  
  1521. A reference to an alternative function to create matches.
  1522.  
  1523. The function is called with C<TEXT>, C<LINE_BUFFER>, C<START>, and
  1524. C<END>.  C<LINE_BUFFER> is a current input buffer string.  C<START>
  1525. and C<END> are indices in C<LINE_BUFFER> saying what the boundaries of
  1526. C<TEXT> are.
  1527.  
  1528. If this function exists and returns null list or C<undef>, or if this
  1529. variable is set to C<undef>, then an internal function
  1530. C<rl_complete()> will call the value of
  1531. C<$rl_completion_entry_function> to generate matches, otherwise the
  1532. array of strings returned will be used.
  1533.  
  1534. The default value of this variable is C<undef>.  You can use it as follows;
  1535.  
  1536.     use Term::ReadLine;
  1537.     ...
  1538.     my $term = new Term::ReadLine 'sample';
  1539.     my $attribs = $term->Attribs;
  1540.     ...
  1541.     sub sample_completion {
  1542.         my ($text, $line, $start, $end) = @_;
  1543.         # If first word then username completion, else filename completion
  1544.         if (substr($line, 0, $start) =~ /^\s*$/) {
  1545.             return $term->completion_matches($text,
  1546.                          $attribs->{'username_completion_function'});
  1547.         } else {
  1548.             return ();
  1549.         }
  1550.     }
  1551.     ...
  1552.     $attribs->{attempted_completion_function} = \&sample_completion;
  1553.  
  1554. =item C<completion_matches(TEXT, ENTRY_FUNC)>
  1555.  
  1556. Returns an array of strings which is a list of completions for
  1557. C<TEXT>.  If there are no completions, returns C<undef>.  The first
  1558. entry in the returned array is the substitution for C<TEXT>.  The
  1559. remaining entries are the possible completions.
  1560.  
  1561. C<ENTRY_FUNC> is a generator function which has two arguments, and
  1562. returns a string.  The first argument is C<TEXT>.  The second is a
  1563. state argument; it is zero on the first call, and non-zero on
  1564. subsequent calls.  C<ENTRY_FUNC> returns a C<undef> to the caller when
  1565. there are no more matches.
  1566.  
  1567. If the value of C<ENTRY_FUNC> is undef, built-in
  1568. C<filename_completion_function> is used.
  1569.  
  1570. C<completion_matches> is a Perl wrapper function of an internal
  1571. function C<completion_matches()>.  See also
  1572. C<$rl_completion_entry_function>.
  1573.  
  1574. =item C<completion_function>
  1575.  
  1576. A variable whose content is a reference to a function which returns a
  1577. list of candidates to complete.
  1578.  
  1579. This variable is compatible with C<Term::ReadLine::Perl> and very easy
  1580. to use.
  1581.  
  1582.     use Term::ReadLine;
  1583.     ...
  1584.     my $term = new Term::ReadLine 'sample';
  1585.     my $attribs = $term->Attribs;
  1586.     ...
  1587.     $attribs->{completion_function} = sub {
  1588.     my ($text, $line, $start) = @_;
  1589.     return qw(a list of candidates to complete);
  1590.     }
  1591.  
  1592. =item C<list_completion_function(TEXT, STATE)>
  1593.  
  1594. A sample generator function defined by C<Term::ReadLine::Gnu>.
  1595. Example code at C<rl_completion_entry_function> shows how to use this
  1596. function.
  1597.  
  1598. =back
  1599.  
  1600. =head2 C<Term::ReadLine::Gnu> Specific Features
  1601.  
  1602. =over 4
  1603.  
  1604. =item C<Term::ReadLine::Gnu> Specific Functions
  1605.  
  1606. =over 4
  1607.  
  1608. =item C<CallbackHandlerInstall(PROMPT, LHANDLER)>
  1609.  
  1610. This method provides the function C<rl_callback_handler_install()>
  1611. with the following addtional feature compatible with C<readline>
  1612. method; ornament feature, C<Term::ReadLine::Perl> compatible
  1613. completion function, histroy expansion, and addition to history
  1614. buffer.
  1615.  
  1616. =item C<call_function(FUNCTION, [COUNT [,KEY]])>
  1617.  
  1618.     int    rl_call_function(FunctionPtr|str function, count = 1, key = -1)
  1619.  
  1620. =item C<rl_get_all_function_names>
  1621.  
  1622. Returns a list of all function names.
  1623.  
  1624. =item C<shadow_redisplay>
  1625.  
  1626. A redisplay function for password input.  You can use it as follows;
  1627.  
  1628.     $attribs->{redisplay_function} = $attribs->{shadow_redisplay};
  1629.     $line = $term->readline("password> ");
  1630.  
  1631. =item C<rl_filename_list>
  1632.  
  1633. Returns candidates of filename to complete.  This function can be used
  1634. with C<completion_function> and is implemented for the compatibility
  1635. with C<Term::ReadLine::Perl>.
  1636.  
  1637. =item C<list_completion_function>
  1638.  
  1639. See the description of section L<"Custom Completion"|"Custom Completion">.
  1640.  
  1641. =back
  1642.  
  1643. =item C<Term::ReadLine::Gnu> Specific Variables
  1644.  
  1645. =over 4
  1646.  
  1647. =item C<do_expand>
  1648.  
  1649. When true, the history expansion is enabled.  By default false.
  1650.  
  1651. =item C<completion_function>
  1652.  
  1653. See the description of section L<"Custom Completion"|"Custom Completion">.
  1654.  
  1655. =item C<completion_word>
  1656.  
  1657. A reference to a list of candidates to complete for
  1658. C<list_completion_function>.
  1659.  
  1660. =back
  1661.  
  1662. =item C<Term::ReadLine::Gnu> Specific Commands
  1663.  
  1664. =over 4
  1665.  
  1666. =item C<history-expand-line>
  1667.  
  1668. The equivalent of the Bash C<history-expand-line> editing command.
  1669.  
  1670. =item C<operate-and-get-next>
  1671.  
  1672. The equivalent of the Korn shell C<operate-and-get-next-history-line>
  1673. editing command and the Bash C<operate-and-get-next>.
  1674.  
  1675. This command is bound to C<\C-o> by default for the compatibility with
  1676. the Bash and C<Term::ReadLine::Perl>.
  1677.  
  1678. =item C<display-readline-version>
  1679.  
  1680. Shows the version of C<Term::ReadLine::Gnu> and the one of the GNU
  1681. Readline Library.
  1682.  
  1683. =item C<change-ornaments>
  1684.  
  1685. Change ornaments interactively.
  1686.  
  1687. =back
  1688.  
  1689. =back
  1690.  
  1691. =head1 FILES
  1692.  
  1693. =over 4
  1694.  
  1695. =item F<~/.inputrc>
  1696.  
  1697. Readline init file.  Using this file it is possible that you would
  1698. like to use a different set of key bindings.  When a program which
  1699. uses the Readline library starts up, the init file is read, and the
  1700. key bindings are set.
  1701.  
  1702. Conditional key binding is also available.  The program name which is
  1703. specified by the first argument of C<new> method is used as the
  1704. application construct.
  1705.  
  1706. For example, when your program call C<new> method like this;
  1707.  
  1708.     ...
  1709.     $term = new Term::ReadLine 'PerlSh';
  1710.     ...
  1711.  
  1712. your F<~/.inputrc> can define key bindings only for it as follows;
  1713.  
  1714.     ...
  1715.     $if PerlSh
  1716.     Meta-Rubout: backward-kill-word
  1717.     "\C-x\C-r": re-read-init-file
  1718.         "\e[11~": "Function Key 1"
  1719.     $endif
  1720.     ...
  1721.  
  1722. =back
  1723.  
  1724. =head1 EXPORTS
  1725.  
  1726. None.
  1727.  
  1728. =head1 SEE ALSO
  1729.  
  1730. =over 4
  1731.  
  1732. =item GNU Readline Library Manual
  1733.  
  1734. =item GNU History Library Manual
  1735.  
  1736. =item C<Term::ReadLine>
  1737.  
  1738. =item C<Term::ReadLine::Perl> (Term-ReadLine-Perl-xx.tar.gz)
  1739.  
  1740. =item F<eg/*> and F<t/*> in the Term::ReadLine::Gnu distribution
  1741.  
  1742. =item Articles related to Term::ReadLine::Gnu
  1743.  
  1744. =over 4
  1745.  
  1746. =item effective perl programming
  1747.  
  1748.     http://www.usenix.org/publications/login/2000-7/features/effective.html
  1749.  
  1750. This article demonstrates how to integrate Term::ReadLine::Gnu into an
  1751. interactive command line program.
  1752.  
  1753. =item eijiro (Japanese)
  1754.  
  1755.     http://bulknews.net/lib/columns/02_eijiro/column.html
  1756.  
  1757. A command line interface to Eijiro, Japanese-English dictionary
  1758. service on WWW.
  1759.  
  1760.  
  1761. =back
  1762.  
  1763. =item Works which use Term::ReadLine::Gnu
  1764.  
  1765. =over 4
  1766.  
  1767. =item Perl Debugger
  1768.  
  1769.     perl -d
  1770.  
  1771. =item The Perl Shell (psh)
  1772.  
  1773.     http://www.focusresearch.com/gregor/psh/
  1774.  
  1775. The Perl Shell is a shell that combines the interactive nature of a
  1776. Unix shell with the power of Perl.
  1777.  
  1778. A programmable completion feature compatible with bash is implemented.
  1779.  
  1780. =item SPP (Synopsys Plus Perl)
  1781.  
  1782.     http://www.stanford.edu/~jsolomon/SPP/
  1783.  
  1784. SPP (Synopsys Plus Perl) is a Perl module that wraps around Synopsys'
  1785. shell programs.  SPP is inspired by the original dc_perl written by
  1786. Steve Golson, but it's an entirely new implementation.  Why is it
  1787. called SPP and not dc_perl?  Well, SPP was written to wrap around any
  1788. of Synopsys' shells.
  1789.  
  1790. =item PFM (Personal File Manager for Unix/Linux)
  1791.  
  1792.     http://p-f-m.sourceforge.net/
  1793.  
  1794. Pfm is a terminal-based file manager written in Perl, based on PFM.COM
  1795. for MS-DOS (originally by Paul Culley and Henk de Heer).
  1796.  
  1797. =item The soundgrab
  1798.  
  1799.     http://rawrec.sourceforge.net/soundgrab/soundgrab.html
  1800.  
  1801. soundgrab is designed to help you slice up a big long raw audio file
  1802. (by default 44.1 kHz 2 channel signed sixteen bit little endian) and
  1803. save your favorite sections to other files. It does this by providing
  1804. you with a cassette player like command line interface.
  1805.  
  1806. =item PDL (The Perl Data Language)
  1807.  
  1808.     http://pdl.perl.org/index_en.html
  1809.  
  1810. PDL (``Perl Data Language'') gives standard Perl the ability to
  1811. compactly store and speedily manipulate the large N-dimensional data
  1812. arrays which are the bread and butter of scientific computing.
  1813.  
  1814. =item PIQT (Perl Interactive DBI Query Tool)
  1815.  
  1816.     http://piqt.sourceforge.net/
  1817.  
  1818. PIQT is an interactive query tool using the Perl DBI database
  1819. interface. It supports ReadLine, provides a built in scripting language
  1820. with a Lisp like syntax, an online help system, and uses wrappers to
  1821. interface to the DBD modules.
  1822.  
  1823. =item Ghostscript Shell
  1824.  
  1825.     http://www.panix.com/~jdf/gshell/
  1826.  
  1827. It provides a friendly way to play with the Ghostscript interpreter,
  1828. including command history and auto-completion of Postscript font names
  1829. and reserved words.
  1830.  
  1831. =back
  1832.  
  1833. If you know any other works which can be listed here, please let me
  1834. know.
  1835.  
  1836. =back
  1837.  
  1838. =head1 AUTHOR
  1839.  
  1840. Hiroo Hayashi C<E<lt>hiroo.hayashi@computer.orgE<gt>>
  1841.  
  1842. C<http://www.perl.org/CPAN/authors/Hiroo_HAYASHI/>
  1843.  
  1844. =head1 TODO
  1845.  
  1846. GTK+ support in addition to Tk.
  1847.  
  1848. =head1 BUGS
  1849.  
  1850. C<rl_add_defun()> can define up to 16 functions.
  1851.  
  1852. Ornament feature works only on prompt strings.  It requires very hard
  1853. hacking of C<display.c:rl_redisplay()> in GNU Readline library to
  1854. ornament input line.
  1855.  
  1856. C<newTTY()> is not tested yet.
  1857.  
  1858. =cut
  1859.