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; # Do not "use Term::ReadLine::Gnu;"
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
19 <http://search.cpan.org/dist/Term-ReadLine/> using the GNU
20 Readline/History Library
21 <http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html>.
22 For basic functions object oriented interface is provided. These are
24 described in the section "Standard Methods" and ""Term::ReadLine::Gnu"
25 Functions".
26 This package also has the interface with the almost all functions and
28 variables which are documented in the GNU Readline/History Library
29 Manual. They are documented in the section ""Term::ReadLine::Gnu"
30 Functions" and ""Term::ReadLine::Gnu" Variables" briefly. For further
31 details of the GNU Readline/History Library, see GNU Readline Library
32 Manual <http://cnswww.cns.cwru.edu/php/chet/readline/readline.html> and
33 GNU History Library Manual
34 <http://cnswww.cns.cwru.edu/php/chet/readline/history.html>.
35 There are some "Term::ReadLine::Gnu" original features. They are
37 described in the section ""Term::ReadLine::Gnu" Specific Features"
38 The sample programs under eg/ directory and test programs under t/
40 directory in the "Term::ReadLine::Gnu" distribution
41 <http://search.cpan.org/dist/Term-ReadLine-Gnu/> include many examples
42 of this module.
43 Standard Methods
45 These are standard methods defined by Term::ReadLine
46 <http://search.cpan.org/dist/Term-ReadLine/>.
47 "ReadLine"
49 returns the actual package that executes the commands. If this
50 package is being used, "Term::ReadLine::Gnu" is returned.
51 "new(NAME,[IN,OUT])"
53 returns the handle for subsequent calls to following functions.
54 Argument is the name of the application. Optionally can be
55 followed by two arguments for "IN" and "OUT" file handles. These
56 arguments should be globs.
57 "readline(PROMPT[,PREPUT])"
59 gets an input line, with actual "GNU Readline" support. Trailing
60 newline is removed. Returns "undef" on "EOF". "PREPUT" is an
61 optional argument meaning the initial value of input.
62 The optional argument "PREPUT" is granted only if the value
64 "preput" is in "Features".
65 "PROMPT" may include some escape sequences. Use
67 "RL_PROMPT_START_IGNORE" to begin a sequence of non-printing
68 characters, and "RL_PROMPT_END_IGNORE" to end the sequence.
69 "AddHistory(LINE1, LINE2, ...)"
71 adds the lines to the history of input, from where it can be used
72 if the actual "readline" is present.
73 "IN", "OUT"
75 return the file handles for input and output or "undef" if
76 "readline" input and output cannot be used for Perl.
77 "MinLine([MAX])"
79 If argument "MAX" is specified, it is an advice on minimal size of
80 line to be included into history. "undef" means do not include
81 anything into history. Returns the old value.
82 "findConsole"
84 returns an array with two strings that give most appropriate names
85 for files for input and output using conventions "<$in", ">$out".
86 "Attribs"
88 returns a reference to a hash which describes internal
89 configuration (variables) of the package. Names of keys in this
90 hash conform to standard conventions with the leading "rl_"
91 stripped.
92 See section ""Term::ReadLine::Gnu" Variables" for supported
94 variables.
95 "Features"
97 Returns a reference to a hash with keys being features present in
98 current implementation. Several optional features are used in the
99 minimal interface: "appname" should be present if the first
100 argument to "new" is recognized, and "minline" should be present if
101 "MinLine" method is not dummy. "autohistory" should be present if
102 lines are put into history automatically (maybe subject to
103 "MinLine"), and "addHistory" if "AddHistory" method is not dummy.
104 "preput" means the second argument to "readline" method is
105 processed. "getHistory" and "setHistory" denote that the
106 corresponding methods are present. "tkRunning" denotes that a Tk
107 application may run while ReadLine is getting input.
108 "tkRunning"
110 makes Tk event loop run when waiting for user input (i.e., during
111 "readline" method).
112 "event_loop"
114 See the description of "event_loop" on Term::ReadLine
115 <http://search.cpan.org/dist/Term-ReadLine/>.
116 "ornaments"
118 makes the command line stand out by using termcap data. The
119 argument to "ornaments" should be 0, 1, or a string of a form
120 "aa,bb,cc,dd". Four components of this string should be names of
121 terminal capacities, first two will be issued to make the prompt
122 standout, last two to make the input line standout.
123 "newTTY"
125 takes two arguments which are input filehandle and output
126 filehandle. Switches to use these filehandles.
127 "enableUTF8"
129 Enables UTF-8 support.
130 If STDIN is in UTF-8 by the "-C" command-line switch or
132 "PERL_UNICODE" environment variable, or "IN" file handle has "utf8"
133 IO layer, then UTF-8 support is also enabled. In other cases you
134 need this "enableUTF8" method.
135 This is an original method of "Term::ReadLine:Gnu".
137 "Term::ReadLine::Gnu" Functions
139 All these GNU Readline/History Library functions supported are callable
140 via method interface and have names which conform to standard
141 conventions with the leading "rl_" stripped. For example "rl_foo()"
142 function is called as "$term->foo()".
143 The titles of the following sections are same as the titles of the
145 corresponding sections in the "Programming with GNU Readline" section
146 in the GNU Readline Library Manual
147 <http://cnswww.cns.cwru.edu/php/chet/readline/readline.html>. Refer
148 them for further details.
149 Although it is preferred to use method interface, most methods have
151 lower level functions in "Term::ReadLine::Gnu::XS" package. To use
152 them a full qualified name is required.
153 Basic Behavior
155 The function "readline()" prints a prompt and then reads and returns a
157 single line of text from the user.
158 $_ = $term->readline('Enter a line: ');
160 You can change key-bindings using "bind_key(KEY, FUNCTION [,MAP])"
162 function. The first argument, "KEY", is the character that you want
163 bind. The second argument, "FUNCTION", is the function to call when
164 "KEY" is pressed. The "FUNCTION" can be a reference to a Perl function
165 (see "Custom Functions") or a "named function" named by "add_defun()"
166 function or commands described in the "Bindable Readline Commands"
167 section in the GNU Readline Library Manual
168 <http://cnswww.cns.cwru.edu/php/chet/readline/readline.html>.
169 $term->bind_key(ord "\ci, 'tab-insert');
171 The above example binds Control-I to the 'tab-insert' command.
173 Custom Functions
175 You can write new functions using Perl. The calling sequence for a
177 command foo looks like
178 sub foo ($count, $key) { ... }
180 where $count is the numeric argument (or 1 if defaulted) and $key is
182 the key that invoked this function.
183 Here is an example;
185 sub reverse_line { # reverse a whole line
187 my($count, $key) = @_; # ignored in this sample function
188 $t->modifying(0, $a->{end}); # save undo information
190 $a->{line_buffer} = reverse $a->{line_buffer};
191 }
192 See the "Writing a New Function" section in the GNU Readline Library
194 Manual <http://cnswww.cns.cwru.edu/php/chet/readline/readline.html> for
195 further details.
196 Readline Convenience Functions
198 Naming a Function
200 "add_defun(NAME, FUNCTION [,KEY=-1])"
202 Add name to a Perl function "FUNCTION". If optional argument "KEY"
203 is specified, bind it to the "FUNCTION". Returns reference to
204 "FunctionPtr".
205 Example:
207 # name `reverse-line' to a function reverse_line(),
208 # and bind it to "\C-t"
209 $term->add_defun('reverse-line', \&reverse_line, ord "\ct");
210 Selecting a Keymap
212 "make_bare_keymap"
214 Keymap rl_make_bare_keymap()
215 "copy_keymap(MAP)"
217 Keymap rl_copy_keymap(Keymap|str map)
218 "make_keymap"
220 Keymap rl_make_keymap()
221 "discard_keymap(MAP)"
223 Keymap rl_discard_keymap(Keymap|str map)
224 "free_keymap(MAP)"
226 void rl_free_keymap(Keymap|str map)
227 "get_keymap"
229 Keymap rl_get_keymap()
230 "set_keymap(MAP)"
232 Keymap rl_set_keymap(Keymap|str map)
233 "get_keymap_by_name(NAME)"
235 Keymap rl_get_keymap_by_name(str name)
236 "get_keymap_name(MAP)"
238 str rl_get_keymap_name(Keymap map)
239 Binding Keys
241 "bind_key(KEY, FUNCTION [,MAP])"
243 int rl_bind_key(int key, FunctionPtr|str function,
244 Keymap|str map = rl_get_keymap())
245 Bind "KEY" to the "FUNCTION". "FUNCTION" is the name added by the
247 "add_defun" method. If optional argument "MAP" is specified, binds
248 in "MAP". Returns non-zero in case of error.
249 "bind_key_if_unbound(KEY, FUNCTION [,MAP])"
251 int rl_bind_key_if_unbound(int key, FunctionPtr|str function,
252 Keymap|str map = rl_get_keymap()) # GRL 5.0
253 "unbind_key(KEY [,MAP])"
255 int rl_unbind_key(int key, Keymap|str map = rl_get_keymap())
256 Bind "KEY" to the null function. Returns non-zero in case of
258 error.
259 "unbind_function(FUNCTION [,MAP])"
261 int rl_unbind_function(FunctionPtr|str function,
262 Keymap|str map = rl_get_keymap())
263 "unbind_command(COMMAND [,MAP])"
265 int rl_unbind_command(str command,
266 Keymap|str map = rl_get_keymap())
267 "bind_keyseq(KEYSEQ, FUNCTION [,MAP])"
269 int rl_bind_keyseq(str keyseq, FunctionPtr|str function,
270 Keymap|str map = rl_get_keymap()) # GRL 5.0
271 "set_key(KEYSEQ, FUNCTION [,MAP])"
273 int rl_set_key(str keyseq, FunctionPtr|str function,
274 Keymap|str map = rl_get_keymap()) # GRL 4.2
275 "bind_keyseq_if_unbound(KEYSEQ, FUNCTION [,MAP])"
277 int rl_bind_keyseq_if_unbound(str keyseq, FunctionPtr|str function,
278 Keymap|str map = rl_get_keymap()) # GRL 5.0
279 "generic_bind(TYPE, KEYSEQ, DATA, [,MAP])"
281 int rl_generic_bind(int type, str keyseq,
282 FunctionPtr|Keymap|str data,
283 Keymap|str map = rl_get_keymap())
284 "parse_and_bind(LINE)"
286 void rl_parse_and_bind(str line)
287 Parse "LINE" as if it had been read from the ~/.inputrc file and
289 perform any key bindings and variable assignments found. For
290 further detail see GNU Readline Library Manual
291 <http://cnswww.cns.cwru.edu/php/chet/readline/readline.html>.
292 "read_init_file([FILENAME])"
294 int rl_read_init_file(str filename = '~/.inputrc')
295 Associating Function Names and Bindings
297 "named_function(NAME)"
299 FunctionPtr rl_named_function(str name)
300 "get_function_name(FUNCTION)"
302 str rl_get_function_name(FunctionPtr function) # TRG original
303 "function_of_keyseq(KEYSEQ [,MAP])"
305 (FunctionPtr|Keymap|str data, int type)
306 rl_function_of_keyseq(str keyseq,
307 Keymap|str map = rl_get_keymap())
308 "invoking_keyseqs(FUNCTION [,MAP])"
310 (@str) rl_invoking_keyseqs(FunctionPtr|str function,
311 Keymap|str map = rl_get_keymap())
312 "function_dumper([READABLE])"
314 void rl_function_dumper(int readable = 0)
315 "list_funmap_names"
317 void rl_list_funmap_names()
318 "funmap_names"
320 (@str) rl_funmap_names()
321 "add_funmap_entry(NAME, FUNCTION)"
323 int rl_add_funmap_entry(char *name, FunctionPtr|str function)
324 Allowing Undoing
326 "begin_undo_group"
328 int rl_begin_undo_group()
329 "end_undo_group"
331 int rl_end_undo_group()
332 "add_undo(WHAT, START, END, TEXT)"
334 int rl_add_undo(int what, int start, int end, str text)
335 "free_undo_list"
337 void rl_free_undo_list()
338 "do_undo"
340 int rl_do_undo()
341 "modifying([START [,END]])"
343 int rl_modifying(int start = 0, int end = rl_end)
344 Redisplay
346 "redisplay"
348 void rl_redisplay()
349 "forced_update_display"
351 int rl_forced_update_display()
352 "on_new_line"
354 int rl_on_new_line()
355 "on_new_line_with_prompt"
357 int rl_on_new_line_with_prompt() # GRL 4.1
358 "clear_visible_line()"
360 int rl_clear_visible_line() # GRL 7.0
361 "reset_line_state"
363 int rl_reset_line_state()
364 "crlf"
366 int rl_crlf()
367 show_char(C)
369 int rl_show_char(int c)
370 "message(FMT[, ...])"
372 int rl_message(str fmt, ...)
373 "clear_message"
375 int rl_clear_message()
376 "save_prompt"
378 void rl_save_prompt()
379 "restore_prompt"
381 void rl_restore_prompt()
382 "expand_prompt(PROMPT)"
384 int rl_expand_prompt(str prompt)
385 "set_prompt(PROMPT)"
387 int rl_set_prompt(const str prompt) # GRL 4.2
388 Modifying Text
390 "insert_text(TEXT)"
392 int rl_insert_text(str text)
393 "delete_text([START [,END]])"
395 int rl_delete_text(int start = 0, int end = rl_end)
396 "copy_text([START [,END]])"
398 str rl_copy_text(int start = 0, int end = rl_end)
399 "kill_text([START [,END]])"
401 int rl_kill_text(int start = 0, int end = rl_end)
402 "push_macro_input(MACRO)"
404 int rl_push_macro_input(str macro)
405 Character Input
407 "read_key"
409 int rl_read_key()
410 "getc(STREAM)"
412 int rl_getc(FILE *STREAM)
413 stuff_char(C)
415 int rl_stuff_char(int c)
416 execute_next(C)
418 int rl_execute_next(int c)
419 "clear_pending_input()"
421 int rl_clear_pending_input() # GRL 4.2
422 "set_keyboard_input_timeout(uSEC)"
424 int rl_set_keyboard_input_timeout(int usec) # GRL 4.2
425 Terminal Management
427 "prep_terminal(META_FLAG)"
429 void rl_prep_terminal(int META_FLAG)
430 "deprep_terminal()"
432 void rl_deprep_terminal()
433 "tty_set_default_bindings([MAP])"
435 void rl_tty_set_default_bindings([Keymap|str map = rl_get_keymap()]) # GRL 4.0
436 "tty_unset_default_bindings([MAP])"
438 void rl_tty_unset_default_bindings([Keymap|str map = rl_get_keymap()]) # GRL 5.0
439 "tty_set_echoing(VALUE)"
441 int rl_tty_set_echoing(int value) # GRL 7.0
442 "reset_terminal([TERMINAL_NAME])"
444 int rl_reset_terminal(str terminal_name = getenv($TERM))
445 Utility Functions
447 "save_state(READLINE_STATE)"
449 READLINE_STATE rl_save_state() # GRL 6.0
450 "restore_state(READLINE_STATE)"
452 int rl_restore_state(READLINE_STATE) # GRL 6.0
453 "free(MEM)"
455 Not implemented since not required for Perl.
456 int rl_free(void *mem) # GRL 6.0
457 "replace_line(TEXT [,CLEAR_UNDO])"
459 int rl_replace_line(str text, int clear_undo = 0) # GRL 4.3
460 "extend_line_buffer(LEN)"
462 Not implemented since not required for Perl.
463 int rl_extend_line_buffer(int len)
464 "initialize"
466 int rl_initialize()
467 "ding"
469 int rl_ding()
470 alphabetic(C)
472 int rl_alphabetic(int C) # GRL 4.2
473 "display_match_list(MATCHES [,LEN [,MAX]])"
475 void rl_display_match_list(\@matches, len = $#maches, max) # GRL 4.0
476 Since the first element of an array @matches as treated as a
478 possible completion, it is not displayed. See the descriptions of
479 "completion_matches()". When "MAX" is omitted, the max length of
480 an item in @matches is used.
481 Miscellaneous Functions
483 "macro_bind(KEYSEQ, MACRO [,MAP])"
485 int rl_macro_bind(const str keyseq, const str macro, Keymap map)
486 "macro_dumper(READABLE)"
488 int rl_macro_dumper(int readline)
489 "variable_bind(VARIABLE, VALUE)"
491 int rl_variable_bind(const str variable, const str value)
492 "variable_value(VARIABLE)"
494 str rl_variable_value(const str variable) # GRL 5.1
495 "variable_dumper(READABLE)"
497 int rl_variable_dumper(int readline)
498 "set_paren_blink_timeout(uSEC)"
500 int rl_set_paren_blink_timeout(usec) # GRL 4.2
501 "get_termcap(cap)"
503 str rl_get_termcap(cap)
504 "clear_history"
506 void rl_clear_history() # GRL 6.3
507 Alternate Interface
509 "callback_handler_install(PROMPT, LHANDLER)"
511 void rl_callback_handler_install(str prompt, pfunc lhandler)
512 "callback_read_char"
514 void rl_callback_read_char()
515 "callback_sigcleanup" # GRL 7.0
517 void rl_callback_sigcleanup()
518 "callback_handler_remove"
520 void rl_callback_handler_remove()
521 Readline Signal Handling
523 "pending_signal()"
525 int rl_pending_signal() # GRL 7.0
526 "cleanup_after_signal"
528 void rl_cleanup_after_signal() # GRL 4.0
529 "free_line_state"
531 void rl_free_line_state() # GRL 4.0
532 "reset_after_signal"
534 void rl_reset_after_signal() # GRL 4.0
535 "echo_signal_char"
537 void rl_echo_signal_char(int sig) # GRL 6.0
538 "resize_terminal"
540 void rl_resize_terminal() # GRL 4.0
541 "set_screen_size(ROWS, COLS)"
543 void rl_set_screen_size(int ROWS, int COLS) # GRL 4.2
544 "get_screen_size()"
546 (int rows, int cols) rl_get_screen_size() # GRL 4.2
547 "reset_screen_size()"
549 void rl_reset_screen_size() # GRL 5.1
550 "set_signals"
552 int rl_set_signals() # GRL 4.0
553 "clear_signals"
555 int rl_clear_signals() # GRL 4.0
556 Completion Functions
558 "complete_internal([WHAT_TO_DO])"
560 int rl_complete_internal(int what_to_do = TAB)
561 "completion_mode(FUNCTION)"
563 int rl_completion_mode(FunctionPtr|str function) # GRL 4.3
564 "completion_matches(TEXT [,FUNC])"
566 (@str) rl_completion_matches(str text,
567 pfunc func = filename_completion_function)
568 "filename_completion_function(TEXT, STATE)"
570 str rl_filename_completion_function(str text, int state)
571 "username_completion_function(TEXT, STATE)"
573 str rl_username_completion_function(str text, int state)
574 "list_completion_function(TEXT, STATE)"
576 str list_completion_function(str text, int state) # TRG original
577 History Functions
579 Initializing History and State Management
581 "using_history"
583 void using_history()
584 "history_get_history_state"
586 HISTORY_STATE history_get_hitory_state() # GRL 6.3
587 "history_set_history_state"
589 void history_set_hitory_state(HISTORY_STATE) # GRL 6.3
590 History List Management
592 "add_history(STRING)"
594 void add_history(str string)
595 "add_history_time(STRING)"
597 void add_history_time(str string) # GRL 5.0
598 "remove_history(WHICH)"
600 str remove_history(int which)
601 "free_history(HISTENT)"
603 Not implemented since Term::ReadLine::Gnu does not support the
604 member 'data' of HIST_ENTRY structure. remove_history() frees
605 the memory.
606 histdata_t free_history_entry(HIST_ENTRY *histent) # GRL 5.0
607 "replace_history_entry(WHICH, STRING)"
609 str replace_history_entry(int which, str string)
610 "clear_history"
612 void clear_history()
613 "StifleHistory(MAX)"
615 int stifle_history(int max|undef)
616 stifles the history list, remembering only the last "MAX" entries.
618 If "MAX" is undef, remembers all entries. This is a replacement of
619 "unstifle_history()".
620 "unstifle_history"
622 int unstifle_history()
623 This is equivalent with "stifle_history(undef)".
625 "history_is_stifled"
627 int history_is_stifled()
628 "SetHistory(LINE1 [, LINE2, ...])"
630 sets the history of input, from where it can be used if the actual
631 "readline" is present.
632 Information About the History List
634 "history_list"
636 Not implemented since not required for Perl.
637 HIST_ENTRY **history_list()
638 "where_history"
640 int where_history()
641 "current_history"
643 str current_history()
644 "history_get(OFFSET)"
646 str history_get(offset)
647 "history_get_time(OFFSET)"
649 time_t history_get_time(offset) # GRL 5.0
650 "history_total_bytes"
652 int history_total_bytes()
653 "GetHistory"
655 returns the history of input as a list, if actual "readline" is
656 present.
657 Moving Around the History List
659 "history_set_pos(POS)"
661 int history_set_pos(int pos)
662 "previous_history"
664 str previous_history()
665 "next_history"
667 str next_history()
668 Searching the History List
670 "history_search(STRING [,DIRECTION])"
672 int history_search(str string, int direction = -1)
673 "history_search_prefix(STRING [,DIRECTION])"
675 int history_search_prefix(str string, int direction = -1)
676 "history_search_pos(STRING [,DIRECTION [,POS]])"
678 int history_search_pos(str string,
679 int direction = -1,
680 int pos = where_history())
681 Managing the History File
683 "ReadHistory([FILENAME [,FROM [,TO]]])"
685 int read_history(str filename = '~/.history',
686 int from = 0, int to = -1)
687 int read_history_range(str filename = '~/.history',
689 int from = 0, int to = -1)
690 adds the contents of "FILENAME" to the history list, a line at a
692 time. If "FILENAME" is false, then read from ~/.history. Start
693 reading at line "FROM" and end at "TO". If "FROM" is omitted or
694 zero, start at the beginning. If "TO" is omitted or less than
695 "FROM", then read until the end of the file. Returns true if
696 successful, or false if not. "read_history()" is an alias of
697 "read_history_range()".
698 "WriteHistory([FILENAME])"
700 int write_history(str filename = '~/.history')
701 writes the current history to "FILENAME", overwriting "FILENAME" if
703 necessary. If "FILENAME" is false, then write the history list to
704 ~/.history. Returns true if successful, or false if not.
705 "append_history(NELEMENTS [,FILENAME])"
707 int append_history(int nelements, str filename = '~/.history')
708 "history_truncate_file([FILENAME [,NLINES]])"
710 int history_truncate_file(str filename = '~/.history',
711 int nlines = 0)
712 History Expansion
714 "history_expand(STRING)"
716 (int result, str expansion) history_expand(str string)
717 Note that this function returns "expansion" in the scalar context.
719 "get_history_event(STRING, CINDEX [,QCHAR])"
721 (str text, int cindex) = get_history_event(str string,
722 int cindex,
723 char qchar = '\0')
724 "history_tokenize(STRING)"
726 (@str) history_tokenize(str string)
727 "history_arg_extract(STRING, [FIRST [,LAST]])"
729 str history_arg_extract(str string, int first = 0, int last = '$')
730 "Term::ReadLine::Gnu" Variables
732 Following GNU Readline/History Library variables can be accessed by a
733 Perl program. See GNU Readline Library Manual
734 <http://cnswww.cns.cwru.edu/php/chet/readline/readline.html> and GNU
735 History Library Manual
736 <http://cnswww.cns.cwru.edu/php/chet/readline/history.html> for details
737 of each variable. You can access them by using "Attribs" methods.
738 Names of keys in this hash conform to standard conventions with the
739 leading "rl_" stripped.
740 Examples:
742 $attribs = $term->Attribs;
744 $v = $attribs->{library_version}; # rl_library_version
745 $v = $attribs->{history_base}; # history_base
746 Readline Variables
748 str rl_line_buffer
750 int rl_point
751 int rl_end
752 int rl_mark
753 int rl_done
754 int rl_num_chars_to_read (GRL 4.1)
755 int rl_pending_input
756 int rl_dispatching
757 int rl_erase_empty_line (GRL 4.0)
758 str rl_prompt (read only)
759 str rl_display_prompt
760 int rl_already_prompted (GRL 4.1)
761 str rl_library_version (read only)
762 int rl_readline_version (read only)
763 int rl_gnu_readline_p (GRL 4.1, read only)
764 str rl_terminal_name
765 str rl_readline_name
766 filehandle rl_instream
767 filehandle rl_outstream
768 int rl_prefer_env_winsize (GRL 5.1)
769 pfunc rl_last_func (GRL 4.2, read only)
770 pfunc rl_startup_hook
771 pfunc rl_pre_input_hook (GRL 4.0)
772 pfunc rl_event_hook
773 pfunc rl_getc_function
774 pfunc rl_signal_event_hook (GRL 6.3)
775 pfunc rl_input_available_hook (GRL 6.3)
776 pfunc rl_redisplay_function
777 pfunc rl_prep_term_function (GRL 2.1)
778 pfunc rl_deprep_term_function (GRL 2.1)
779 Keymap rl_executing_keymap (read only)
780 Keymap rl_binding_keymap (read only)
781 str rl_executing_macro (GRL 4.2, read only)
782 int rl_executing_key (GRL 6.3, read only)
783 str rl_executing_keyseq (GRL 6.3, read only)
784 int rl_key_sequence_length (read only)
785 int rl_readline_state (GRL 4.2)
786 int rl_explicit_arg (read only)
787 int rl_numeric_arg (read only)
788 int rl_editing_mode (read only)
789 Signal Handling Variables
791 int rl_catch_signals (GRL 4.0)
793 int rl_catch_sigwinch (GRL 4.0)
794 int rl_persistent_signal_handlers (GRL 7.0)
795 int rl_change_environment (GRL 6.3)
796 Completion Variables
798 pfunc rl_completion_entry_function
800 pfunc rl_attempted_completion_function
801 pfunc rl_filename_quoting_function
802 pfunc rl_filename_dequoting_function
803 pfunc rl_char_is_quoted_p
804 pfunc rl_ignore_some_completions_function
805 pfunc rl_directory_completion_hook
806 pfunc rl_directory_rewrite_hook (GRL 4.2)
807 pfunc rl_filename_stat_hook (GRL 6.3)
808 pfunc rl_filename_rewrite_hook (GRL 6.1)
809 pfunc rl_completion_display_matches_hook (GRL 4.0)
810 str rl_basic_word_break_characters
811 str rl_basic_quote_characters
812 str rl_completer_word_break_characters
813 pfunc rl_completion_word_break_hook (GRL 5.0)
814 str rl_completer_quote_characters
815 str rl_filename_quote_characters
816 str rl_special_prefixes
817 int rl_completion_query_items
818 int rl_completion_append_character
819 int rl_completion_suppress_append (GRL 4.3)
820 int rl_completion_quote_character (GRL 5.0, read only)
821 int rl_completion_suppress_quote (GRL 5.0)
822 int rl_completion_found_quote (GRL 5.0, read only)
823 int rl_completion_mark_symlink_dirs (GRL 4.3)
824 int rl_ignore_completion_duplicates
825 int rl_filename_completion_desired
826 int rl_filename_quoting_desired
827 int rl_attempted_completion_over
828 int rl_sort_completion_matches (GRL 6.0)
829 int rl_completion_type (read only)
830 int rl_completion_invoking_key (GRL 6.0, read only)
831 int rl_inhibit_completion
832 History Variables
834 int history_base
836 int history_length
837 int history_max_entries (called `max_input_history', read only)
838 int history_write_timestamps (GRL 5.0)
839 char history_expansion_char
840 char history_subst_char
841 char history_comment_char
842 str history_word_delimiters (GRL 4.2)
843 str history_search_delimiter_chars
844 str history_no_expand_chars
845 int history_quotes_inhibit_expansion
846 pfunc history_inhibit_expansion_function
847 Function References
849 rl_getc
851 rl_redisplay
852 rl_callback_read_char
853 rl_display_match_list
854 rl_filename_completion_function
855 rl_username_completion_function
856 list_completion_function
857 shadow_redisplay
858 Tk_getc
859 Custom Completion
861 In this section variables and functions for custom completion are
862 described along with examples.
863 Most of descriptions in this section came from GNU Readline Library
865 Manual <http://cnswww.cns.cwru.edu/php/chet/readline/readline.html>.
866 "completion_entry_function"
868 This variable holds reference refers to a generator function for
869 "completion_matches()".
870 A generator function is called repeatedly from
872 "completion_matches()", returning a string each time. The
873 arguments to the generator function are "TEXT" and "STATE". "TEXT"
874 is the partial word to be completed. "STATE" is zero the first
875 time the function is called, allowing the generator to perform any
876 necessary initialization, and a positive non-zero integer for each
877 subsequent call. When the generator function returns "undef" this
878 signals "completion_matches()" that there are no more possibilities
879 left.
880 If this variable set to undef, built-in
882 "filename_completion_function" is used.
883 A sample generator function, "list_completion_function", is defined
885 in Gnu.pm. You can use it as follows;
886 use Term::ReadLine;
888 ...
889 my $term = new Term::ReadLine 'sample';
890 my $attribs = $term->Attribs;
891 ...
892 $attribs->{completion_entry_function} =
893 $attribs->{list_completion_function};
894 ...
895 $attribs->{completion_word} =
896 [qw(reference to a list of words which you want to use for completion)];
897 $term->readline("custom completion>");
898 See also "completion_matches".
900 "attempted_completion_function"
902 A reference to an alternative function to create matches.
903 The function is called with "TEXT", "LINE_BUFFER", "START", and
905 "END". "LINE_BUFFER" is a current input buffer string. "START"
906 and "END" are indices in "LINE_BUFFER" saying what the boundaries
907 of "TEXT" are.
908 If this function exists and returns null list or "undef", or if
910 this variable is set to "undef", then an internal function
911 "rl_complete()" will call the value of "completion_entry_function"
912 to generate matches, otherwise the array of strings returned will
913 be used.
914 The default value of this variable is "undef". You can use it as
916 follows;
917 use Term::ReadLine;
919 ...
920 my $term = new Term::ReadLine 'sample';
921 my $attribs = $term->Attribs;
922 ...
923 sub sample_completion {
924 my ($text, $line, $start, $end) = @_;
925 # If first word then username completion, else filename completion
926 if (substr($line, 0, $start) =~ /^\s*$/) {
927 return $term->completion_matches($text,
928 $attribs->{'username_completion_function'});
929 } else {
930 return ();
931 }
932 }
933 ...
934 $attribs->{attempted_completion_function} = \&sample_completion;
935 "completion_matches(TEXT, ENTRY_FUNC)"
937 Returns an array of strings which is a list of completions for
938 "TEXT". If there are no completions, returns "undef". The first
939 entry in the returned array is the substitution for "TEXT". The
940 remaining entries are the possible completions.
941 "ENTRY_FUNC" is a generator function which has two arguments, and
943 returns a string. The first argument is "TEXT". The second is a
944 state argument; it is zero on the first call, and non-zero on
945 subsequent calls. "ENTRY_FUNC" returns "undef" to the caller when
946 there are no more matches.
947 If the value of "ENTRY_FUNC" is undef, built-in
949 "filename_completion_function" is used.
950 "completion_matches" is a Perl wrapper function of an internal
952 function "completion_matches()". See also
953 "completion_entry_function".
954 "completion_function"
956 A variable whose content is a reference to a function which returns
957 a list of candidates to complete.
958 This variable is compatible with Term::ReadLine::Perl
960 <http://search.cpan.org/dist/Term-ReadLine-Perl/> and very easy to
961 use.
962 use Term::ReadLine;
964 ...
965 my $term = new Term::ReadLine 'sample';
966 my $attribs = $term->Attribs;
967 ...
968 $attribs->{completion_function} = sub {
969 my ($text, $line, $start) = @_;
970 return qw(a list of candidates to complete);
971 };
972 "list_completion_function(TEXT, STATE)"
974 A sample generator function defined by "Term::ReadLine::Gnu".
975 Example code at "completion_entry_function" shows how to use this
976 function.
977 "Term::ReadLine::Gnu" Specific Features
979 "Term::ReadLine::Gnu" Specific Functions
980 "CallbackHandlerInstall(PROMPT, LHANDLER)"
982 This method provides the function "rl_callback_handler_install()"
983 with the following additional feature compatible with "readline"
984 method; ornament feature, Term::ReadLine::Perl
985 <http://search.cpan.org/dist/Term-ReadLine-Perl/> compatible
986 completion function, history expansion, and addition to history
987 buffer.
988 "call_function(FUNCTION, [COUNT [,KEY]])"
990 int rl_call_function(FunctionPtr|str function, count = 1, key = -1)
991 "get_all_function_names"
993 Returns a list of all function names.
994 "shadow_redisplay"
996 A redisplay function for password input. You can use it as
997 follows;
998 $attribs->{redisplay_function} = $attribs->{shadow_redisplay};
1000 $line = $term->readline("password> ");
1001 "filename_list"
1003 Returns candidates of filenames to complete. This function can be
1004 used with "completion_function" and is implemented for the
1005 compatibility with Term::ReadLine::Perl
1006 <http://search.cpan.org/dist/Term-ReadLine-Perl/>.
1007 "list_completion_function"
1009 See the description of section "Custom Completion".
1010 "Term::ReadLine::Gnu" Specific Variables
1012 "do_expand"
1014 When true, the history expansion is enabled. By default false.
1015 "completion_function"
1017 See the description of section "Custom Completion".
1018 "completion_word"
1020 A reference to a list of candidates to complete for
1021 "list_completion_function".
1022 "Term::ReadLine::Gnu" Specific Commands
1024 "history-expand-line"
1026 The equivalent of the Bash "history-expand-line" editing command.
1027 "operate-and-get-next"
1029 The equivalent of the Korn shell
1030 "operate-and-get-next-history-line" editing command and the Bash
1031 "operate-and-get-next".
1032 This command is bound to "\C-o" by default for the compatibility
1034 with the Bash and Term::ReadLine::Perl
1035 <http://search.cpan.org/dist/Term-ReadLine-Perl/>.
1036 "display-readline-version"
1038 Shows the version of "Term::ReadLine::Gnu" and the one of the GNU
1039 Readline Library.
1040 "change-ornaments"
1042 Change ornaments interactively.
1043
1045 ~/.inputrc
1046 Readline init file. Using this file it is possible that you would
1047 like to use a different set of key bindings. When a program which
1048 uses the GNU Readline library starts up, the init file is read, and
1049 the key bindings are set.
1050 The conditional init constructs is supported. The program name
1052 which is specified by the first argument of "new" method is used as
1053 the application construct.
1054 For example, when your program calls "new" method as follows;
1056 ...
1058 $term = new Term::ReadLine 'PerlSh';
1059 ...
1060 your ~/.inputrc can define key bindings only for the program as
1062 follows;
1063 ...
1065 $if PerlSh
1066 Meta-Rubout: backward-kill-word
1067 "\C-x\C-r": re-read-init-file
1068 "\e[11~": "Function Key 1"
1069 $endif
1070 ...
1071 For further details, see the section "Readline Init File" in the
1073 GNU Readline Library Manual
1074 <http://cnswww.cns.cwru.edu/php/chet/readline/readline.html>
1075
1077 No symbols are exported by default. The following tags are defined and
1078 their symbols can be exported.
1079 prompt
1081 RL_PROMPT_START_IGNORE RL_PROMPT_END_IGNORE
1082 match_type
1084 NO_MATCH SINGLE_MATCH MULT_MATCH
1085 keymap_type
1087 ISFUNC ISKMAP ISMACR
1088 undo_code
1090 UNDO_DELETE UNDO_INSERT UNDO_BEGIN UNDO_END
1091 rl_state
1093 RL_STATE_NONE RL_STATE_INITIALIZING RL_STATE_INITIALIZED
1094 RL_STATE_TERMPREPPED RL_STATE_READCMD RL_STATE_METANEXT
1095 RL_STATE_DISPATCHING RL_STATE_MOREINPUT RL_STATE_ISEARCH
1096 RL_STATE_NSEARCH RL_STATE_SEARCH RL_STATE_NUMERICARG
1097 RL_STATE_MACROINPUT RL_STATE_MACRODEF RL_STATE_OVERWRITE
1098 RL_STATE_COMPLETING RL_STATE_SIGHANDLER RL_STATE_UNDOING
1099 RL_STATE_INPUTPENDING RL_STATE_TTYCSAVED RL_STATE_CALLBACK
1100 RL_STATE_VIMOTION RL_STATE_MULTIKEY RL_STATE_VICMDONCE
1101 RL_STATE_CHARSEARCH RL_STATE_REDISPLAYING RL_STATE_DONE
1102 They can be exported as follows;
1104 use Term::ReadLine;
1106 BEGIN {
1107 import Term::ReadLine::Gnu qw(:keymap_type RL_STATE_INITIALIZED);
1108 }
1109
1111 The environment variable "PERL_RL" governs which ReadLine clone is
1112 loaded. See the ENVIRONMENT section on Term::ReadLine
1113 <http://search.cpan.org/dist/Term-ReadLine/> for further details.
1114
1116 Term::ReadLine::Gnu Project Home Page
1117 <http://sourceforge.net/projects/perl-trg/>
1118 GNU Readline Library Manual
1119 <http://cnswww.cns.cwru.edu/php/chet/readline/readline.html>
1120 GNU History Library Manual
1121 <http://cnswww.cns.cwru.edu/php/chet/readline/history.html>
1122 Sample and test programs (eg/* and t/*) in the "Term::ReadLine::Gnu"
1123 distribution <http://search.cpan.org/dist/Term-ReadLine-Gnu/>
1124 Term::ReadLine <http://search.cpan.org/dist/Term-ReadLine/>
1125 Works which use Term::ReadLine::Gnu
1126 Distributions which depend on Term::ReadLine::Gnu on CPAN
1127 <http://www.cpan.org/>
1128 <https://metacpan.org/requires/distribution/Term-ReadLine-Gnu>
1129 Perl Debugger <http://perldoc.perl.org/perldebug.html>
1131 perl -d
1132 Perl Shell (psh) <http://gnp.github.io/psh/>
1134 The Perl Shell is a shell that combines the interactive nature
1135 of a Unix shell with the power of Perl.
1136 A programmable completion feature compatible with bash is
1138 implemented.
1139 SPP (Synopsys Plus Perl)
1141 <http://vlsiweb.stanford.edu/~jsolomon/SPP/>
1142 SPP (Synopsys Plus Perl) is a Perl module that wraps around
1143 Synopsys' shell programs. SPP is inspired by the original
1144 dc_perl written by Steve Golson, but it's an entirely new
1145 implementation. Why is it called SPP and not dc_perl? Well,
1146 SPP was written to wrap around any of Synopsys' shells.
1147 PFM (Personal File Manager for Unix/Linux) <http://p-f-
1149 m.sourceforge.net/>
1150 Pfm is a terminal-based file manager written in Perl, based on
1151 PFM.COM for MS-DOS (originally by Paul Culley and Henk de
1152 Heer).
1153 The soundgrab <http://brittonkerin.com/soundgrab/soundgrab.html>
1155 soundgrab is designed to help you slice up a big long raw audio
1156 file (by default 44.1 kHz 2 channel signed sixteen bit little
1157 endian) and save your favorite sections to other files. It does
1158 this by providing you with a cassette player like command line
1159 interface.
1160 PDL (The Perl Data Language) <http://pdl.perl.org/>
1162 PDL (``Perl Data Language'') gives standard Perl the ability to
1163 compactly store and speedily manipulate the large N-dimensional
1164 data arrays which are the bread and butter of scientific
1165 computing.
1166 PIQT (Perl Interactive DBI Query Tool)
1168 <http://piqt.sourceforge.net/>
1169 PIQT is an interactive query tool using the Perl DBI database
1170 interface. It supports ReadLine, provides a built in scripting
1171 language with a Lisp like syntax, an online help system, and
1172 uses wrappers to interface to the DBD modules.
1173 vshnu (the New Visual Shell)
1175 <http://www.cs.indiana.edu/~kinzler/vshnu/>
1176 A visual shell and CLI shell supplement.
1177 If you know any other works you recommend, please let me know.
1179
1181 Hiroo Hayashi "<hiroo.hayashi@computer.org>"
1182 <http://search.cpan.org/~hayashi/>
1184
1186 GTK+ support in addition to Tk.
1187
1189 Submit a bug report to rt.cpan.org
1190 <https://rt.cpan.org/Dist/Display.html?Name=Term-ReadLine-Gnu>.
1191 "add_defun()" can define up to 16 functions.
1192 Some functions and variables do not have test code yet. Your
1193 contribution is welcome. See t/readline.t for details.
1194 If the pager command (| or ||) in Perl debugger causes segmentation
1195 fault, you need to fix perl5db.pl. See
1196 <https://rt.perl.org/Public/Bug/Display.html?id=121456> for details.
1197
1199 Copyright (c) 1996-2016 Hiroo Hayashi. All rights reserved.
1200 This program is free software; you can redistribute it and/or modify it
1202 under the same terms as Perl itself.
1203perl v5.28.0 2018-07-20 Gnu(3)