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 "activate_mark"
515 void rl_activate_mark() # GRL 8.1
516 "deactivate_mark"
518 void rl_deactivate_mark() # GRL 8.1
519 "keep_mark_active"
521 void rl_keep_mark_active() # GRL 8.1
522 "mark_active_p"
524 int rl_mark_active_p() # GRL 8.1
525 Alternate Interface
527 "callback_handler_install(PROMPT, LHANDLER)"
529 void rl_callback_handler_install(str prompt, pfunc lhandler)
530 "callback_read_char"
532 void rl_callback_read_char()
533 "callback_sigcleanup" # GRL 7.0
535 void rl_callback_sigcleanup()
536 "callback_handler_remove"
538 void rl_callback_handler_remove()
539 Readline Signal Handling
541 "pending_signal()"
543 int rl_pending_signal() # GRL 7.0
544 "cleanup_after_signal"
546 void rl_cleanup_after_signal() # GRL 4.0
547 "free_line_state"
549 void rl_free_line_state() # GRL 4.0
550 "reset_after_signal"
552 void rl_reset_after_signal() # GRL 4.0
553 "check_signals"
555 void rl_check_signals() # GRL 8.0
556 "echo_signal_char"
558 void rl_echo_signal_char(int sig) # GRL 6.0
559 "resize_terminal"
561 void rl_resize_terminal() # GRL 4.0
562 "set_screen_size(ROWS, COLS)"
564 void rl_set_screen_size(int ROWS, int COLS) # GRL 4.2
565 "get_screen_size()"
567 (int rows, int cols) rl_get_screen_size() # GRL 4.2
568 "reset_screen_size()"
570 void rl_reset_screen_size() # GRL 5.1
571 "set_signals"
573 int rl_set_signals() # GRL 4.0
574 "clear_signals"
576 int rl_clear_signals() # GRL 4.0
577 Completion Functions
579 "complete_internal([WHAT_TO_DO])"
581 int rl_complete_internal(int what_to_do = TAB)
582 "completion_mode(FUNCTION)"
584 int rl_completion_mode(FunctionPtr|str function) # GRL 4.3
585 "completion_matches(TEXT [,FUNC])"
587 (@str) rl_completion_matches(str text,
588 pfunc func = filename_completion_function)
589 "filename_completion_function(TEXT, STATE)"
591 str rl_filename_completion_function(str text, int state)
592 "username_completion_function(TEXT, STATE)"
594 str rl_username_completion_function(str text, int state)
595 "list_completion_function(TEXT, STATE)"
597 str list_completion_function(str text, int state) # TRG original
598 History Functions
600 Initializing History and State Management
602 "using_history"
604 void using_history()
605 "history_get_history_state"
607 HISTORY_STATE history_get_hitory_state() # GRL 6.3
608 "history_set_history_state"
610 void history_set_hitory_state(HISTORY_STATE) # GRL 6.3
611 History List Management
613 "add_history(STRING)"
615 void add_history(str string)
616 "add_history_time(STRING)"
618 void add_history_time(str string) # GRL 5.0
619 "remove_history(WHICH)"
621 str remove_history(int which)
622 "free_history(HISTENT)"
624 Not implemented since Term::ReadLine::Gnu does not support the
625 member 'data' of HIST_ENTRY structure. remove_history() frees
626 the memory.
627 histdata_t free_history_entry(HIST_ENTRY *histent) # GRL 5.0
628 "replace_history_entry(WHICH, STRING)"
630 str replace_history_entry(int which, str string)
631 "clear_history"
633 void clear_history()
634 "StifleHistory(MAX)"
636 int stifle_history(int max|undef)
637 stifles the history list, remembering only the last "MAX" entries.
639 If "MAX" is undef, remembers all entries. This is a replacement of
640 "unstifle_history()".
641 "unstifle_history"
643 int unstifle_history()
644 This is equivalent with "stifle_history(undef)".
646 "history_is_stifled"
648 int history_is_stifled()
649 "SetHistory(LINE1 [, LINE2, ...])"
651 sets the history of input, from where it can be used if the actual
652 "readline" is present.
653 Information About the History List
655 "history_list"
657 Not implemented since not required for Perl.
658 HIST_ENTRY **history_list()
659 "where_history"
661 int where_history()
662 "current_history"
664 str current_history()
665 "history_get(OFFSET)"
667 str history_get(offset)
668 "history_get_time(OFFSET)"
670 time_t history_get_time(offset) # GRL 5.0
671 "history_total_bytes"
673 int history_total_bytes()
674 "GetHistory"
676 returns the history of input as a list, if actual "readline" is
677 present.
678 Moving Around the History List
680 "history_set_pos(POS)"
682 int history_set_pos(int pos)
683 "previous_history"
685 str previous_history()
686 "next_history"
688 str next_history()
689 Searching the History List
691 "history_search(STRING [,DIRECTION])"
693 int history_search(str string, int direction = -1)
694 "history_search_prefix(STRING [,DIRECTION])"
696 int history_search_prefix(str string, int direction = -1)
697 "history_search_pos(STRING [,DIRECTION [,POS]])"
699 int history_search_pos(str string,
700 int direction = -1,
701 int pos = where_history())
702 Managing the History File
704 "ReadHistory([FILENAME [,FROM [,TO]]])"
706 int read_history(str filename = '~/.history',
707 int from = 0, int to = -1)
708 int read_history_range(str filename = '~/.history',
710 int from = 0, int to = -1)
711 adds the contents of "FILENAME" to the history list, a line at a
713 time. If "FILENAME" is false, then read from ~/.history. Start
714 reading at line "FROM" and end at "TO". If "FROM" is omitted or
715 zero, start at the beginning. If "TO" is omitted or less than
716 "FROM", then read until the end of the file. Returns true if
717 successful, or false if not. "read_history()" is an alias of
718 "read_history_range()".
719 "WriteHistory([FILENAME])"
721 int write_history(str filename = '~/.history')
722 writes the current history to "FILENAME", overwriting "FILENAME" if
724 necessary. If "FILENAME" is false, then write the history list to
725 ~/.history. Returns true if successful, or false if not.
726 "append_history(NELEMENTS [,FILENAME])"
728 int append_history(int nelements, str filename = '~/.history')
729 "history_truncate_file([FILENAME [,NLINES]])"
731 int history_truncate_file(str filename = '~/.history',
732 int nlines = 0)
733 History Expansion
735 "history_expand(STRING)"
737 (int result, str expansion) history_expand(str string)
738 Note that this function returns "expansion" in the scalar context.
740 "get_history_event(STRING, CINDEX [,QCHAR])"
742 (str text, int cindex) = get_history_event(str string,
743 int cindex,
744 char qchar = '\0')
745 "history_tokenize(STRING)"
747 (@str) history_tokenize(str string)
748 "history_arg_extract(STRING, [FIRST [,LAST]])"
750 str history_arg_extract(str string, int first = 0, int last = '$')
751 "Term::ReadLine::Gnu" Variables
753 Following GNU Readline/History Library variables can be accessed by a
754 Perl program. See GNU Readline Library Manual
755 <https://tiswww.cwru.edu/php/chet/readline/readline.html> and GNU
756 History Library Manual
757 <https://tiswww.cwru.edu/php/chet/readline/history.html> for details of
758 each variable. You can access them by using "Attribs" methods. Names
759 of keys in this hash conform to standard conventions with the leading
760 "rl_" stripped.
761 Examples:
763 $attribs = $term->Attribs;
765 $v = $attribs->{library_version}; # rl_library_version
766 $v = $attribs->{history_base}; # history_base
767 Readline Variables
769 str rl_line_buffer
771 int rl_point
772 int rl_end
773 int rl_mark
774 int rl_done
775 int rl_num_chars_to_read (GRL 4.1)
776 int rl_pending_input
777 int rl_dispatching
778 int rl_erase_empty_line (GRL 4.0)
779 str rl_prompt (read only)
780 str rl_display_prompt
781 int rl_already_prompted (GRL 4.1)
782 str rl_library_version (read only)
783 int rl_readline_version (read only)
784 int rl_gnu_readline_p (GRL 4.1, read only)
785 str rl_terminal_name
786 str rl_readline_name
787 filehandle rl_instream
788 filehandle rl_outstream
789 int rl_prefer_env_winsize (GRL 5.1)
790 pfunc rl_last_func (GRL 4.2, read only)
791 pfunc rl_startup_hook
792 pfunc rl_pre_input_hook (GRL 4.0)
793 pfunc rl_event_hook
794 pfunc rl_getc_function
795 pfunc rl_signal_event_hook (GRL 6.3)
796 pfunc rl_input_available_hook (GRL 6.3)
797 pfunc rl_redisplay_function
798 pfunc rl_prep_term_function (GRL 2.1)
799 pfunc rl_deprep_term_function (GRL 2.1)
800 Keymap rl_executing_keymap (read only)
801 Keymap rl_binding_keymap (read only)
802 str rl_executing_macro (GRL 4.2, read only)
803 int rl_executing_key (GRL 6.3, read only)
804 str rl_executing_keyseq (GRL 6.3, read only)
805 int rl_key_sequence_length (read only)
806 int rl_readline_state (GRL 4.2)
807 int rl_explicit_arg (read only)
808 int rl_numeric_arg (read only)
809 int rl_editing_mode (read only)
810 Signal Handling Variables
812 int rl_catch_signals (GRL 4.0)
814 int rl_catch_sigwinch (GRL 4.0)
815 int rl_persistent_signal_handlers (GRL 7.0)
816 int rl_change_environment (GRL 6.3)
817 Completion Variables
819 pfunc rl_completion_entry_function
821 pfunc rl_attempted_completion_function
822 pfunc rl_filename_quoting_function
823 pfunc rl_filename_dequoting_function
824 pfunc rl_char_is_quoted_p
825 pfunc rl_ignore_some_completions_function
826 pfunc rl_directory_completion_hook
827 pfunc rl_directory_rewrite_hook (GRL 4.2)
828 pfunc rl_filename_stat_hook (GRL 6.3)
829 pfunc rl_filename_rewrite_hook (GRL 6.1)
830 pfunc rl_completion_display_matches_hook (GRL 4.0)
831 str rl_basic_word_break_characters
832 str rl_basic_quote_characters
833 str rl_completer_word_break_characters
834 pfunc rl_completion_word_break_hook (GRL 5.0)
835 str rl_completer_quote_characters
836 str rl_filename_quote_characters
837 str rl_special_prefixes
838 int rl_completion_query_items
839 int rl_completion_append_character
840 int rl_completion_suppress_append (GRL 4.3)
841 int rl_completion_quote_character (GRL 5.0, read only)
842 int rl_completion_suppress_quote (GRL 5.0)
843 int rl_completion_found_quote (GRL 5.0, read only)
844 int rl_completion_mark_symlink_dirs (GRL 4.3)
845 int rl_ignore_completion_duplicates
846 int rl_filename_completion_desired
847 int rl_filename_quoting_desired
848 int rl_attempted_completion_over
849 int rl_sort_completion_matches (GRL 6.0)
850 int rl_completion_type (read only)
851 int rl_completion_invoking_key (GRL 6.0, read only)
852 int rl_inhibit_completion
853 History Variables
855 int history_base
857 int history_length
858 int history_max_entries (called `max_input_history', read only)
859 int history_write_timestamps (GRL 5.0)
860 char history_expansion_char
861 char history_subst_char
862 char history_comment_char
863 str history_word_delimiters (GRL 4.2)
864 str history_search_delimiter_chars
865 str history_no_expand_chars
866 int history_quotes_inhibit_expansion
867 int history_quoting_state
868 pfunc history_inhibit_expansion_function
869 Function References
871 rl_getc
873 rl_redisplay
874 rl_callback_read_char
875 rl_display_match_list
876 rl_filename_completion_function
877 rl_username_completion_function
878 list_completion_function
879 shadow_redisplay
880 Tk_getc
881 Custom Completion
883 In this section variables and functions for custom completion are
884 described along with examples.
885 Most of descriptions in this section came from GNU Readline Library
887 Manual <https://tiswww.cwru.edu/php/chet/readline/readline.html>.
888 "completion_entry_function"
890 This variable holds reference refers to a generator function for
891 "completion_matches()".
892 A generator function is called repeatedly from
894 "completion_matches()", returning a string each time. The
895 arguments to the generator function are "TEXT" and "STATE". "TEXT"
896 is the partial word to be completed. "STATE" is zero the first
897 time the function is called, allowing the generator to perform any
898 necessary initialization, and a positive non-zero integer for each
899 subsequent call. When the generator function returns "undef" this
900 signals "completion_matches()" that there are no more possibilities
901 left.
902 If this variable set to undef, built-in
904 "filename_completion_function" is used.
905 A sample generator function, "list_completion_function", is defined
907 in Gnu.pm. You can use it as follows;
908 use Term::ReadLine;
910 ...
911 my $term = new Term::ReadLine 'sample';
912 my $attribs = $term->Attribs;
913 ...
914 $attribs->{completion_entry_function} =
915 $attribs->{list_completion_function};
916 ...
917 $attribs->{completion_word} =
918 [qw(reference to a list of words which you want to use for completion)];
919 $term->readline("custom completion>");
920 See also "completion_matches".
922 "attempted_completion_function"
924 A reference to an alternative function to create matches.
925 The function is called with "TEXT", "LINE_BUFFER", "START", and
927 "END". "LINE_BUFFER" is a current input buffer string. "START"
928 and "END" are indices in "LINE_BUFFER" saying what the boundaries
929 of "TEXT" are.
930 If this function exists and returns null list or "undef", or if
932 this variable is set to "undef", then an internal function
933 "rl_complete()" will call the value of "completion_entry_function"
934 to generate matches, otherwise the array of strings returned will
935 be used.
936 The default value of this variable is "undef". You can use it as
938 follows;
939 use Term::ReadLine;
941 ...
942 my $term = new Term::ReadLine 'sample';
943 my $attribs = $term->Attribs;
944 ...
945 sub sample_completion {
946 my ($text, $line, $start, $end) = @_;
947 # If first word then username completion, else filename completion
948 if (substr($line, 0, $start) =~ /^\s*$/) {
949 return $term->completion_matches($text,
950 $attribs->{'username_completion_function'});
951 } else {
952 return ();
953 }
954 }
955 ...
956 $attribs->{attempted_completion_function} = \&sample_completion;
957 "completion_matches(TEXT, ENTRY_FUNC)"
959 Returns an array of strings which is a list of completions for
960 "TEXT". If there are no completions, returns "undef". The first
961 entry in the returned array is the substitution for "TEXT". The
962 remaining entries are the possible completions.
963 "ENTRY_FUNC" is a generator function which has two arguments, and
965 returns a string. The first argument is "TEXT". The second is a
966 state argument; it is zero on the first call, and non-zero on
967 subsequent calls. "ENTRY_FUNC" returns "undef" to the caller when
968 there are no more matches.
969 If the value of "ENTRY_FUNC" is undef, built-in
971 "filename_completion_function" is used.
972 "completion_matches" is a Perl wrapper function of an internal
974 function "completion_matches()". See also
975 "completion_entry_function".
976 "completion_function"
978 A variable whose content is a reference to a function which returns
979 a list of candidates to complete.
980 This variable is compatible with Term::ReadLine::Perl
982 <http://search.cpan.org/dist/Term-ReadLine-Perl/> and very easy to
983 use.
984 use Term::ReadLine;
986 ...
987 my $term = new Term::ReadLine 'sample';
988 my $attribs = $term->Attribs;
989 ...
990 $attribs->{completion_function} = sub {
991 my ($text, $line, $start) = @_;
992 return qw(a list of candidates to complete);
993 };
994 "list_completion_function(TEXT, STATE)"
996 A sample generator function defined by "Term::ReadLine::Gnu".
997 Example code at "completion_entry_function" shows how to use this
998 function.
999 "Term::ReadLine::Gnu" Specific Features
1001 "Term::ReadLine::Gnu" Specific Functions
1002 "CallbackHandlerInstall(PROMPT, LHANDLER)"
1004 This method provides the function "rl_callback_handler_install()"
1005 with the following additional feature compatible with "readline"
1006 method; ornament feature, Term::ReadLine::Perl
1007 <http://search.cpan.org/dist/Term-ReadLine-Perl/> compatible
1008 completion function, history expansion, and addition to history
1009 buffer.
1010 "call_function(FUNCTION, [COUNT [,KEY]])"
1012 int rl_call_function(FunctionPtr|str function, count = 1, key = -1)
1013 "get_all_function_names"
1015 Returns a list of all function names.
1016 "shadow_redisplay"
1018 A redisplay function for password input. You can use it as
1019 follows;
1020 $attribs->{redisplay_function} = $attribs->{shadow_redisplay};
1022 $line = $term->readline("password> ");
1023 "filename_list"
1025 Returns candidates of filenames to complete. This function can be
1026 used with "completion_function" and is implemented for the
1027 compatibility with Term::ReadLine::Perl
1028 <http://search.cpan.org/dist/Term-ReadLine-Perl/>.
1029 "list_completion_function"
1031 See the description of section "Custom Completion".
1032 "Term::ReadLine::Gnu" Specific Variables
1034 "do_expand"
1036 When true, the history expansion is enabled. By default false.
1037 "completion_function"
1039 See the description of section "Custom Completion".
1040 "completion_word"
1042 A reference to a list of candidates to complete for
1043 "list_completion_function".
1044 "Term::ReadLine::Gnu" Specific Commands
1046 "history-expand-line"
1048 The equivalent of the Bash "history-expand-line" editing command.
1049 "operate-and-get-next"
1051 The equivalent of the Korn shell
1052 "operate-and-get-next-history-line" editing command and the Bash
1053 "operate-and-get-next".
1054 This command is bound to "\C-o" by default for the compatibility
1056 with the Bash and Term::ReadLine::Perl
1057 <http://search.cpan.org/dist/Term-ReadLine-Perl/>.
1058 "display-readline-version"
1060 Shows the version of "Term::ReadLine::Gnu" and the one of the GNU
1061 Readline Library.
1062 "change-ornaments"
1064 Change ornaments interactively.
1065
1067 ~/.inputrc
1068 Readline init file. Using this file it is possible that you would
1069 like to use a different set of key bindings. When a program which
1070 uses the GNU Readline library starts up, the init file is read, and
1071 the key bindings are set.
1072 The conditional init constructs is supported. The program name
1074 which is specified by the first argument of "new" method is used as
1075 the application construct.
1076 For example, when your program calls "new" method as follows;
1078 ...
1080 $term = new Term::ReadLine 'PerlSh';
1081 ...
1082 your ~/.inputrc can define key bindings only for the program as
1084 follows;
1085 ...
1087 $if PerlSh
1088 Meta-Rubout: backward-kill-word
1089 "\C-x\C-r": re-read-init-file
1090 "\e[11~": "Function Key 1"
1091 $endif
1092 ...
1093 For further details, see the section "Readline Init File" in the
1095 GNU Readline Library Manual
1096 <https://tiswww.cwru.edu/php/chet/readline/readline.html>
1097
1099 No symbols are exported by default. The following tags are defined and
1100 their symbols can be exported.
1101 prompt
1103 RL_PROMPT_START_IGNORE RL_PROMPT_END_IGNORE
1104 match_type
1106 NO_MATCH SINGLE_MATCH MULT_MATCH
1107 keymap_type
1109 ISFUNC ISKMAP ISMACR
1110 undo_code
1112 UNDO_DELETE UNDO_INSERT UNDO_BEGIN UNDO_END
1113 rl_state
1115 RL_STATE_NONE RL_STATE_INITIALIZING RL_STATE_INITIALIZED
1116 RL_STATE_TERMPREPPED RL_STATE_READCMD RL_STATE_METANEXT
1117 RL_STATE_DISPATCHING RL_STATE_MOREINPUT RL_STATE_ISEARCH
1118 RL_STATE_NSEARCH RL_STATE_SEARCH RL_STATE_NUMERICARG
1119 RL_STATE_MACROINPUT RL_STATE_MACRODEF RL_STATE_OVERWRITE
1120 RL_STATE_COMPLETING RL_STATE_SIGHANDLER RL_STATE_UNDOING
1121 RL_STATE_INPUTPENDING RL_STATE_TTYCSAVED RL_STATE_CALLBACK
1122 RL_STATE_VIMOTION RL_STATE_MULTIKEY RL_STATE_VICMDONCE
1123 RL_STATE_CHARSEARCH RL_STATE_REDISPLAYING RL_STATE_DONE
1124 They can be exported as follows;
1126 use Term::ReadLine;
1128 BEGIN {
1129 import Term::ReadLine::Gnu qw(:keymap_type RL_STATE_INITIALIZED);
1130 }
1131
1133 The environment variable "PERL_RL" governs which ReadLine clone is
1134 loaded. See the ENVIRONMENT section on Term::ReadLine
1135 <http://search.cpan.org/dist/Term-ReadLine/> for further details.
1136
1138 Term::ReadLine::Gnu Project Home Page
1139 <http://sourceforge.net/projects/perl-trg/>
1140 GNU Readline Library Manual
1141 <https://tiswww.cwru.edu/php/chet/readline/readline.html>
1142 GNU History Library Manual
1143 <https://tiswww.cwru.edu/php/chet/readline/history.html>
1144 Sample and test programs (eg/* and t/*) in the "Term::ReadLine::Gnu"
1145 distribution <http://search.cpan.org/dist/Term-ReadLine-Gnu/>
1146 Term::ReadLine <http://search.cpan.org/dist/Term-ReadLine/>
1147 Works which use Term::ReadLine::Gnu
1148 Distributions which depend on Term::ReadLine::Gnu on CPAN
1149 <http://www.cpan.org/>
1150 <https://metacpan.org/requires/distribution/Term-ReadLine-Gnu>
1151 Perl Debugger <http://perldoc.perl.org/perldebug.html>
1153 perl -d
1154 Perl Shell (psh) <http://gnp.github.io/psh/>
1156 The Perl Shell is a shell that combines the interactive nature
1157 of a Unix shell with the power of Perl.
1158 A programmable completion feature compatible with bash is
1160 implemented.
1161 SPP (Synopsys Plus Perl)
1163 <http://vlsiweb.stanford.edu/~jsolomon/SPP/>
1164 SPP (Synopsys Plus Perl) is a Perl module that wraps around
1165 Synopsys' shell programs. SPP is inspired by the original
1166 dc_perl written by Steve Golson, but it's an entirely new
1167 implementation. Why is it called SPP and not dc_perl? Well,
1168 SPP was written to wrap around any of Synopsys' shells.
1169 PFM (Personal File Manager for Unix/Linux) <http://p-f-
1171 m.sourceforge.net/>
1172 Pfm is a terminal-based file manager written in Perl, based on
1173 PFM.COM for MS-DOS (originally by Paul Culley and Henk de
1174 Heer).
1175 The soundgrab <https://sourceforge.net/projects/soundgrab/>
1177 soundgrab is designed to help you slice up a big long raw audio
1178 file (by default 44.1 kHz 2 channel signed sixteen bit little
1179 endian) and save your favorite sections to other files. It does
1180 this by providing you with a cassette player like command line
1181 interface.
1182 PDL (The Perl Data Language) <http://pdl.perl.org/>
1184 PDL (``Perl Data Language'') gives standard Perl the ability to
1185 compactly store and speedily manipulate the large N-dimensional
1186 data arrays which are the bread and butter of scientific
1187 computing.
1188 PIQT (Perl Interactive DBI Query Tool)
1190 <http://piqt.sourceforge.net/>
1191 PIQT is an interactive query tool using the Perl DBI database
1192 interface. It supports ReadLine, provides a built in scripting
1193 language with a Lisp like syntax, an online help system, and
1194 uses wrappers to interface to the DBD modules.
1195 vshnu (the New Visual Shell)
1197 <http://www.cs.indiana.edu/~kinzler/vshnu/>
1198 A visual shell and CLI shell supplement.
1199 If you know any other works you recommend, please let me know.
1201
1203 Hiroo Hayashi "<hiroo.hayashi@computer.org>"
1204 <http://search.cpan.org/~hayashi/>
1206
1208 GTK+ support in addition to Tk.
1209
1211 Submit a bug report to rt.cpan.org
1212 <https://rt.cpan.org/Dist/Display.html?Name=Term-ReadLine-Gnu>.
1213 "add_defun()" can define up to 16 functions.
1214 Some functions and variables do not have test code yet. Your
1215 contribution is welcome. See t/readline.t for details.
1216 If the pager command (| or ||) in Perl debugger causes segmentation
1217 fault, you need to fix perl5db.pl. See
1218 <https://rt.perl.org/Public/Bug/Display.html?id=121456> for details.
1219
1221 Copyright (c) 1996-2020 Hiroo Hayashi. All rights reserved.
1222 This program is free software; you can redistribute it and/or modify it
1224 under the same terms as Perl itself.
1225perl v5.32.1 2021-01-27 Gnu(3)