1Gnu(3) User Contributed Perl Documentation Gnu(3)
2
6 Term::ReadLine::Gnu - Perl extension for the GNU Readline/History
7 Library
8
10 use Term::ReadLine;
11 $term = new Term::ReadLine 'ProgramName';
12 while ( defined ($_ = $term->readline('prompt>')) ) {
13 ...
14 }
15
17 Overview
18 This is an implementation of Term::ReadLine using the GNU
19 Readline/History Library.
20 For basic functions object oriented interface is provided. These are
22 described in the section "Standard Methods" and ""Term::ReadLine::Gnu"
23 Functions".
24 This package also has the interface with the almost all functions and
26 variables which are documented in the GNU Readline/History Library
27 Manual. They are documented in the section ""Term::ReadLine::Gnu"
28 Functions" and ""Term::ReadLine::Gnu" Variables" briefly. For more
29 detail of the GNU Readline/History Library, see 'GNU Readline Library
30 Manual' and 'GNU History Library Manual'.
31 The sample programs under "eg/" directory and test programs under "t/"
33 directory in the "Term::ReadLine::Gnu" distribution include many
34 example of this module.
35 Standard Methods
37 These methods are standard methods defined by Term::ReadLine.
38 "ReadLine"
40 returns the actual package that executes the commands. If you have
41 installed this package, possible value is "Term::ReadLine::Gnu".
42 "new(NAME,[IN[,OUT]])"
44 returns the handle for subsequent calls to following functions.
45 Argument is the name of the application. Optionally can be
46 followed by two arguments for "IN" and "OUT" file handles. These
47 arguments should be globs.
48 "readline(PROMPT[,PREPUT])"
50 gets an input line, with actual "GNU Readline" support. Trailing
51 newline is removed. Returns "undef" on "EOF". "PREPUT" is an
52 optional argument meaning the initial value of input.
53 The optional argument "PREPUT" is granted only if the value
55 "preput" is in "Features".
56 "PROMPT" may include some escape sequences. Use
58 "RL_PROMPT_START_IGNORE" to begin a sequence of non-printing
59 characters, and "RL_PROMPT_END_IGNORE" to end of such a sequence.
60 "AddHistory(LINE1, LINE2, ...)"
62 adds the lines to the history of input, from where it can be used
63 if the actual "readline" is present.
64 "IN", "OUT"
66 return the file handles for input and output or "undef" if
67 "readline" input and output cannot be used for Perl.
68 "MinLine([MAX])"
70 If argument "MAX" is specified, it is an advice on minimal size of
71 line to be included into history. "undef" means do not include
72 anything into history. Returns the old value.
73 "findConsole"
75 returns an array with two strings that give most appropriate names
76 for files for input and output using conventions "<$in", ">$out".
77 "Attribs"
79 returns a reference to a hash which describes internal
80 configuration (variables) of the package. Names of keys in this
81 hash conform to standard conventions with the leading "rl_"
82 stripped.
83 See section "Variables" for supported variables.
85 "Features"
87 Returns a reference to a hash with keys being features present in
88 current implementation. Several optional features are used in the
89 minimal interface: "appname" should be present if the first
90 argument to "new" is recognized, and "minline" should be present if
91 "MinLine" method is not dummy. "autohistory" should be present if
92 lines are put into history automatically (maybe subject to
93 "MinLine"), and "addHistory" if "AddHistory" method is not dummy.
94 "preput" means the second argument to "readline" method is
95 processed. "getHistory" and "setHistory" denote that the
96 corresponding methods are present. "tkRunning" denotes that a Tk
97 application may run while ReadLine is getting input.
98 "Term::ReadLine::Gnu" Functions
100 All these GNU Readline/History Library functions are callable via
101 method interface and have names which conform to standard conventions
102 with the leading "rl_" stripped.
103 Almost methods have lower level functions in "Term::ReadLine::Gnu::XS"
105 package. To use them full qualified name is required. Using method
106 interface is preferred.
107 Readline Convenience Functions
109 Naming Function
110 "add_defun(NAME, FUNC [,KEY=-1])"
111 Add name to the Perl function "FUNC". If optional argument
112 "KEY" is specified, bind it to the "FUNC". Returns
113 reference to "FunctionPtr".
114 Example:
116 # name name `reverse-line' to a function reverse_line(),
117 # and bind it to "\C-t"
118 $term->add_defun('reverse-line', \&reverse_line, ord "\ct");
119 Selecting a Keymap
121 "make_bare_keymap"
122 Keymap rl_make_bare_keymap()
123 "copy_keymap(MAP)"
125 Keymap rl_copy_keymap(Keymap|str map)
126 "make_keymap"
128 Keymap rl_make_keymap()
129 "discard_keymap(MAP)"
131 Keymap rl_discard_keymap(Keymap|str map)
132 "get_keymap"
134 Keymap rl_get_keymap()
135 "set_keymap(MAP)"
137 Keymap rl_set_keymap(Keymap|str map)
138 "get_keymap_by_name(NAME)"
140 Keymap rl_get_keymap_by_name(str name)
141 "get_keymap_name(MAP)"
143 str rl_get_keymap_name(Keymap map)
144 Binding Keys
146 "bind_key(KEY, FUNCTION [,MAP])"
147 int rl_bind_key(int key, FunctionPtr|str function,
148 Keymap|str map = rl_get_keymap())
149 Bind "KEY" to the "FUNCTION". "FUNCTION" is the name added
151 by the "add_defun" method. If optional argument "MAP" is
152 specified, binds in "MAP". Returns non-zero in case of
153 error.
154 "bind_key_if_unbound(KEY, FUNCTION [,MAP])"
156 int rl_bind_key_if_unbound(int key, FunctionPtr|str function,
157 Keymap|str map = rl_get_keymap()) #GRL5.0
158 "unbind_key(KEY [,MAP])"
160 int rl_unbind_key(int key, Keymap|str map = rl_get_keymap())
161 Bind "KEY" to the null function. Returns non-zero in case
163 of error.
164 "unbind_function(FUNCTION [,MAP])"
166 int rl_unbind_function(FunctionPtr|str function,
167 Keymap|str map = rl_get_keymap())
168 "unbind_command(COMMAND [,MAP])"
170 int rl_unbind_command(str command,
171 Keymap|str map = rl_get_keymap())
172 "bind_keyseq(KEYSEQ, FUNCTION [,MAP])"
174 int rl_bind_keyseq(str keyseq, FunctionPtr|str function,
175 Keymap|str map = rl_get_keymap()) # GRL 5.0
176 "set_key(KEYSEQ, FUNCTION [,MAP])"
178 int rl_set_key(str keyseq, FunctionPtr|str function,
179 Keymap|str map = rl_get_keymap())
180 "bind_keyseq_if_unbound(KEYSEQ, FUNCTION [,MAP])"
182 int rl_bind_keyseq_if_unbound(str keyseq, FunctionPtr|str function,
183 Keymap|str map = rl_get_keymap()) # GRL 5.0
184 "generic_bind(TYPE, KEYSEQ, DATA, [,MAP])"
186 int rl_generic_bind(int type, str keyseq,
187 FunctionPtr|Keymap|str data,
188 Keymap|str map = rl_get_keymap())
189 "parse_and_bind(LINE)"
191 void rl_parse_and_bind(str line)
192 Parse "LINE" as if it had been read from the ~/.inputrc
194 file and perform any key bindings and variable assignments
195 found. For more detail see 'GNU Readline Library Manual'.
196 "read_init_file([FILENAME])"
198 int rl_read_init_file(str filename = '~/.inputrc')
199 Associating Function Names and Bindings
201 "named_function(NAME)"
202 FunctionPtr rl_named_function(str name)
203 "get_function_name(FUNCTION)"
205 str rl_get_function_name(FunctionPtr function)
206 "function_of_keyseq(KEYMAP [,MAP])"
208 (FunctionPtr|Keymap|str data, int type)
209 rl_function_of_keyseq(str keyseq,
210 Keymap|str map = rl_get_keymap())
211 "invoking_keyseqs(FUNCTION [,MAP])"
213 (@str) rl_invoking_keyseqs(FunctionPtr|str function,
214 Keymap|str map = rl_get_keymap())
215 "function_dumper([READABLE])"
217 void rl_function_dumper(int readable = 0)
218 "list_funmap_names"
220 void rl_list_funmap_names()
221 "funmap_names"
223 (@str) rl_funmap_names()
224 "add_funmap_entry(NAME, FUNCTION)"
226 int rl_add_funmap_entry(char *name, FunctionPtr|str function)
227 Allowing Undoing
229 "begin_undo_group"
230 int rl_begin_undo_group()
231 "end_undo_group"
233 int rl_end_undo_group()
234 "add_undo(WHAT, START, END, TEXT)"
236 int rl_add_undo(int what, int start, int end, str text)
237 "free_undo_list"
239 void rl_free_undo_list()
240 "do_undo"
242 int rl_do_undo()
243 "modifying([START [,END]])"
245 int rl_modifying(int start = 0, int end = rl_end)
246 Redisplay
248 "redisplay"
249 void rl_redisplay()
250 "forced_update_display"
252 int rl_forced_update_display()
253 "on_new_line"
255 int rl_on_new_line()
256 "on_new_line_with_prompt"
258 int rl_on_new_line_with_prompt() # GRL 4.1
259 "reset_line_state"
261 int rl_reset_line_state()
262 rl_show_char(C)
264 int rl_show_char(int c)
265 "message(FMT[, ...])"
267 int rl_message(str fmt, ...)
268 "crlf"
270 int rl_crlf() # GRL 4.2
271 "clear_message"
273 int rl_clear_message()
274 "save_prompt"
276 void rl_save_prompt()
277 "restore_prompt"
279 void rl_restore_prompt()
280 "expand_prompt(PROMPT)"
282 int rl_expand_prompt(str prompt) # GRL 4.2
283 "set_prompt(PROMPT)"
285 int rl_set_prompt(const str prompt) # GRL 4.2
286 Modifying Text
288 "insert_text(TEXT)"
289 int rl_insert_text(str text)
290 "delete_text([START [,END]])"
292 int rl_delete_text(int start = 0, int end = rl_end)
293 "copy_text([START [,END]])"
295 str rl_copy_text(int start = 0, int end = rl_end)
296 "kill_text([START [,END]])"
298 int rl_kill_text(int start = 0, int end = rl_end)
299 "push_macro_input(MACRO)"
301 int rl_push_macro_input(str macro)
302 Character Input
304 "read_key"
305 int rl_read_key()
306 "getc(STREAM)"
308 int rl_getc(FILE *STREAM)
309 stuff_char(C)
311 int rl_stuff_char(int c)
312 execute_next(C)
314 int rl_execute_next(int c) # GRL 4.2
315 "clear_pending_input()"
317 int rl_clear_pending_input() # GRL 4.2
318 "set_keyboard_input_timeout(uSEC)"
320 int rl_set_keyboard_input_timeout(int usec) # GRL 4.2
321 Terminal Management
323 "prep_terminal(META_FLAG)"
324 void rl_prep_terminal(int META_FLAG) # GRL 4.2
325 "deprep_terminal()"
327 void rl_deprep_terminal() # GRL 4.2
328 "tty_set_default_bindings(KMAP)"
330 void rl_tty_set_default_bindings([Keymap KMAP]) # GRL 4.2
331 "tty_unset_default_bindings(KMAP)"
333 void rl_tty_unset_default_bindings([Keymap KMAP]) # GRL 5.0
334 "reset_terminal([TERMINAL_NAME])"
336 int rl_reset_terminal(str terminal_name = getenv($TERM)) # GRL 4.2
337 Utility Functions
339 "save_state(READLINE_STATE)"
340 NOT IMPLEMENTED YET!
341 int rl_save_state(struct readline_state *sp) # GRL 6.0
342 "restore_state(READLINE_STATE)"
344 NOT IMPLEMENTED YET!
345 int rl_restore_state(struct readline_state *sp) # GRL 6.0
346 "replace_line(TEXT [,CLEAR_UNDO])"
348 int rl_replace_line(str text, int clear_undo) # GRL 4.3
349 "initialize"
351 int rl_initialize()
352 "ding"
354 int rl_ding()
355 alphabetic(C)
357 int rl_alphabetic(int C)
358 "display_match_list(MATCHES [,LEN [,MAX]])"
360 void rl_display_match_list(\@matches, len = $#maches, max) # GRL 4.0
361 Since the first element of an array @matches as treated as
363 a possible completion, it is not displayed. See the
364 descriptions of "completion_matches()".
365 When "MAX" is ommited, the max length of an item in
367 @matches is used.
368 Miscellaneous Functions
370 "macro_bind(KEYSEQ, MACRO [,MAP])"
371 int rl_macro_bind(const str keyseq, const str macro, Keymap map)
372 "macro_dumper(READABLE)"
374 int rl_macro_dumper(int readline)
375 "variable_bind(VARIABLE, VALUE)"
377 int rl_variable_bind(const str variable, const str value)
378 "variable_value(VARIABLE)"
380 str rl_variable_value(const str variable) # GRL 5.1
381 "variable_dumper(READABLE)"
383 int rl_variable_dumper(int readline)
384 "set_paren_blink_timeout(uSEC)"
386 int rl_set_paren_blink_timeout(usec) # GRL 4.2
387 "get_termcap(cap)"
389 str rl_get_termcap(cap)
390 Alternate Interface
392 "callback_handler_install(PROMPT, LHANDLER)"
393 void rl_callback_handler_install(str prompt, pfunc lhandler)
394 "callback_read_char"
396 void rl_callback_read_char()
397 "callback_handler_remove"
399 void rl_callback_handler_remove()
400 Readline Signal Handling
402 "cleanup_after_signal"
403 void rl_cleanup_after_signal() # GRL 4.0
404 "free_line_state"
406 void rl_free_line_state() # GRL 4.0
407 "reset_after_signal"
409 void rl_reset_after_signal() # GRL 4.0
410 "echo_signal_char"
412 void rl_echo_signal_char(int sig) # GRL 6.0
413 "resize_terminal"
415 void rl_resize_terminal() # GRL 4.0
416 "set_screen_size(ROWS, COLS)"
418 void rl_set_screen_size(int ROWS, int COLS) # GRL 4.2
419 "get_screen_size()"
421 (int rows, int cols) rl_get_screen_size() # GRL 4.2
422 "reset_screen_size()"
424 void rl_reset_screen_size() # GRL 5.1
425 "set_signals"
427 int rl_set_signals() # GRL 4.0
428 "clear_signals"
430 int rl_clear_signals() # GRL 4.0
431 Completion Functions
433 "complete_internal([WHAT_TO_DO])"
434 int rl_complete_internal(int what_to_do = TAB)
435 "completion_mode(FUNCTION)"
437 int rl_completion_mode(FunctionPtr|str function)
438 "completion_matches(TEXT [,FUNC])"
440 (@str) rl_completion_matches(str text,
441 pfunc func = filename_completion_function)
442 "filename_completion_function(TEXT, STATE)"
444 str rl_filename_completion_function(str text, int state)
445 "username_completion_function(TEXT, STATE)"
447 str rl_username_completion_function(str text, int state)
448 "list_completion_function(TEXT, STATE)"
450 str list_completion_function(str text, int state)
451 History Functions
453 Initializing History and State Management
454 "using_history"
455 void using_history()
456 History List Management
458 "addhistory(STRING[, STRING, ...])"
459 void add_history(str string)
460 "StifleHistory(MAX)"
462 int stifle_history(int max|undef)
463 stifles the history list, remembering only the last "MAX"
465 entries. If "MAX" is undef, remembers all entries. This
466 is a replacement of unstifle_history().
467 "unstifle_history"
469 int unstifle_history()
470 This is equivalent with 'stifle_history(undef)'.
472 "SetHistory(LINE1 [, LINE2, ...])"
474 sets the history of input, from where it can be used if the
475 actual "readline" is present.
476 "add_history_time(STRING)"
478 void add_history_time(str string) # GRL 5.0
479 "remove_history(WHICH)"
481 str remove_history(int which)
482 "replace_history_entry(WHICH, LINE)"
484 str replace_history_entry(int which, str line)
485 "clear_history"
487 void clear_history()
488 "history_is_stifled"
490 int history_is_stifled()
491 Information About the History List
493 "where_history"
494 int where_history()
495 "current_history"
497 str current_history()
498 "history_get(OFFSET)"
500 str history_get(offset)
501 "history_get_time(OFFSET)"
503 time_t history_get_time(offset)
504 "history_total_bytes"
506 int history_total_bytes()
507 "GetHistory"
509 returns the history of input as a list, if actual
510 "readline" is present.
511 Moving Around the History List
513 "history_set_pos(POS)"
514 int history_set_pos(int pos)
515 "previous_history"
517 str previous_history()
518 "next_history"
520 str next_history()
521 Searching the History List
523 "history_search(STRING [,DIRECTION])"
524 int history_search(str string, int direction = -1)
525 "history_search_prefix(STRING [,DIRECTION])"
527 int history_search_prefix(str string, int direction = -1)
528 "history_search_pos(STRING [,DIRECTION [,POS]])"
530 int history_search_pos(str string,
531 int direction = -1,
532 int pos = where_history())
533 Managing the History File
535 "ReadHistory([FILENAME [,FROM [,TO]]])"
536 int read_history(str filename = '~/.history',
537 int from = 0, int to = -1)
538 int read_history_range(str filename = '~/.history',
540 int from = 0, int to = -1)
541 adds the contents of "FILENAME" to the history list, a line
543 at a time. If "FILENAME" is false, then read from
544 ~/.history. Start reading at line "FROM" and end at "TO".
545 If "FROM" is omitted or zero, start at the beginning. If
546 "TO" is omitted or less than "FROM", then read until the
547 end of the file. Returns true if successful, or false if
548 not. "read_history()" is an aliase of
549 "read_history_range()".
550 "WriteHistory([FILENAME])"
552 int write_history(str filename = '~/.history')
553 writes the current history to "FILENAME", overwriting
555 "FILENAME" if necessary. If "FILENAME" is false, then
556 write the history list to ~/.history. Returns true if
557 successful, or false if not.
558 "append_history(NELEMENTS [,FILENAME])"
560 int append_history(int nelements, str filename = '~/.history')
561 "history_truncate_file([FILENAME [,NLINES]])"
563 int history_truncate_file(str filename = '~/.history',
564 int nlines = 0)
565 History Expansion
567 "history_expand(LINE)"
568 (int result, str expansion) history_expand(str line)
569 Note that this function returns "expansion" in scalar
571 context.
572 "get_history_event(STRING, CINDEX [,QCHAR])"
574 (str text, int cindex) = get_history_event(str string,
575 int cindex,
576 char qchar = '\0')
577 "history_tokenize(LINE)"
579 (@str) history_tokenize(str line)
580 "history_arg_extract(LINE, [FIRST [,LAST]])"
582 str history_arg_extract(str line, int first = 0, int last = '$')
583 "Term::ReadLine::Gnu" Variables
585 Following GNU Readline/History Library variables can be accessed from
586 Perl program. See 'GNU Readline Library Manual' and ' GNU History
587 Library Manual' for each variable. You can access them with "Attribs"
588 methods. Names of keys in this hash conform to standard conventions
589 with the leading "rl_" stripped.
590 Examples:
592 $attribs = $term->Attribs;
594 $v = $attribs->{library_version}; # rl_library_version
595 $v = $attribs->{history_base}; # history_base
596 Readline Variables
598 str rl_line_buffer
599 int rl_point
600 int rl_end
601 int rl_mark
602 int rl_done
603 int rl_num_chars_to_read (GRL 4.2)
604 int rl_pending_input
605 int rl_dispatching (GRL 4.2)
606 int rl_erase_empty_line (GRL 4.0)
607 str rl_prompt (read only)
608 str rl_display_prompt (GRL 6.0)
609 int rl_already_prompted (GRL 4.1)
610 str rl_library_version (read only)
611 int rl_readline_version (read only)
612 int rl_gnu_readline_p (GRL 4.2)
613 str rl_terminal_name
614 str rl_readline_name
615 filehandle rl_instream
616 filehandle rl_outstream
617 int rl_prefer_env_winsize (GRL 5.1)
618 pfunc rl_last_func (GRL 4.2)
619 pfunc rl_startup_hook
620 pfunc rl_pre_input_hook (GRL 4.0)
621 pfunc rl_event_hook
622 pfunc rl_getc_function
623 pfunc rl_redisplay_function
624 pfunc rl_prep_term_function (GRL 4.2)
625 pfunc rl_deprep_term_function (GRL 4.2)
626 Keymap rl_executing_keymap (read only)
627 Keymap rl_binding_keymap (read only)
628 str rl_executing_macro (GRL 4.2)
629 int rl_readline_state (GRL 4.2)
630 int rl_explicit_arg (GRL 4.2)
631 int rl_numeric_arg (GRL 4.2)
632 int rl_editing_mode (GRL 4.2)
633 Signal Handling Variables
635 int rl_catch_signals (GRL 4.0)
636 int rl_catch_sigwinch (GRL 4.0)
637 Completion Variables
639 pfunc rl_completion_entry_function
640 pfunc rl_attempted_completion_function
641 pfunc rl_filename_quoting_function
642 pfunc rl_filename_dequoting_function
643 pfunc rl_char_is_quoted_p
644 int rl_completion_query_items
645 str rl_basic_word_break_characters
646 str rl_basic_quote_characters
647 str rl_completer_word_break_characters
648 pfunc rl_completion_word_break_hook (GRL 5.0)
649 str rl_completer_quote_characters
650 str rl_filename_quote_characters
651 str rl_special_prefixes
652 int rl_completion_append_character
653 int rl_completion_suppress_append (GRL 4.3)
654 int rl_completion_quote_charactor (GRL 5.0)
655 int rl_completion_suppress_quote (GRL 5.0)
656 int rl_completion_found_quote (GRL 5.0)
657 int rl_completion_mark_symlink_dirs (GRL 4.3)
658 int rl_ignore_completion_duplicates
659 int rl_filename_completion_desired
660 int rl_filename_quoting_desired
661 int rl_attempted_completion_over (GRL 4.2)
662 int rl_sort_completion_matches (GRL 6.0)
663 int rl_completion_type (GRL 4.2)
664 int rl_completion_invoking_key (GRL 6.0)
665 int rl_inhibit_completion
666 pfunc rl_ignore_some_completion_function
667 pfunc rl_directory_completion_hook
668 pfunc rl_completion_display_matches_hook (GRL 4.0)
669 History Variables
671 int history_base
672 int history_length
673 int history_max_entries (called `max_input_history'. read only)
674 int history_write_timestamps (GRL 5.0)
675 char history_expansion_char
676 char history_subst_char
677 char history_comment_char
678 str history_word_delimiters (GRL 4.2)
679 str history_no_expand_chars
680 str history_search_delimiter_chars
681 int history_quotes_inhibit_expansion
682 pfunc history_inhibit_expansion_function
683 Function References
685 rl_getc
686 rl_redisplay
687 rl_callback_read_char
688 rl_display_match_list
689 rl_filename_completion_function
690 rl_username_completion_function
691 list_completion_function
692 shadow_redisplay
693 Tk_getc
694 Custom Completion
696 In this section variables and functions for custom completion is
697 described with examples.
698 Most of descriptions in this section is cited from GNU Readline Library
700 manual.
701 "rl_completion_entry_function"
703 This variable holds reference refers to a generator function for
704 "completion_matches()".
705 A generator function is called repeatedly from
707 "completion_matches()", returning a string each time. The
708 arguments to the generator function are "TEXT" and "STATE". "TEXT"
709 is the partial word to be completed. "STATE" is zero the first
710 time the function is called, allowing the generator to perform any
711 necessary initialization, and a positive non-zero integer for each
712 subsequent call. When the generator function returns "undef" this
713 signals "completion_matches()" that there are no more possibilities
714 left.
715 If the value is undef, built-in "filename_completion_function" is
717 used.
718 A sample generator function, "list_completion_function", is defined
720 in Gnu.pm. You can use it as follows;
721 use Term::ReadLine;
723 ...
724 my $term = new Term::ReadLine 'sample';
725 my $attribs = $term->Attribs;
726 ...
727 $attribs->{completion_entry_function} =
728 $attribs->{list_completion_function};
729 ...
730 $attribs->{completion_word} =
731 [qw(reference to a list of words which you want to use for completion)];
732 $term->readline("custom completion>");
733 See also "completion_matches".
735 "rl_attempted_completion_function"
737 A reference to an alternative function to create matches.
738 The function is called with "TEXT", "LINE_BUFFER", "START", and
740 "END". "LINE_BUFFER" is a current input buffer string. "START"
741 and "END" are indices in "LINE_BUFFER" saying what the boundaries
742 of "TEXT" are.
743 If this function exists and returns null list or "undef", or if
745 this variable is set to "undef", then an internal function
746 "rl_complete()" will call the value of
747 $rl_completion_entry_function to generate matches, otherwise the
748 array of strings returned will be used.
749 The default value of this variable is "undef". You can use it as
751 follows;
752 use Term::ReadLine;
754 ...
755 my $term = new Term::ReadLine 'sample';
756 my $attribs = $term->Attribs;
757 ...
758 sub sample_completion {
759 my ($text, $line, $start, $end) = @_;
760 # If first word then username completion, else filename completion
761 if (substr($line, 0, $start) =~ /^\s*$/) {
762 return $term->completion_matches($text,
763 $attribs->{'username_completion_function'});
764 } else {
765 return ();
766 }
767 }
768 ...
769 $attribs->{attempted_completion_function} = \&sample_completion;
770 "completion_matches(TEXT, ENTRY_FUNC)"
772 Returns an array of strings which is a list of completions for
773 "TEXT". If there are no completions, returns "undef". The first
774 entry in the returned array is the substitution for "TEXT". The
775 remaining entries are the possible completions.
776 "ENTRY_FUNC" is a generator function which has two arguments, and
778 returns a string. The first argument is "TEXT". The second is a
779 state argument; it is zero on the first call, and non-zero on
780 subsequent calls. "ENTRY_FUNC" returns a "undef" to the caller
781 when there are no more matches.
782 If the value of "ENTRY_FUNC" is undef, built-in
784 "filename_completion_function" is used.
785 "completion_matches" is a Perl wrapper function of an internal
787 function "completion_matches()". See also
788 $rl_completion_entry_function.
789 "completion_function"
791 A variable whose content is a reference to a function which returns
792 a list of candidates to complete.
793 This variable is compatible with "Term::ReadLine::Perl" and very
795 easy to use.
796 use Term::ReadLine;
798 ...
799 my $term = new Term::ReadLine 'sample';
800 my $attribs = $term->Attribs;
801 ...
802 $attribs->{completion_function} = sub {
803 my ($text, $line, $start) = @_;
804 return qw(a list of candidates to complete);
805 }
806 "list_completion_function(TEXT, STATE)"
808 A sample generator function defined by "Term::ReadLine::Gnu".
809 Example code at "rl_completion_entry_function" shows how to use
810 this function.
811 "Term::ReadLine::Gnu" Specific Features
813 "Term::ReadLine::Gnu" Specific Functions
814 "CallbackHandlerInstall(PROMPT, LHANDLER)"
815 This method provides the function
816 "rl_callback_handler_install()" with the following addtional
817 feature compatible with "readline" method; ornament feature,
818 "Term::ReadLine::Perl" compatible completion function, histroy
819 expansion, and addition to history buffer.
820 "call_function(FUNCTION, [COUNT [,KEY]])"
822 int rl_call_function(FunctionPtr|str function, count = 1, key = -1)
823 "rl_get_all_function_names"
825 Returns a list of all function names.
826 "shadow_redisplay"
828 A redisplay function for password input. You can use it as
829 follows;
830 $attribs->{redisplay_function} = $attribs->{shadow_redisplay};
832 $line = $term->readline("password> ");
833 "rl_filename_list"
835 Returns candidates of filename to complete. This function can
836 be used with "completion_function" and is implemented for the
837 compatibility with "Term::ReadLine::Perl".
838 "list_completion_function"
840 See the description of section "Custom Completion".
841 "Term::ReadLine::Gnu" Specific Variables
843 "do_expand"
844 When true, the history expansion is enabled. By default false.
845 "completion_function"
847 See the description of section "Custom Completion".
848 "completion_word"
850 A reference to a list of candidates to complete for
851 "list_completion_function".
852 "Term::ReadLine::Gnu" Specific Commands
854 "history-expand-line"
855 The equivalent of the Bash "history-expand-line" editing
856 command.
857 "operate-and-get-next"
859 The equivalent of the Korn shell
860 "operate-and-get-next-history-line" editing command and the
861 Bash "operate-and-get-next".
862 This command is bound to "\C-o" by default for the
864 compatibility with the Bash and "Term::ReadLine::Perl".
865 "display-readline-version"
867 Shows the version of "Term::ReadLine::Gnu" and the one of the
868 GNU Readline Library.
869 "change-ornaments"
871 Change ornaments interactively.
872
874 ~/.inputrc
875 Readline init file. Using this file it is possible that you would
876 like to use a different set of key bindings. When a program which
877 uses the Readline library starts up, the init file is read, and the
878 key bindings are set.
879 Conditional key binding is also available. The program name which
881 is specified by the first argument of "new" method is used as the
882 application construct.
883 For example, when your program call "new" method like this;
885 ...
887 $term = new Term::ReadLine 'PerlSh';
888 ...
889 your ~/.inputrc can define key bindings only for it as follows;
891 ...
893 $if PerlSh
894 Meta-Rubout: backward-kill-word
895 "\C-x\C-r": re-read-init-file
896 "\e[11~": "Function Key 1"
897 $endif
898 ...
899
901 None.
902
904 GNU Readline Library Manual
905 GNU History Library Manual
906 "Term::ReadLine"
907 "Term::ReadLine::Perl" (Term-ReadLine-Perl-xx.tar.gz)
908 eg/* and t/* in the Term::ReadLine::Gnu distribution
909 Articles related to Term::ReadLine::Gnu
910 effective perl programming
911 http://www.usenix.org/publications/login/2000-7/features/effective.html
912 This article demonstrates how to integrate Term::ReadLine::Gnu
914 into an interactive command line program.
915 eijiro (Japanese)
917 http://bulknews.net/lib/columns/02_eijiro/column.html
918 A command line interface to Eijiro, Japanese-English dictionary
920 service on WWW.
921 Works which use Term::ReadLine::Gnu
923 Perl Debugger
924 perl -d
925 The Perl Shell (psh)
927 http://www.focusresearch.com/gregor/psh/
928 The Perl Shell is a shell that combines the interactive nature
930 of a Unix shell with the power of Perl.
931 A programmable completion feature compatible with bash is
933 implemented.
934 SPP (Synopsys Plus Perl)
936 http://www.stanford.edu/~jsolomon/SPP/
937 SPP (Synopsys Plus Perl) is a Perl module that wraps around
939 Synopsys' shell programs. SPP is inspired by the original
940 dc_perl written by Steve Golson, but it's an entirely new
941 implementation. Why is it called SPP and not dc_perl? Well,
942 SPP was written to wrap around any of Synopsys' shells.
943 PFM (Personal File Manager for Unix/Linux)
945 http://p-f-m.sourceforge.net/
946 Pfm is a terminal-based file manager written in Perl, based on
948 PFM.COM for MS-DOS (originally by Paul Culley and Henk de
949 Heer).
950 The soundgrab
952 http://rawrec.sourceforge.net/soundgrab/soundgrab.html
953 soundgrab is designed to help you slice up a big long raw audio
955 file (by default 44.1 kHz 2 channel signed sixteen bit little
956 endian) and save your favorite sections to other files. It does
957 this by providing you with a cassette player like command line
958 interface.
959 PDL (The Perl Data Language)
961 http://pdl.perl.org/index_en.html
962 PDL (``Perl Data Language'') gives standard Perl the ability to
964 compactly store and speedily manipulate the large N-dimensional
965 data arrays which are the bread and butter of scientific
966 computing.
967 PIQT (Perl Interactive DBI Query Tool)
969 http://piqt.sourceforge.net/
970 PIQT is an interactive query tool using the Perl DBI database
972 interface. It supports ReadLine, provides a built in scripting
973 language with a Lisp like syntax, an online help system, and
974 uses wrappers to interface to the DBD modules.
975 Ghostscript Shell
977 http://www.panix.com/~jdf/gshell/
978 It provides a friendly way to play with the Ghostscript
980 interpreter, including command history and auto-completion of
981 Postscript font names and reserved words.
982 vshnu (the New Visual Shell)
984 http://www.cs.indiana.edu/~kinzler/vshnu/
985 A visual shell and CLI shell supplement.
987 If you know any other works which can be listed here, please let me
989 know.
990
992 Hiroo Hayashi "<hiroo.hayashi@computer.org>"
993 "http://www.perl.org/CPAN/authors/Hiroo_HAYASHI/"
995
997 GTK+ support in addition to Tk.
998
1000 "rl_add_defun()" can define up to 16 functions.
1001 Ornament feature works only on prompt strings. It requires very hard
1003 hacking of "display.c:rl_redisplay()" in GNU Readline library to
1004 ornament input line.
1005 "newTTY()" is not tested yet.
1007perl v5.12.0 2010-05-06 Gnu(3)