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