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 "trim_arg_from_keyseq(KEYSEQ [,MAP])"
316 int rl_trim_arg_from_keyseq(str keyseq,
317 Keymap|str map = rl_get_keymap()) # GRL 8.2
318 "invoking_keyseqs(FUNCTION [,MAP])"
320 (@str) rl_invoking_keyseqs(FunctionPtr|str function,
321 Keymap|str map = rl_get_keymap())
322 function_dumper([READABLE])
324 void rl_function_dumper(int readable = 0)
325 "list_funmap_names"
327 void rl_list_funmap_names()
328 "funmap_names"
330 (@str) rl_funmap_names()
331 "add_funmap_entry(NAME, FUNCTION)"
333 int rl_add_funmap_entry(char *name, FunctionPtr|str function)
334 Allowing Undoing
336 "begin_undo_group"
338 int rl_begin_undo_group()
339 "end_undo_group"
341 int rl_end_undo_group()
342 "add_undo(WHAT, START, END, TEXT)"
344 int rl_add_undo(int what, int start, int end, str text)
345 "free_undo_list"
347 void rl_free_undo_list()
348 "do_undo"
350 int rl_do_undo()
351 "modifying([START [,END]])"
353 int rl_modifying(int start = 0, int end = rl_end)
354 Redisplay
356 "redisplay"
358 void rl_redisplay()
359 "forced_update_display"
361 int rl_forced_update_display()
362 "on_new_line"
364 int rl_on_new_line()
365 "on_new_line_with_prompt"
367 int rl_on_new_line_with_prompt() # GRL 4.1
368 clear_visible_line()
370 int rl_clear_visible_line() # GRL 7.0
371 "reset_line_state"
373 int rl_reset_line_state()
374 "crlf"
376 int rl_crlf()
377 show_char(C)
379 int rl_show_char(int c)
380 "message(FMT[, ...])"
382 int rl_message(str fmt, ...)
383 "clear_message"
385 int rl_clear_message()
386 "save_prompt"
388 void rl_save_prompt()
389 "restore_prompt"
391 void rl_restore_prompt()
392 expand_prompt(PROMPT)
394 int rl_expand_prompt(str prompt)
395 set_prompt(PROMPT)
397 int rl_set_prompt(const str prompt) # GRL 4.2
398 Modifying Text
400 insert_text(TEXT)
402 int rl_insert_text(str text)
403 "delete_text([START [,END]])"
405 int rl_delete_text(int start = 0, int end = rl_end)
406 "copy_text([START [,END]])"
408 str rl_copy_text(int start = 0, int end = rl_end)
409 "kill_text([START [,END]])"
411 int rl_kill_text(int start = 0, int end = rl_end)
412 push_macro_input(MACRO)
414 int rl_push_macro_input(str macro)
415 Character Input
417 "read_key"
419 int rl_read_key()
420 getc(STREAM)
422 int rl_getc(FILE *STREAM)
423 stuff_char(C)
425 int rl_stuff_char(int c)
426 execute_next(C)
428 int rl_execute_next(int c)
429 clear_pending_input()
431 int rl_clear_pending_input() # GRL 4.2
432 set_keyboard_input_timeout(uSEC)
434 int rl_set_keyboard_input_timeout(int usec) # GRL 4.2
435 "set_timeout(SECS, USECS)"
437 int rl_set_timeout(int secs, int usecs) # GRL 8.2
438 clear_timeout()
440 int rl_clear_timeout() # GRL 8.2
441 timeout_remaining()
443 int rl_timeout_remaining() # scalar context, GRL 8.2
444 (int ret, int secs, int usecs) rl_timeout_remaining() # array context
445 Terminal Management
447 prep_terminal(META_FLAG)
449 void rl_prep_terminal(int META_FLAG)
450 deprep_terminal()
452 void rl_deprep_terminal()
453 tty_set_default_bindings([MAP])
455 void rl_tty_set_default_bindings([Keymap|str map = rl_get_keymap()]) # GRL 4.0
456 tty_unset_default_bindings([MAP])
458 void rl_tty_unset_default_bindings([Keymap|str map = rl_get_keymap()]) # GRL 5.0
459 tty_set_echoing(VALUE)
461 int rl_tty_set_echoing(int value) # GRL 7.0
462 reset_terminal([TERMINAL_NAME])
464 int rl_reset_terminal(str terminal_name = getenv($TERM))
465 Utility Functions
467 save_state(READLINE_STATE)
469 READLINE_STATE rl_save_state() # GRL 6.0
470 restore_state(READLINE_STATE)
472 int rl_restore_state(READLINE_STATE) # GRL 6.0
473 free(MEM)
475 Not implemented since not required for Perl.
476 int rl_free(void *mem) # GRL 6.0
477 "replace_line(TEXT [,CLEAR_UNDO])"
479 int rl_replace_line(str text, int clear_undo = 0) # GRL 4.3
480 extend_line_buffer(LEN)
482 Not implemented since not required for Perl.
483 int rl_extend_line_buffer(int len)
484 "initialize"
486 int rl_initialize()
487 "ding"
489 int rl_ding()
490 alphabetic(C)
492 int rl_alphabetic(int C) # GRL 4.2
493 "display_match_list(MATCHES [,LEN [,MAX]])"
495 void rl_display_match_list(\@matches, len = $#maches, max) # GRL 4.0
496 Since the first element of an array @matches as treated as a
498 possible completion, it is not displayed. See the descriptions of
499 completion_matches(). When "MAX" is omitted, the max length of an
500 item in @matches is used.
501 Miscellaneous Functions
503 "macro_bind(KEYSEQ, MACRO [,MAP])"
505 int rl_macro_bind(const str keyseq, const str macro, Keymap map)
506 macro_dumper(READABLE)
508 int rl_macro_dumper(int readline)
509 "variable_bind(VARIABLE, VALUE)"
511 int rl_variable_bind(const str variable, const str value)
512 variable_value(VARIABLE)
514 str rl_variable_value(const str variable) # GRL 5.1
515 variable_dumper(READABLE)
517 int rl_variable_dumper(int readline)
518 set_paren_blink_timeout(uSEC)
520 int rl_set_paren_blink_timeout(usec) # GRL 4.2
521 get_termcap(cap)
523 str rl_get_termcap(cap)
524 "clear_history"
526 void rl_clear_history() # GRL 6.3
527 "activate_mark"
529 void rl_activate_mark() # GRL 8.1
530 "deactivate_mark"
532 void rl_deactivate_mark() # GRL 8.1
533 "keep_mark_active"
535 void rl_keep_mark_active() # GRL 8.1
536 "mark_active_p"
538 int rl_mark_active_p() # GRL 8.1
539 Alternate Interface
541 "callback_handler_install(PROMPT, LHANDLER)"
543 void rl_callback_handler_install(str prompt, pfunc lhandler)
544 "callback_read_char"
546 void rl_callback_read_char()
547 "callback_sigcleanup" # GRL 7.0
549 void rl_callback_sigcleanup()
550 "callback_handler_remove"
552 void rl_callback_handler_remove()
553 Readline Signal Handling
555 pending_signal()
557 int rl_pending_signal() # GRL 7.0
558 "cleanup_after_signal"
560 void rl_cleanup_after_signal() # GRL 4.0
561 "free_line_state"
563 void rl_free_line_state() # GRL 4.0
564 "reset_after_signal"
566 void rl_reset_after_signal() # GRL 4.0
567 "check_signals"
569 void rl_check_signals() # GRL 8.0
570 "echo_signal_char"
572 void rl_echo_signal_char(int sig) # GRL 6.0
573 "resize_terminal"
575 void rl_resize_terminal() # GRL 4.0
576 "set_screen_size(ROWS, COLS)"
578 void rl_set_screen_size(int ROWS, int COLS) # GRL 4.2
579 get_screen_size()
581 (int rows, int cols) rl_get_screen_size() # GRL 4.2
582 reset_screen_size()
584 void rl_reset_screen_size() # GRL 5.1
585 "set_signals"
587 int rl_set_signals() # GRL 4.0
588 "clear_signals"
590 int rl_clear_signals() # GRL 4.0
591 Completion Functions
593 complete_internal([WHAT_TO_DO])
595 int rl_complete_internal(int what_to_do = TAB)
596 completion_mode(FUNCTION)
598 int rl_completion_mode(FunctionPtr|str function) # GRL 4.3
599 "completion_matches(TEXT [,FUNC])"
601 (@str) rl_completion_matches(str text,
602 pfunc func = filename_completion_function)
603 "filename_completion_function(TEXT, STATE)"
605 str rl_filename_completion_function(str text, int state)
606 "username_completion_function(TEXT, STATE)"
608 str rl_username_completion_function(str text, int state)
609 "list_completion_function(TEXT, STATE)"
611 str list_completion_function(str text, int state) # TRG original
612 History Functions
614 Initializing History and State Management
616 "using_history"
618 void using_history()
619 "history_get_history_state"
621 HISTORY_STATE history_get_hitory_state() # GRL 6.3
622 "history_set_history_state"
624 void history_set_hitory_state(HISTORY_STATE) # GRL 6.3
625 History List Management
627 add_history(STRING)
629 void add_history(str string)
630 add_history_time(STRING)
632 void add_history_time(str string) # GRL 5.0
633 remove_history(WHICH)
635 str remove_history(int which)
636 free_history(HISTENT)
638 Not implemented since Term::ReadLine::Gnu does not support the
639 member 'data' of HIST_ENTRY structure. remove_history() frees
640 the memory.
641 histdata_t free_history_entry(HIST_ENTRY *histent) # GRL 5.0
642 "replace_history_entry(WHICH, STRING)"
644 str replace_history_entry(int which, str string)
645 "clear_history"
647 void clear_history()
648 StifleHistory(MAX)
650 int stifle_history(int max|undef)
651 stifles the history list, remembering only the last "MAX" entries.
653 If "MAX" is undef, remembers all entries. This is a replacement of
654 unstifle_history().
655 "unstifle_history"
657 int unstifle_history()
658 This is equivalent with stifle_history(undef).
660 "history_is_stifled"
662 int history_is_stifled()
663 "SetHistory(LINE1 [, LINE2, ...])"
665 sets the history of input, from where it can be used if the actual
666 "readline" is present.
667 Information About the History List
669 "history_list"
671 Not implemented since not required for Perl.
672 HIST_ENTRY **history_list()
673 "where_history"
675 int where_history()
676 "current_history"
678 str current_history()
679 history_get(OFFSET)
681 str history_get(offset)
682 history_get_time(OFFSET)
684 time_t history_get_time(offset) # GRL 5.0
685 "history_total_bytes"
687 int history_total_bytes()
688 "GetHistory"
690 returns the history of input as a list, if actual "readline" is
691 present.
692 Moving Around the History List
694 history_set_pos(POS)
696 int history_set_pos(int pos)
697 "previous_history"
699 str previous_history()
700 "next_history"
702 str next_history()
703 Searching the History List
705 "history_search(STRING [,DIRECTION])"
707 int history_search(str string, int direction = -1)
708 "history_search_prefix(STRING [,DIRECTION])"
710 int history_search_prefix(str string, int direction = -1)
711 "history_search_pos(STRING [,DIRECTION [,POS]])"
713 int history_search_pos(str string,
714 int direction = -1,
715 int pos = where_history())
716 Managing the History File
718 "ReadHistory([FILENAME [,FROM [,TO]]])"
720 int read_history(str filename = '~/.history',
721 int from = 0, int to = -1)
722 int read_history_range(str filename = '~/.history',
724 int from = 0, int to = -1)
725 adds the contents of "FILENAME" to the history list, a line at a
727 time. If "FILENAME" is false, then read from ~/.history. Start
728 reading at line "FROM" and end at "TO". If "FROM" is omitted or
729 zero, start at the beginning. If "TO" is omitted or less than
730 "FROM", then read until the end of the file. Returns true if
731 successful, or false if not. read_history() is an alias of
732 read_history_range().
733 WriteHistory([FILENAME])
735 int write_history(str filename = '~/.history')
736 writes the current history to "FILENAME", overwriting "FILENAME" if
738 necessary. If "FILENAME" is false, then write the history list to
739 ~/.history. Returns true if successful, or false if not.
740 "append_history(NELEMENTS [,FILENAME])"
742 int append_history(int nelements, str filename = '~/.history')
743 "history_truncate_file([FILENAME [,NLINES]])"
745 int history_truncate_file(str filename = '~/.history',
746 int nlines = 0)
747 History Expansion
749 history_expand(STRING)
751 (int result, str expansion) history_expand(str string)
752 Note that this function returns "expansion" in the scalar context.
754 "get_history_event(STRING, CINDEX [,QCHAR])"
756 (str text, int cindex) = get_history_event(str string,
757 int cindex,
758 char qchar = '\0')
759 history_tokenize(STRING)
761 (@str) history_tokenize(str string)
762 "history_arg_extract(STRING, [FIRST [,LAST]])"
764 str history_arg_extract(str string, int first = 0, int last = '$')
765 "Term::ReadLine::Gnu" Variables
767 Following GNU Readline/History Library variables can be accessed by a
768 Perl program. See GNU Readline Library Manual
769 <https://tiswww.cwru.edu/php/chet/readline/readline.html> and GNU
770 History Library Manual
771 <https://tiswww.cwru.edu/php/chet/readline/history.html> for details of
772 each variable. You can access them by using "Attribs" methods. Names
773 of keys in this hash conform to standard conventions with the leading
774 "rl_" stripped.
775 Examples:
777 $attribs = $term->Attribs;
779 $v = $attribs->{library_version}; # rl_library_version
780 $v = $attribs->{history_base}; # history_base
781 Readline Variables
783 str rl_line_buffer
785 int rl_point
786 int rl_end
787 int rl_mark
788 int rl_done
789 int rl_eof_found (GRL 8.2)
790 int rl_num_chars_to_read (GRL 4.1)
791 int rl_pending_input
792 int rl_dispatching
793 int rl_erase_empty_line (GRL 4.0)
794 str rl_prompt (read only)
795 str rl_display_prompt
796 int rl_already_prompted (GRL 4.1)
797 str rl_library_version (read only)
798 int rl_readline_version (read only)
799 int rl_gnu_readline_p (GRL 4.1, read only)
800 str rl_terminal_name
801 str rl_readline_name
802 filehandle rl_instream
803 filehandle rl_outstream
804 int rl_prefer_env_winsize (GRL 5.1)
805 pfunc rl_last_func (GRL 4.2, read only)
806 pfunc rl_startup_hook
807 pfunc rl_pre_input_hook (GRL 4.0)
808 pfunc rl_event_hook
809 pfunc rl_getc_function
810 pfunc rl_signal_event_hook (GRL 6.3)
811 pfunc rl_timeout_event_hook (GRL 8.2)
812 pfunc rl_input_available_hook (GRL 6.3)
813 pfunc rl_redisplay_function
814 pfunc rl_prep_term_function (GRL 2.1)
815 pfunc rl_deprep_term_function (GRL 2.1)
816 Keymap rl_executing_keymap (read only)
817 Keymap rl_binding_keymap (read only)
818 str rl_executing_macro (GRL 4.2, read only)
819 int rl_executing_key (GRL 6.3, read only)
820 str rl_executing_keyseq (GRL 6.3, read only)
821 int rl_key_sequence_length (read only)
822 int rl_readline_state (GRL 4.2)
823 int rl_explicit_arg (read only)
824 int rl_numeric_arg (read only)
825 int rl_editing_mode (read only)
826 Signal Handling Variables
828 int rl_catch_signals (GRL 4.0)
830 int rl_catch_sigwinch (GRL 4.0)
831 int rl_persistent_signal_handlers (GRL 7.0)
832 int rl_change_environment (GRL 6.3)
833 Completion Variables
835 pfunc rl_completion_entry_function
837 pfunc rl_attempted_completion_function
838 pfunc rl_filename_quoting_function
839 pfunc rl_filename_dequoting_function
840 pfunc rl_char_is_quoted_p
841 pfunc rl_ignore_some_completions_function
842 pfunc rl_directory_completion_hook
843 pfunc rl_directory_rewrite_hook (GRL 4.2)
844 pfunc rl_filename_stat_hook (GRL 6.3)
845 pfunc rl_filename_rewrite_hook (GRL 6.1)
846 pfunc rl_completion_display_matches_hook (GRL 4.0)
847 str rl_basic_word_break_characters
848 str rl_basic_quote_characters
849 str rl_completer_word_break_characters
850 pfunc rl_completion_word_break_hook (GRL 5.0)
851 str rl_completer_quote_characters
852 str rl_filename_quote_characters
853 str rl_special_prefixes
854 int rl_completion_query_items
855 int rl_completion_append_character
856 int rl_completion_suppress_append (GRL 4.3)
857 int rl_completion_quote_character (GRL 5.0, read only)
858 int rl_completion_suppress_quote (GRL 5.0)
859 int rl_completion_found_quote (GRL 5.0, read only)
860 int rl_completion_mark_symlink_dirs (GRL 4.3)
861 int rl_ignore_completion_duplicates
862 int rl_filename_completion_desired
863 int rl_filename_quoting_desired
864 int rl_attempted_completion_over
865 int rl_sort_completion_matches (GRL 6.0)
866 int rl_completion_type (read only)
867 int rl_completion_invoking_key (GRL 6.0, read only)
868 int rl_inhibit_completion
869 History Variables
871 int history_base
873 int history_length
874 int history_max_entries (called `max_input_history', read only)
875 int history_write_timestamps (GRL 5.0)
876 char history_expansion_char
877 char history_subst_char
878 char history_comment_char
879 str history_word_delimiters (GRL 4.2)
880 str history_search_delimiter_chars
881 str history_no_expand_chars
882 int history_quotes_inhibit_expansion
883 int history_quoting_state
884 pfunc history_inhibit_expansion_function
885 Function References
887 rl_getc
889 rl_redisplay
890 rl_callback_read_char
891 rl_display_match_list
892 rl_filename_completion_function
893 rl_username_completion_function
894 list_completion_function
895 shadow_redisplay
896 Tk_getc
897 Custom Completion
899 In this section variables and functions for custom completion are
900 described along with examples.
901 Most of descriptions in this section came from GNU Readline Library
903 Manual <https://tiswww.cwru.edu/php/chet/readline/readline.html>.
904 "completion_entry_function"
906 This variable holds reference refers to a generator function for
907 completion_matches().
908 A generator function is called repeatedly from
910 completion_matches(), returning a string each time. The arguments
911 to the generator function are "TEXT" and "STATE". "TEXT" is the
912 partial word to be completed. "STATE" is zero the first time the
913 function is called, allowing the generator to perform any necessary
914 initialization, and a positive non-zero integer for each subsequent
915 call. When the generator function returns "undef" this signals
916 completion_matches() that there are no more possibilities left.
917 If this variable set to undef, built-in
919 "filename_completion_function" is used.
920 A sample generator function, "list_completion_function", is defined
922 in Gnu.pm. You can use it as follows;
923 use Term::ReadLine;
925 ...
926 my $term = new Term::ReadLine 'sample';
927 my $attribs = $term->Attribs;
928 ...
929 $attribs->{completion_entry_function} =
930 $attribs->{list_completion_function};
931 ...
932 $attribs->{completion_word} =
933 [qw(reference to a list of words which you want to use for completion)];
934 $term->readline("custom completion>");
935 See also "completion_matches".
937 "attempted_completion_function"
939 A reference to an alternative function to create matches.
940 The function is called with "TEXT", "LINE_BUFFER", "START", and
942 "END". "LINE_BUFFER" is a current input buffer string. "START"
943 and "END" are indices in "LINE_BUFFER" saying what the boundaries
944 of "TEXT" are.
945 If this function exists and returns null list or "undef", or if
947 this variable is set to "undef", then an internal function
948 rl_complete() will call the value of "completion_entry_function" to
949 generate matches, otherwise the array of strings returned will be
950 used.
951 The default value of this variable is "undef". You can use it as
953 follows;
954 use Term::ReadLine;
956 ...
957 my $term = new Term::ReadLine 'sample';
958 my $attribs = $term->Attribs;
959 ...
960 sub sample_completion {
961 my ($text, $line, $start, $end) = @_;
962 # If first word then username completion, else filename completion
963 if (substr($line, 0, $start) =~ /^\s*$/) {
964 return $term->completion_matches($text,
965 $attribs->{'username_completion_function'});
966 } else {
967 return ();
968 }
969 }
970 ...
971 $attribs->{attempted_completion_function} = \&sample_completion;
972 "completion_matches(TEXT, ENTRY_FUNC)"
974 Returns an array of strings which is a list of completions for
975 "TEXT". If there are no completions, returns "undef". The first
976 entry in the returned array is the substitution for "TEXT". The
977 remaining entries are the possible completions.
978 "ENTRY_FUNC" is a generator function which has two arguments, and
980 returns a string. The first argument is "TEXT". The second is a
981 state argument; it is zero on the first call, and non-zero on
982 subsequent calls. "ENTRY_FUNC" returns "undef" to the caller when
983 there are no more matches.
984 If the value of "ENTRY_FUNC" is undef, built-in
986 "filename_completion_function" is used.
987 "completion_matches" is a Perl wrapper function of an internal
989 function completion_matches(). See also
990 "completion_entry_function".
991 "completion_function"
993 A variable whose content is a reference to a function which returns
994 a list of candidates to complete.
995 This variable is compatible with Term::ReadLine::Perl
997 <http://search.cpan.org/dist/Term-ReadLine-Perl/> and very easy to
998 use.
999 use Term::ReadLine;
1001 ...
1002 my $term = new Term::ReadLine 'sample';
1003 my $attribs = $term->Attribs;
1004 ...
1005 $attribs->{completion_function} = sub {
1006 my ($text, $line, $start) = @_;
1007 return qw(a list of candidates to complete);
1008 };
1009 "list_completion_function(TEXT, STATE)"
1011 A sample generator function defined by "Term::ReadLine::Gnu".
1012 Example code at "completion_entry_function" shows how to use this
1013 function.
1014 "Term::ReadLine::Gnu" Specific Features
1016 "Term::ReadLine::Gnu" Specific Functions
1017 "CallbackHandlerInstall(PROMPT, LHANDLER)"
1019 This method provides the function rl_callback_handler_install()
1020 with the following additional feature compatible with "readline"
1021 method; ornament feature, Term::ReadLine::Perl
1022 <http://search.cpan.org/dist/Term-ReadLine-Perl/> compatible
1023 completion function, history expansion, and addition to history
1024 buffer.
1025 "call_function(FUNCTION, [COUNT [,KEY]])"
1027 int rl_call_function(FunctionPtr|str function, count = 1, key = -1)
1028 "get_all_function_names"
1030 Returns a list of all function names.
1031 "shadow_redisplay"
1033 A redisplay function for password input. You can use it as
1034 follows;
1035 $attribs->{redisplay_function} = $attribs->{shadow_redisplay};
1037 $line = $term->readline("password> ");
1038 "filename_list"
1040 Returns candidates of filenames to complete. This function can be
1041 used with "completion_function" and is implemented for the
1042 compatibility with Term::ReadLine::Perl
1043 <http://search.cpan.org/dist/Term-ReadLine-Perl/>.
1044 "list_completion_function"
1046 See the description of section "Custom Completion".
1047 "Term::ReadLine::Gnu" Specific Variables
1049 "do_expand"
1051 When true, the history expansion is enabled. By default false.
1052 "completion_function"
1054 See the description of section "Custom Completion".
1055 "completion_word"
1057 A reference to a list of candidates to complete for
1058 "list_completion_function".
1059 "Term::ReadLine::Gnu" Specific Commands
1061 "history-expand-line"
1063 The equivalent of the Bash "history-expand-line" editing command.
1064 "operate-and-get-next"
1066 The equivalent of the Korn shell
1067 "operate-and-get-next-history-line" editing command and the Bash
1068 "operate-and-get-next".
1069 This command is bound to "\C-o" by default for the compatibility
1071 with the Bash and Term::ReadLine::Perl
1072 <http://search.cpan.org/dist/Term-ReadLine-Perl/>.
1073 "display-readline-version"
1075 Shows the version of "Term::ReadLine::Gnu" and the one of the GNU
1076 Readline Library.
1077 "change-ornaments"
1079 Change ornaments interactively.
1080
1082 ~/.inputrc
1083 Readline init file. Using this file it is possible that you would
1084 like to use a different set of key bindings. When a program which
1085 uses the GNU Readline library starts up, the init file is read, and
1086 the key bindings are set.
1087 The conditional init constructs is supported. The program name
1089 which is specified by the first argument of "new" method is used as
1090 the application construct.
1091 For example, when your program calls "new" method as follows;
1093 ...
1095 $term = new Term::ReadLine 'PerlSh';
1096 ...
1097 your ~/.inputrc can define key bindings only for the program as
1099 follows;
1100 ...
1102 $if PerlSh
1103 Meta-Rubout: backward-kill-word
1104 "\C-x\C-r": re-read-init-file
1105 "\e[11~": "Function Key 1"
1106 $endif
1107 ...
1108 For further details, see the section "Readline Init File" in the
1110 GNU Readline Library Manual
1111 <https://tiswww.cwru.edu/php/chet/readline/readline.html>
1112
1114 No symbols are exported by default. The following tags are defined and
1115 their symbols can be exported.
1116 prompt
1118 RL_PROMPT_START_IGNORE RL_PROMPT_END_IGNORE
1119 match_type
1121 NO_MATCH SINGLE_MATCH MULT_MATCH
1122 keymap_type
1124 ISFUNC ISKMAP ISMACR
1125 undo_code
1127 UNDO_DELETE UNDO_INSERT UNDO_BEGIN UNDO_END
1128 rl_state
1130 RL_STATE_NONE RL_STATE_INITIALIZING RL_STATE_INITIALIZED
1131 RL_STATE_TERMPREPPED RL_STATE_READCMD RL_STATE_METANEXT
1132 RL_STATE_DISPATCHING RL_STATE_MOREINPUT RL_STATE_ISEARCH
1133 RL_STATE_NSEARCH RL_STATE_SEARCH RL_STATE_NUMERICARG
1134 RL_STATE_MACROINPUT RL_STATE_MACRODEF RL_STATE_OVERWRITE
1135 RL_STATE_COMPLETING RL_STATE_SIGHANDLER RL_STATE_UNDOING
1136 RL_STATE_INPUTPENDING RL_STATE_TTYCSAVED RL_STATE_CALLBACK
1137 RL_STATE_VIMOTION RL_STATE_MULTIKEY RL_STATE_VICMDONCE
1138 RL_STATE_CHARSEARCH RL_STATE_REDISPLAYING RL_STATE_DONE
1139 RL_STATE_TIMEOUT RL_STATE_EOF
1140 They can be exported as follows;
1142 use Term::ReadLine;
1144 BEGIN {
1145 import Term::ReadLine::Gnu qw(:keymap_type RL_STATE_INITIALIZED);
1146 }
1147
1149 The environment variable "PERL_RL" governs which ReadLine clone is
1150 loaded. See the ENVIRONMENT section on Term::ReadLine
1151 <http://search.cpan.org/dist/Term-ReadLine/> for further details.
1152 If the environment variable "TERM" is set to "emacs" or the environment
1154 variable "INSIDE_EMACS" or "EMACS" is defined, "Term::ReadLine::Stub"
1155 is used instead of <Term::ReadLine:Gnu>.
1156
1158 Term::ReadLine::Gnu Project Home Page <https://github.com/hirooih/perl-
1159 trg>
1160 GNU Readline Library Manual
1161 <https://tiswww.cwru.edu/php/chet/readline/readline.html>
1162 GNU History Library Manual
1163 <https://tiswww.cwru.edu/php/chet/readline/history.html>
1164 Sample and test programs (eg/* and t/*) in the "Term::ReadLine::Gnu"
1165 distribution <http://search.cpan.org/dist/Term-ReadLine-Gnu/>
1166 Term::ReadLine <http://search.cpan.org/dist/Term-ReadLine/>
1167 Works which use Term::ReadLine::Gnu
1168 Distributions which depend on Term::ReadLine::Gnu on CPAN
1169 <http://www.cpan.org/>
1170 <https://metacpan.org/requires/distribution/Term-ReadLine-Gnu>
1171 Perl Debugger <http://perldoc.perl.org/perldebug.html>
1173 perl -d
1174 Perl Shell (psh) <http://gnp.github.io/psh/>
1176 The Perl Shell is a shell that combines the interactive nature
1177 of a Unix shell with the power of Perl.
1178 A programmable completion feature compatible with bash is
1180 implemented.
1181 SPP (Synopsys Plus Perl)
1183 <http://vlsiweb.stanford.edu/~jsolomon/SPP/>
1184 SPP (Synopsys Plus Perl) is a Perl module that wraps around
1185 Synopsys' shell programs. SPP is inspired by the original
1186 dc_perl written by Steve Golson, but it's an entirely new
1187 implementation. Why is it called SPP and not dc_perl? Well,
1188 SPP was written to wrap around any of Synopsys' shells.
1189 PFM (Personal File Manager for Unix/Linux) <http://p-f-
1191 m.sourceforge.net/>
1192 Pfm is a terminal-based file manager written in Perl, based on
1193 PFM.COM for MS-DOS (originally by Paul Culley and Henk de
1194 Heer).
1195 The soundgrab <https://sourceforge.net/projects/soundgrab/>
1197 soundgrab is designed to help you slice up a big long raw audio
1198 file (by default 44.1 kHz 2 channel signed sixteen bit little
1199 endian) and save your favorite sections to other files. It does
1200 this by providing you with a cassette player like command line
1201 interface.
1202 PDL (The Perl Data Language) <http://pdl.perl.org/>
1204 PDL (``Perl Data Language'') gives standard Perl the ability to
1205 compactly store and speedily manipulate the large N-dimensional
1206 data arrays which are the bread and butter of scientific
1207 computing.
1208 PIQT (Perl Interactive DBI Query Tool)
1210 <http://piqt.sourceforge.net/>
1211 PIQT is an interactive query tool using the Perl DBI database
1212 interface. It supports ReadLine, provides a built in scripting
1213 language with a Lisp like syntax, an online help system, and
1214 uses wrappers to interface to the DBD modules.
1215 vshnu (the New Visual Shell)
1217 <http://www.cs.indiana.edu/~kinzler/vshnu/>
1218 A visual shell and CLI shell supplement.
1219 If you know any other works you recommend, please let me know.
1221
1223 Hiroo Hayashi "<hiroo.hayashi@computer.org>"
1224 <http://search.cpan.org/~hayashi/>
1226
1228 GTK+ support in addition to Tk.
1229
1231 Submit a bug report to the bug tracker on GitHub
1232 <https://github.com/hirooih/perl-trg/issues>.
1233 add_defun() can define up to 16 functions.
1234 Some functions and variables do not have test code yet. Your
1235 contribution is welcome. See t/readline.t for details.
1236 If the pager command (| or ||) in Perl debugger causes segmentation
1237 fault, you need to fix perl5db.pl. See
1238 <https://rt.perl.org/Public/Bug/Display.html?id=121456> for details.
1239
1241 Copyright (c) 1996-2020 Hiroo Hayashi. All rights reserved.
1242 This program is free software; you can redistribute it and/or modify it
1244 under the same terms as Perl itself.
1245perl v5.38.0 2023-07-24 Gnu(3)