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 <https://tiswww.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 <https://tiswww.cwru.edu/php/chet/readline/readline.html> and
33 GNU History Library Manual
34 <https://tiswww.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 <https://tiswww.cwru.edu/php/chet/readline/readline.html>. Refer them
148 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 <https://tiswww.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 <https://tiswww.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 "empty_keymap(MAP)"
229 int rl_empty_keymap(Keymap|str map) # GRL 8.0
230 "get_keymap"
232 Keymap rl_get_keymap()
233 "set_keymap(MAP)"
235 Keymap rl_set_keymap(Keymap|str map)
236 "get_keymap_by_name(NAME)"
238 Keymap rl_get_keymap_by_name(str name)
239 "get_keymap_name(MAP)"
241 str rl_get_keymap_name(Keymap map)
242 "set_keymap_name(NAME, MAP)"
244 int rl_set_keymap_name(str name, Keymap|str map) # GRL 8.0
245 Binding Keys
247 "bind_key(KEY, FUNCTION [,MAP])"
249 int rl_bind_key(int key, FunctionPtr|str function,
250 Keymap|str map = rl_get_keymap())
251 Bind "KEY" to the "FUNCTION". "FUNCTION" is the name added by the
253 "add_defun" method. If optional argument "MAP" is specified, binds
254 in "MAP". Returns non-zero in case of error.
255 "bind_key_if_unbound(KEY, FUNCTION [,MAP])"
257 int rl_bind_key_if_unbound(int key, FunctionPtr|str function,
258 Keymap|str map = rl_get_keymap()) # GRL 5.0
259 "unbind_key(KEY [,MAP])"
261 int rl_unbind_key(int key, Keymap|str map = rl_get_keymap())
262 Bind "KEY" to the null function. Returns non-zero in case of
264 error.
265 "unbind_function(FUNCTION [,MAP])"
267 int rl_unbind_function(FunctionPtr|str function,
268 Keymap|str map = rl_get_keymap())
269 "unbind_command(COMMAND [,MAP])"
271 int rl_unbind_command(str command,
272 Keymap|str map = rl_get_keymap())
273 "bind_keyseq(KEYSEQ, FUNCTION [,MAP])"
275 int rl_bind_keyseq(str keyseq, FunctionPtr|str function,
276 Keymap|str map = rl_get_keymap()) # GRL 5.0
277 "set_key(KEYSEQ, FUNCTION [,MAP])"
279 int rl_set_key(str keyseq, FunctionPtr|str function,
280 Keymap|str map = rl_get_keymap()) # GRL 4.2
281 "bind_keyseq_if_unbound(KEYSEQ, FUNCTION [,MAP])"
283 int rl_bind_keyseq_if_unbound(str keyseq, FunctionPtr|str function,
284 Keymap|str map = rl_get_keymap()) # GRL 5.0
285 "generic_bind(TYPE, KEYSEQ, DATA, [,MAP])"
287 int rl_generic_bind(int type, str keyseq,
288 FunctionPtr|Keymap|str data,
289 Keymap|str map = rl_get_keymap())
290 "parse_and_bind(LINE)"
292 void rl_parse_and_bind(str line)
293 Parse "LINE" as if it had been read from the ~/.inputrc file and
295 perform any key bindings and variable assignments found. For
296 further detail see GNU Readline Library Manual
297 <https://tiswww.cwru.edu/php/chet/readline/readline.html>.
298 "read_init_file([FILENAME])"
300 int rl_read_init_file(str filename = '~/.inputrc')
301 Associating Function Names and Bindings
303 "named_function(NAME)"
305 FunctionPtr rl_named_function(str name)
306 "get_function_name(FUNCTION)"
308 str rl_get_function_name(FunctionPtr function) # TRG original
309 "function_of_keyseq(KEYSEQ [,MAP])"
311 (FunctionPtr|Keymap|str data, int type)
312 rl_function_of_keyseq(str keyseq,
313 Keymap|str map = rl_get_keymap())
314 "invoking_keyseqs(FUNCTION [,MAP])"
316 (@str) rl_invoking_keyseqs(FunctionPtr|str function,
317 Keymap|str map = rl_get_keymap())
318 "function_dumper([READABLE])"
320 void rl_function_dumper(int readable = 0)
321 "list_funmap_names"
323 void rl_list_funmap_names()
324 "funmap_names"
326 (@str) rl_funmap_names()
327 "add_funmap_entry(NAME, FUNCTION)"
329 int rl_add_funmap_entry(char *name, FunctionPtr|str function)
330 Allowing Undoing
332 "begin_undo_group"
334 int rl_begin_undo_group()
335 "end_undo_group"
337 int rl_end_undo_group()
338 "add_undo(WHAT, START, END, TEXT)"
340 int rl_add_undo(int what, int start, int end, str text)
341 "free_undo_list"
343 void rl_free_undo_list()
344 "do_undo"
346 int rl_do_undo()
347 "modifying([START [,END]])"
349 int rl_modifying(int start = 0, int end = rl_end)
350 Redisplay
352 "redisplay"
354 void rl_redisplay()
355 "forced_update_display"
357 int rl_forced_update_display()
358 "on_new_line"
360 int rl_on_new_line()
361 "on_new_line_with_prompt"
363 int rl_on_new_line_with_prompt() # GRL 4.1
364 "clear_visible_line()"
366 int rl_clear_visible_line() # GRL 7.0
367 "reset_line_state"
369 int rl_reset_line_state()
370 "crlf"
372 int rl_crlf()
373 show_char(C)
375 int rl_show_char(int c)
376 "message(FMT[, ...])"
378 int rl_message(str fmt, ...)
379 "clear_message"
381 int rl_clear_message()
382 "save_prompt"
384 void rl_save_prompt()
385 "restore_prompt"
387 void rl_restore_prompt()
388 "expand_prompt(PROMPT)"
390 int rl_expand_prompt(str prompt)
391 "set_prompt(PROMPT)"
393 int rl_set_prompt(const str prompt) # GRL 4.2
394 Modifying Text
396 "insert_text(TEXT)"
398 int rl_insert_text(str text)
399 "delete_text([START [,END]])"
401 int rl_delete_text(int start = 0, int end = rl_end)
402 "copy_text([START [,END]])"
404 str rl_copy_text(int start = 0, int end = rl_end)
405 "kill_text([START [,END]])"
407 int rl_kill_text(int start = 0, int end = rl_end)
408 "push_macro_input(MACRO)"
410 int rl_push_macro_input(str macro)
411 Character Input
413 "read_key"
415 int rl_read_key()
416 "getc(STREAM)"
418 int rl_getc(FILE *STREAM)
419 stuff_char(C)
421 int rl_stuff_char(int c)
422 execute_next(C)
424 int rl_execute_next(int c)
425 "clear_pending_input()"
427 int rl_clear_pending_input() # GRL 4.2
428 "set_keyboard_input_timeout(uSEC)"
430 int rl_set_keyboard_input_timeout(int usec) # GRL 4.2
431 Terminal Management
433 "prep_terminal(META_FLAG)"
435 void rl_prep_terminal(int META_FLAG)
436 "deprep_terminal()"
438 void rl_deprep_terminal()
439 "tty_set_default_bindings([MAP])"
441 void rl_tty_set_default_bindings([Keymap|str map = rl_get_keymap()]) # GRL 4.0
442 "tty_unset_default_bindings([MAP])"
444 void rl_tty_unset_default_bindings([Keymap|str map = rl_get_keymap()]) # GRL 5.0
445 "tty_set_echoing(VALUE)"
447 int rl_tty_set_echoing(int value) # GRL 7.0
448 "reset_terminal([TERMINAL_NAME])"
450 int rl_reset_terminal(str terminal_name = getenv($TERM))
451 Utility Functions
453 "save_state(READLINE_STATE)"
455 READLINE_STATE rl_save_state() # GRL 6.0
456 "restore_state(READLINE_STATE)"
458 int rl_restore_state(READLINE_STATE) # GRL 6.0
459 "free(MEM)"
461 Not implemented since not required for Perl.
462 int rl_free(void *mem) # GRL 6.0
463 "replace_line(TEXT [,CLEAR_UNDO])"
465 int rl_replace_line(str text, int clear_undo = 0) # GRL 4.3
466 "extend_line_buffer(LEN)"
468 Not implemented since not required for Perl.
469 int rl_extend_line_buffer(int len)
470 "initialize"
472 int rl_initialize()
473 "ding"
475 int rl_ding()
476 alphabetic(C)
478 int rl_alphabetic(int C) # GRL 4.2
479 "display_match_list(MATCHES [,LEN [,MAX]])"
481 void rl_display_match_list(\@matches, len = $#maches, max) # GRL 4.0
482 Since the first element of an array @matches as treated as a
484 possible completion, it is not displayed. See the descriptions of
485 "completion_matches()". When "MAX" is omitted, the max length of
486 an item in @matches is used.
487 Miscellaneous Functions
489 "macro_bind(KEYSEQ, MACRO [,MAP])"
491 int rl_macro_bind(const str keyseq, const str macro, Keymap map)
492 "macro_dumper(READABLE)"
494 int rl_macro_dumper(int readline)
495 "variable_bind(VARIABLE, VALUE)"
497 int rl_variable_bind(const str variable, const str value)
498 "variable_value(VARIABLE)"
500 str rl_variable_value(const str variable) # GRL 5.1
501 "variable_dumper(READABLE)"
503 int rl_variable_dumper(int readline)
504 "set_paren_blink_timeout(uSEC)"
506 int rl_set_paren_blink_timeout(usec) # GRL 4.2
507 "get_termcap(cap)"
509 str rl_get_termcap(cap)
510 "clear_history"
512 void rl_clear_history() # GRL 6.3
513 Alternate Interface
515 "callback_handler_install(PROMPT, LHANDLER)"
517 void rl_callback_handler_install(str prompt, pfunc lhandler)
518 "callback_read_char"
520 void rl_callback_read_char()
521 "callback_sigcleanup" # GRL 7.0
523 void rl_callback_sigcleanup()
524 "callback_handler_remove"
526 void rl_callback_handler_remove()
527 Readline Signal Handling
529 "pending_signal()"
531 int rl_pending_signal() # GRL 7.0
532 "cleanup_after_signal"
534 void rl_cleanup_after_signal() # GRL 4.0
535 "free_line_state"
537 void rl_free_line_state() # GRL 4.0
538 "reset_after_signal"
540 void rl_reset_after_signal() # GRL 4.0
541 "check_signals"
543 void rl_check_signals() # GRL 8.0
544 "echo_signal_char"
546 void rl_echo_signal_char(int sig) # GRL 6.0
547 "resize_terminal"
549 void rl_resize_terminal() # GRL 4.0
550 "set_screen_size(ROWS, COLS)"
552 void rl_set_screen_size(int ROWS, int COLS) # GRL 4.2
553 "get_screen_size()"
555 (int rows, int cols) rl_get_screen_size() # GRL 4.2
556 "reset_screen_size()"
558 void rl_reset_screen_size() # GRL 5.1
559 "set_signals"
561 int rl_set_signals() # GRL 4.0
562 "clear_signals"
564 int rl_clear_signals() # GRL 4.0
565 Completion Functions
567 "complete_internal([WHAT_TO_DO])"
569 int rl_complete_internal(int what_to_do = TAB)
570 "completion_mode(FUNCTION)"
572 int rl_completion_mode(FunctionPtr|str function) # GRL 4.3
573 "completion_matches(TEXT [,FUNC])"
575 (@str) rl_completion_matches(str text,
576 pfunc func = filename_completion_function)
577 "filename_completion_function(TEXT, STATE)"
579 str rl_filename_completion_function(str text, int state)
580 "username_completion_function(TEXT, STATE)"
582 str rl_username_completion_function(str text, int state)
583 "list_completion_function(TEXT, STATE)"
585 str list_completion_function(str text, int state) # TRG original
586 History Functions
588 Initializing History and State Management
590 "using_history"
592 void using_history()
593 "history_get_history_state"
595 HISTORY_STATE history_get_hitory_state() # GRL 6.3
596 "history_set_history_state"
598 void history_set_hitory_state(HISTORY_STATE) # GRL 6.3
599 History List Management
601 "add_history(STRING)"
603 void add_history(str string)
604 "add_history_time(STRING)"
606 void add_history_time(str string) # GRL 5.0
607 "remove_history(WHICH)"
609 str remove_history(int which)
610 "free_history(HISTENT)"
612 Not implemented since Term::ReadLine::Gnu does not support the
613 member 'data' of HIST_ENTRY structure. remove_history() frees
614 the memory.
615 histdata_t free_history_entry(HIST_ENTRY *histent) # GRL 5.0
616 "replace_history_entry(WHICH, STRING)"
618 str replace_history_entry(int which, str string)
619 "clear_history"
621 void clear_history()
622 "StifleHistory(MAX)"
624 int stifle_history(int max|undef)
625 stifles the history list, remembering only the last "MAX" entries.
627 If "MAX" is undef, remembers all entries. This is a replacement of
628 "unstifle_history()".
629 "unstifle_history"
631 int unstifle_history()
632 This is equivalent with "stifle_history(undef)".
634 "history_is_stifled"
636 int history_is_stifled()
637 "SetHistory(LINE1 [, LINE2, ...])"
639 sets the history of input, from where it can be used if the actual
640 "readline" is present.
641 Information About the History List
643 "history_list"
645 Not implemented since not required for Perl.
646 HIST_ENTRY **history_list()
647 "where_history"
649 int where_history()
650 "current_history"
652 str current_history()
653 "history_get(OFFSET)"
655 str history_get(offset)
656 "history_get_time(OFFSET)"
658 time_t history_get_time(offset) # GRL 5.0
659 "history_total_bytes"
661 int history_total_bytes()
662 "GetHistory"
664 returns the history of input as a list, if actual "readline" is
665 present.
666 Moving Around the History List
668 "history_set_pos(POS)"
670 int history_set_pos(int pos)
671 "previous_history"
673 str previous_history()
674 "next_history"
676 str next_history()
677 Searching the History List
679 "history_search(STRING [,DIRECTION])"
681 int history_search(str string, int direction = -1)
682 "history_search_prefix(STRING [,DIRECTION])"
684 int history_search_prefix(str string, int direction = -1)
685 "history_search_pos(STRING [,DIRECTION [,POS]])"
687 int history_search_pos(str string,
688 int direction = -1,
689 int pos = where_history())
690 Managing the History File
692 "ReadHistory([FILENAME [,FROM [,TO]]])"
694 int read_history(str filename = '~/.history',
695 int from = 0, int to = -1)
696 int read_history_range(str filename = '~/.history',
698 int from = 0, int to = -1)
699 adds the contents of "FILENAME" to the history list, a line at a
701 time. If "FILENAME" is false, then read from ~/.history. Start
702 reading at line "FROM" and end at "TO". If "FROM" is omitted or
703 zero, start at the beginning. If "TO" is omitted or less than
704 "FROM", then read until the end of the file. Returns true if
705 successful, or false if not. "read_history()" is an alias of
706 "read_history_range()".
707 "WriteHistory([FILENAME])"
709 int write_history(str filename = '~/.history')
710 writes the current history to "FILENAME", overwriting "FILENAME" if
712 necessary. If "FILENAME" is false, then write the history list to
713 ~/.history. Returns true if successful, or false if not.
714 "append_history(NELEMENTS [,FILENAME])"
716 int append_history(int nelements, str filename = '~/.history')
717 "history_truncate_file([FILENAME [,NLINES]])"
719 int history_truncate_file(str filename = '~/.history',
720 int nlines = 0)
721 History Expansion
723 "history_expand(STRING)"
725 (int result, str expansion) history_expand(str string)
726 Note that this function returns "expansion" in the scalar context.
728 "get_history_event(STRING, CINDEX [,QCHAR])"
730 (str text, int cindex) = get_history_event(str string,
731 int cindex,
732 char qchar = '\0')
733 "history_tokenize(STRING)"
735 (@str) history_tokenize(str string)
736 "history_arg_extract(STRING, [FIRST [,LAST]])"
738 str history_arg_extract(str string, int first = 0, int last = '$')
739 "Term::ReadLine::Gnu" Variables
741 Following GNU Readline/History Library variables can be accessed by a
742 Perl program. See GNU Readline Library Manual
743 <https://tiswww.cwru.edu/php/chet/readline/readline.html> and GNU
744 History Library Manual
745 <https://tiswww.cwru.edu/php/chet/readline/history.html> for details of
746 each variable. You can access them by using "Attribs" methods. Names
747 of keys in this hash conform to standard conventions with the leading
748 "rl_" stripped.
749 Examples:
751 $attribs = $term->Attribs;
753 $v = $attribs->{library_version}; # rl_library_version
754 $v = $attribs->{history_base}; # history_base
755 Readline Variables
757 str rl_line_buffer
759 int rl_point
760 int rl_end
761 int rl_mark
762 int rl_done
763 int rl_num_chars_to_read (GRL 4.1)
764 int rl_pending_input
765 int rl_dispatching
766 int rl_erase_empty_line (GRL 4.0)
767 str rl_prompt (read only)
768 str rl_display_prompt
769 int rl_already_prompted (GRL 4.1)
770 str rl_library_version (read only)
771 int rl_readline_version (read only)
772 int rl_gnu_readline_p (GRL 4.1, read only)
773 str rl_terminal_name
774 str rl_readline_name
775 filehandle rl_instream
776 filehandle rl_outstream
777 int rl_prefer_env_winsize (GRL 5.1)
778 pfunc rl_last_func (GRL 4.2, read only)
779 pfunc rl_startup_hook
780 pfunc rl_pre_input_hook (GRL 4.0)
781 pfunc rl_event_hook
782 pfunc rl_getc_function
783 pfunc rl_signal_event_hook (GRL 6.3)
784 pfunc rl_input_available_hook (GRL 6.3)
785 pfunc rl_redisplay_function
786 pfunc rl_prep_term_function (GRL 2.1)
787 pfunc rl_deprep_term_function (GRL 2.1)
788 Keymap rl_executing_keymap (read only)
789 Keymap rl_binding_keymap (read only)
790 str rl_executing_macro (GRL 4.2, read only)
791 int rl_executing_key (GRL 6.3, read only)
792 str rl_executing_keyseq (GRL 6.3, read only)
793 int rl_key_sequence_length (read only)
794 int rl_readline_state (GRL 4.2)
795 int rl_explicit_arg (read only)
796 int rl_numeric_arg (read only)
797 int rl_editing_mode (read only)
798 Signal Handling Variables
800 int rl_catch_signals (GRL 4.0)
802 int rl_catch_sigwinch (GRL 4.0)
803 int rl_persistent_signal_handlers (GRL 7.0)
804 int rl_change_environment (GRL 6.3)
805 Completion Variables
807 pfunc rl_completion_entry_function
809 pfunc rl_attempted_completion_function
810 pfunc rl_filename_quoting_function
811 pfunc rl_filename_dequoting_function
812 pfunc rl_char_is_quoted_p
813 pfunc rl_ignore_some_completions_function
814 pfunc rl_directory_completion_hook
815 pfunc rl_directory_rewrite_hook (GRL 4.2)
816 pfunc rl_filename_stat_hook (GRL 6.3)
817 pfunc rl_filename_rewrite_hook (GRL 6.1)
818 pfunc rl_completion_display_matches_hook (GRL 4.0)
819 str rl_basic_word_break_characters
820 str rl_basic_quote_characters
821 str rl_completer_word_break_characters
822 pfunc rl_completion_word_break_hook (GRL 5.0)
823 str rl_completer_quote_characters
824 str rl_filename_quote_characters
825 str rl_special_prefixes
826 int rl_completion_query_items
827 int rl_completion_append_character
828 int rl_completion_suppress_append (GRL 4.3)
829 int rl_completion_quote_character (GRL 5.0, read only)
830 int rl_completion_suppress_quote (GRL 5.0)
831 int rl_completion_found_quote (GRL 5.0, read only)
832 int rl_completion_mark_symlink_dirs (GRL 4.3)
833 int rl_ignore_completion_duplicates
834 int rl_filename_completion_desired
835 int rl_filename_quoting_desired
836 int rl_attempted_completion_over
837 int rl_sort_completion_matches (GRL 6.0)
838 int rl_completion_type (read only)
839 int rl_completion_invoking_key (GRL 6.0, read only)
840 int rl_inhibit_completion
841 History Variables
843 int history_base
845 int history_length
846 int history_max_entries (called `max_input_history', read only)
847 int history_write_timestamps (GRL 5.0)
848 char history_expansion_char
849 char history_subst_char
850 char history_comment_char
851 str history_word_delimiters (GRL 4.2)
852 str history_search_delimiter_chars
853 str history_no_expand_chars
854 int history_quotes_inhibit_expansion
855 int history_quoting_state
856 pfunc history_inhibit_expansion_function
857 Function References
859 rl_getc
861 rl_redisplay
862 rl_callback_read_char
863 rl_display_match_list
864 rl_filename_completion_function
865 rl_username_completion_function
866 list_completion_function
867 shadow_redisplay
868 Tk_getc
869 Custom Completion
871 In this section variables and functions for custom completion are
872 described along with examples.
873 Most of descriptions in this section came from GNU Readline Library
875 Manual <https://tiswww.cwru.edu/php/chet/readline/readline.html>.
876 "completion_entry_function"
878 This variable holds reference refers to a generator function for
879 "completion_matches()".
880 A generator function is called repeatedly from
882 "completion_matches()", returning a string each time. The
883 arguments to the generator function are "TEXT" and "STATE". "TEXT"
884 is the partial word to be completed. "STATE" is zero the first
885 time the function is called, allowing the generator to perform any
886 necessary initialization, and a positive non-zero integer for each
887 subsequent call. When the generator function returns "undef" this
888 signals "completion_matches()" that there are no more possibilities
889 left.
890 If this variable set to undef, built-in
892 "filename_completion_function" is used.
893 A sample generator function, "list_completion_function", is defined
895 in Gnu.pm. You can use it as follows;
896 use Term::ReadLine;
898 ...
899 my $term = new Term::ReadLine 'sample';
900 my $attribs = $term->Attribs;
901 ...
902 $attribs->{completion_entry_function} =
903 $attribs->{list_completion_function};
904 ...
905 $attribs->{completion_word} =
906 [qw(reference to a list of words which you want to use for completion)];
907 $term->readline("custom completion>");
908 See also "completion_matches".
910 "attempted_completion_function"
912 A reference to an alternative function to create matches.
913 The function is called with "TEXT", "LINE_BUFFER", "START", and
915 "END". "LINE_BUFFER" is a current input buffer string. "START"
916 and "END" are indices in "LINE_BUFFER" saying what the boundaries
917 of "TEXT" are.
918 If this function exists and returns null list or "undef", or if
920 this variable is set to "undef", then an internal function
921 "rl_complete()" will call the value of "completion_entry_function"
922 to generate matches, otherwise the array of strings returned will
923 be used.
924 The default value of this variable is "undef". You can use it as
926 follows;
927 use Term::ReadLine;
929 ...
930 my $term = new Term::ReadLine 'sample';
931 my $attribs = $term->Attribs;
932 ...
933 sub sample_completion {
934 my ($text, $line, $start, $end) = @_;
935 # If first word then username completion, else filename completion
936 if (substr($line, 0, $start) =~ /^\s*$/) {
937 return $term->completion_matches($text,
938 $attribs->{'username_completion_function'});
939 } else {
940 return ();
941 }
942 }
943 ...
944 $attribs->{attempted_completion_function} = \&sample_completion;
945 "completion_matches(TEXT, ENTRY_FUNC)"
947 Returns an array of strings which is a list of completions for
948 "TEXT". If there are no completions, returns "undef". The first
949 entry in the returned array is the substitution for "TEXT". The
950 remaining entries are the possible completions.
951 "ENTRY_FUNC" is a generator function which has two arguments, and
953 returns a string. The first argument is "TEXT". The second is a
954 state argument; it is zero on the first call, and non-zero on
955 subsequent calls. "ENTRY_FUNC" returns "undef" to the caller when
956 there are no more matches.
957 If the value of "ENTRY_FUNC" is undef, built-in
959 "filename_completion_function" is used.
960 "completion_matches" is a Perl wrapper function of an internal
962 function "completion_matches()". See also
963 "completion_entry_function".
964 "completion_function"
966 A variable whose content is a reference to a function which returns
967 a list of candidates to complete.
968 This variable is compatible with Term::ReadLine::Perl
970 <http://search.cpan.org/dist/Term-ReadLine-Perl/> and very easy to
971 use.
972 use Term::ReadLine;
974 ...
975 my $term = new Term::ReadLine 'sample';
976 my $attribs = $term->Attribs;
977 ...
978 $attribs->{completion_function} = sub {
979 my ($text, $line, $start) = @_;
980 return qw(a list of candidates to complete);
981 };
982 "list_completion_function(TEXT, STATE)"
984 A sample generator function defined by "Term::ReadLine::Gnu".
985 Example code at "completion_entry_function" shows how to use this
986 function.
987 "Term::ReadLine::Gnu" Specific Features
989 "Term::ReadLine::Gnu" Specific Functions
990 "CallbackHandlerInstall(PROMPT, LHANDLER)"
992 This method provides the function "rl_callback_handler_install()"
993 with the following additional feature compatible with "readline"
994 method; ornament feature, Term::ReadLine::Perl
995 <http://search.cpan.org/dist/Term-ReadLine-Perl/> compatible
996 completion function, history expansion, and addition to history
997 buffer.
998 "call_function(FUNCTION, [COUNT [,KEY]])"
1000 int rl_call_function(FunctionPtr|str function, count = 1, key = -1)
1001 "get_all_function_names"
1003 Returns a list of all function names.
1004 "shadow_redisplay"
1006 A redisplay function for password input. You can use it as
1007 follows;
1008 $attribs->{redisplay_function} = $attribs->{shadow_redisplay};
1010 $line = $term->readline("password> ");
1011 "filename_list"
1013 Returns candidates of filenames to complete. This function can be
1014 used with "completion_function" and is implemented for the
1015 compatibility with Term::ReadLine::Perl
1016 <http://search.cpan.org/dist/Term-ReadLine-Perl/>.
1017 "list_completion_function"
1019 See the description of section "Custom Completion".
1020 "Term::ReadLine::Gnu" Specific Variables
1022 "do_expand"
1024 When true, the history expansion is enabled. By default false.
1025 "completion_function"
1027 See the description of section "Custom Completion".
1028 "completion_word"
1030 A reference to a list of candidates to complete for
1031 "list_completion_function".
1032 "Term::ReadLine::Gnu" Specific Commands
1034 "history-expand-line"
1036 The equivalent of the Bash "history-expand-line" editing command.
1037 "operate-and-get-next"
1039 The equivalent of the Korn shell
1040 "operate-and-get-next-history-line" editing command and the Bash
1041 "operate-and-get-next".
1042 This command is bound to "\C-o" by default for the compatibility
1044 with the Bash and Term::ReadLine::Perl
1045 <http://search.cpan.org/dist/Term-ReadLine-Perl/>.
1046 "display-readline-version"
1048 Shows the version of "Term::ReadLine::Gnu" and the one of the GNU
1049 Readline Library.
1050 "change-ornaments"
1052 Change ornaments interactively.
1053
1055 ~/.inputrc
1056 Readline init file. Using this file it is possible that you would
1057 like to use a different set of key bindings. When a program which
1058 uses the GNU Readline library starts up, the init file is read, and
1059 the key bindings are set.
1060 The conditional init constructs is supported. The program name
1062 which is specified by the first argument of "new" method is used as
1063 the application construct.
1064 For example, when your program calls "new" method as follows;
1066 ...
1068 $term = new Term::ReadLine 'PerlSh';
1069 ...
1070 your ~/.inputrc can define key bindings only for the program as
1072 follows;
1073 ...
1075 $if PerlSh
1076 Meta-Rubout: backward-kill-word
1077 "\C-x\C-r": re-read-init-file
1078 "\e[11~": "Function Key 1"
1079 $endif
1080 ...
1081 For further details, see the section "Readline Init File" in the
1083 GNU Readline Library Manual
1084 <https://tiswww.cwru.edu/php/chet/readline/readline.html>
1085
1087 No symbols are exported by default. The following tags are defined and
1088 their symbols can be exported.
1089 prompt
1091 RL_PROMPT_START_IGNORE RL_PROMPT_END_IGNORE
1092 match_type
1094 NO_MATCH SINGLE_MATCH MULT_MATCH
1095 keymap_type
1097 ISFUNC ISKMAP ISMACR
1098 undo_code
1100 UNDO_DELETE UNDO_INSERT UNDO_BEGIN UNDO_END
1101 rl_state
1103 RL_STATE_NONE RL_STATE_INITIALIZING RL_STATE_INITIALIZED
1104 RL_STATE_TERMPREPPED RL_STATE_READCMD RL_STATE_METANEXT
1105 RL_STATE_DISPATCHING RL_STATE_MOREINPUT RL_STATE_ISEARCH
1106 RL_STATE_NSEARCH RL_STATE_SEARCH RL_STATE_NUMERICARG
1107 RL_STATE_MACROINPUT RL_STATE_MACRODEF RL_STATE_OVERWRITE
1108 RL_STATE_COMPLETING RL_STATE_SIGHANDLER RL_STATE_UNDOING
1109 RL_STATE_INPUTPENDING RL_STATE_TTYCSAVED RL_STATE_CALLBACK
1110 RL_STATE_VIMOTION RL_STATE_MULTIKEY RL_STATE_VICMDONCE
1111 RL_STATE_CHARSEARCH RL_STATE_REDISPLAYING RL_STATE_DONE
1112 They can be exported as follows;
1114 use Term::ReadLine;
1116 BEGIN {
1117 import Term::ReadLine::Gnu qw(:keymap_type RL_STATE_INITIALIZED);
1118 }
1119
1121 The environment variable "PERL_RL" governs which ReadLine clone is
1122 loaded. See the ENVIRONMENT section on Term::ReadLine
1123 <http://search.cpan.org/dist/Term-ReadLine/> for further details.
1124
1126 Term::ReadLine::Gnu Project Home Page
1127 <http://sourceforge.net/projects/perl-trg/>
1128 GNU Readline Library Manual
1129 <https://tiswww.cwru.edu/php/chet/readline/readline.html>
1130 GNU History Library Manual
1131 <https://tiswww.cwru.edu/php/chet/readline/history.html>
1132 Sample and test programs (eg/* and t/*) in the "Term::ReadLine::Gnu"
1133 distribution <http://search.cpan.org/dist/Term-ReadLine-Gnu/>
1134 Term::ReadLine <http://search.cpan.org/dist/Term-ReadLine/>
1135 Works which use Term::ReadLine::Gnu
1136 Distributions which depend on Term::ReadLine::Gnu on CPAN
1137 <http://www.cpan.org/>
1138 <https://metacpan.org/requires/distribution/Term-ReadLine-Gnu>
1139 Perl Debugger <http://perldoc.perl.org/perldebug.html>
1141 perl -d
1142 Perl Shell (psh) <http://gnp.github.io/psh/>
1144 The Perl Shell is a shell that combines the interactive nature
1145 of a Unix shell with the power of Perl.
1146 A programmable completion feature compatible with bash is
1148 implemented.
1149 SPP (Synopsys Plus Perl)
1151 <http://vlsiweb.stanford.edu/~jsolomon/SPP/>
1152 SPP (Synopsys Plus Perl) is a Perl module that wraps around
1153 Synopsys' shell programs. SPP is inspired by the original
1154 dc_perl written by Steve Golson, but it's an entirely new
1155 implementation. Why is it called SPP and not dc_perl? Well,
1156 SPP was written to wrap around any of Synopsys' shells.
1157 PFM (Personal File Manager for Unix/Linux) <http://p-f-
1159 m.sourceforge.net/>
1160 Pfm is a terminal-based file manager written in Perl, based on
1161 PFM.COM for MS-DOS (originally by Paul Culley and Henk de
1162 Heer).
1163 The soundgrab <http://brittonkerin.com/soundgrab/soundgrab.html>
1165 soundgrab is designed to help you slice up a big long raw audio
1166 file (by default 44.1 kHz 2 channel signed sixteen bit little
1167 endian) and save your favorite sections to other files. It does
1168 this by providing you with a cassette player like command line
1169 interface.
1170 PDL (The Perl Data Language) <http://pdl.perl.org/>
1172 PDL (``Perl Data Language'') gives standard Perl the ability to
1173 compactly store and speedily manipulate the large N-dimensional
1174 data arrays which are the bread and butter of scientific
1175 computing.
1176 PIQT (Perl Interactive DBI Query Tool)
1178 <http://piqt.sourceforge.net/>
1179 PIQT is an interactive query tool using the Perl DBI database
1180 interface. It supports ReadLine, provides a built in scripting
1181 language with a Lisp like syntax, an online help system, and
1182 uses wrappers to interface to the DBD modules.
1183 vshnu (the New Visual Shell)
1185 <http://www.cs.indiana.edu/~kinzler/vshnu/>
1186 A visual shell and CLI shell supplement.
1187 If you know any other works you recommend, please let me know.
1189
1191 Hiroo Hayashi "<hiroo.hayashi@computer.org>"
1192 <http://search.cpan.org/~hayashi/>
1194
1196 GTK+ support in addition to Tk.
1197
1199 Submit a bug report to rt.cpan.org
1200 <https://rt.cpan.org/Dist/Display.html?Name=Term-ReadLine-Gnu>.
1201 "add_defun()" can define up to 16 functions.
1202 Some functions and variables do not have test code yet. Your
1203 contribution is welcome. See t/readline.t for details.
1204 If the pager command (| or ||) in Perl debugger causes segmentation
1205 fault, you need to fix perl5db.pl. See
1206 <https://rt.perl.org/Public/Bug/Display.html?id=121456> for details.
1207
1209 Copyright (c) 1996-2016 Hiroo Hayashi. All rights reserved.
1210 This program is free software; you can redistribute it and/or modify it
1212 under the same terms as Perl itself.
1213perl v5.30.1 2020-01-30 Gnu(3)