1Gnu(3)                User Contributed Perl Documentation               Gnu(3)
2
3
4

NAME

6       Term::ReadLine::Gnu - Perl extension for the GNU Readline/History
7       Library
8

SYNOPSIS

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

DESCRIPTION

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
23       For basic functions object oriented interface is provided. These are
24       described in the section "Standard Methods" and ""Term::ReadLine::Gnu"
25       Functions".
26
27       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
36       There are some "Term::ReadLine::Gnu" original features.  They are
37       described in the section ""Term::ReadLine::Gnu" Specific Features"
38
39       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
44   Standard Methods
45       These are standard methods defined by Term::ReadLine
46       <http://search.cpan.org/dist/Term-ReadLine/>.
47
48       "ReadLine"
49           returns the actual package that executes the commands. If this
50           package is being used, "Term::ReadLine::Gnu" is returned.
51
52       "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
58       "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
63           The optional argument "PREPUT" is granted only if the value
64           "preput" is in "Features".
65
66           "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
70       "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
74       "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
78       "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
83       "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
87       "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
93           See section ""Term::ReadLine::Gnu" Variables" for supported
94           variables.
95
96       "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
109       "tkRunning"
110           makes Tk event loop run when waiting for user input (i.e., during
111           "readline" method).
112
113       "event_loop"
114           See the description of "event_loop" on Term::ReadLine
115           <http://search.cpan.org/dist/Term-ReadLine/>.
116
117       "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
124       "newTTY"
125           takes two arguments which are input filehandle and output
126           filehandle.  Switches to use these filehandles.
127
128       "enableUTF8"
129           Enables UTF-8 support.
130
131           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
136           This is an original method of "Term::ReadLine:Gnu".
137
138   "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
144       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
150       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
154       Basic Behavior
155
156       The function "readline()" prints a prompt and then reads and returns a
157       single line of text from the user.
158
159               $_ = $term->readline('Enter a line: ');
160
161       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
170               $term->bind_key(ord "\ci, 'tab-insert');
171
172       The above example binds Control-I to the 'tab-insert' command.
173
174       Custom Functions
175
176       You can write new functions using Perl.  The calling sequence for a
177       command foo looks like
178
179               sub foo ($count, $key) { ... }
180
181       where $count is the numeric argument (or 1 if defaulted) and $key is
182       the key that invoked this function.
183
184       Here is an example;
185
186               sub reverse_line {              # reverse a whole line
187                   my($count, $key) = @_;      # ignored in this sample function
188
189                   $t->modifying(0, $a->{end}); # save undo information
190                   $a->{line_buffer} = reverse $a->{line_buffer};
191               }
192
193       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
197       Readline Convenience Functions
198
199       Naming a Function
200
201       "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
206             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
211       Selecting a Keymap
212
213       "make_bare_keymap"
214                   Keymap  rl_make_bare_keymap()
215
216       "copy_keymap(MAP)"
217                   Keymap  rl_copy_keymap(Keymap|str map)
218
219       "make_keymap"
220                   Keymap  rl_make_keymap()
221
222       "discard_keymap(MAP)"
223                   Keymap  rl_discard_keymap(Keymap|str map)
224
225       "free_keymap(MAP)"
226                   void    rl_free_keymap(Keymap|str map)
227
228       "empty_keymap(MAP)"
229                   int     rl_empty_keymap(Keymap|str map)                 # GRL 8.0
230
231       "get_keymap"
232                   Keymap  rl_get_keymap()
233
234       "set_keymap(MAP)"
235                   Keymap  rl_set_keymap(Keymap|str map)
236
237       "get_keymap_by_name(NAME)"
238                   Keymap  rl_get_keymap_by_name(str name)
239
240       "get_keymap_name(MAP)"
241                   str     rl_get_keymap_name(Keymap map)
242
243       "set_keymap_name(NAME, MAP)"
244                   int     rl_set_keymap_name(str name, Keymap|str map)    # GRL 8.0
245
246       Binding Keys
247
248       "bind_key(KEY, FUNCTION [,MAP])"
249                   int     rl_bind_key(int key, FunctionPtr|str function,
250                                       Keymap|str map = rl_get_keymap())
251
252           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
256       "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
260       "unbind_key(KEY [,MAP])"
261                   int     rl_unbind_key(int key, Keymap|str map = rl_get_keymap())
262
263           Bind "KEY" to the null function.  Returns non-zero in case of
264           error.
265
266       "unbind_function(FUNCTION [,MAP])"
267                   int     rl_unbind_function(FunctionPtr|str function,
268                                              Keymap|str map = rl_get_keymap())
269
270       "unbind_command(COMMAND [,MAP])"
271                   int     rl_unbind_command(str command,
272                                             Keymap|str map = rl_get_keymap())
273
274       "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
278       "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
282       "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
286       "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
291       "parse_and_bind(LINE)"
292                   void    rl_parse_and_bind(str line)
293
294           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
299       "read_init_file([FILENAME])"
300                   int     rl_read_init_file(str filename = '~/.inputrc')
301
302       Associating Function Names and Bindings
303
304       "named_function(NAME)"
305                   FunctionPtr rl_named_function(str name)
306
307       "get_function_name(FUNCTION)"
308                   str     rl_get_function_name(FunctionPtr function)      # TRG original
309
310       "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
315       "invoking_keyseqs(FUNCTION [,MAP])"
316                   (@str)  rl_invoking_keyseqs(FunctionPtr|str function,
317                                               Keymap|str map = rl_get_keymap())
318
319       "function_dumper([READABLE])"
320                   void    rl_function_dumper(int readable = 0)
321
322       "list_funmap_names"
323                   void    rl_list_funmap_names()
324
325       "funmap_names"
326                   (@str)  rl_funmap_names()
327
328       "add_funmap_entry(NAME, FUNCTION)"
329                   int     rl_add_funmap_entry(char *name, FunctionPtr|str function)
330
331       Allowing Undoing
332
333       "begin_undo_group"
334                   int     rl_begin_undo_group()
335
336       "end_undo_group"
337                   int     rl_end_undo_group()
338
339       "add_undo(WHAT, START, END, TEXT)"
340                   int     rl_add_undo(int what, int start, int end, str text)
341
342       "free_undo_list"
343                   void    rl_free_undo_list()
344
345       "do_undo"
346                   int     rl_do_undo()
347
348       "modifying([START [,END]])"
349                   int     rl_modifying(int start = 0, int end = rl_end)
350
351       Redisplay
352
353       "redisplay"
354                   void    rl_redisplay()
355
356       "forced_update_display"
357                   int     rl_forced_update_display()
358
359       "on_new_line"
360                   int     rl_on_new_line()
361
362       "on_new_line_with_prompt"
363                   int     rl_on_new_line_with_prompt()                    # GRL 4.1
364
365       "clear_visible_line()"
366                   int     rl_clear_visible_line()                         # GRL 7.0
367
368       "reset_line_state"
369                   int     rl_reset_line_state()
370
371       "crlf"
372                   int     rl_crlf()
373
374       show_char(C)
375                   int     rl_show_char(int c)
376
377       "message(FMT[, ...])"
378                   int     rl_message(str fmt, ...)
379
380       "clear_message"
381                   int     rl_clear_message()
382
383       "save_prompt"
384                   void    rl_save_prompt()
385
386       "restore_prompt"
387                   void    rl_restore_prompt()
388
389       "expand_prompt(PROMPT)"
390                   int     rl_expand_prompt(str prompt)
391
392       "set_prompt(PROMPT)"
393                   int     rl_set_prompt(const str prompt)                 # GRL 4.2
394
395       Modifying Text
396
397       "insert_text(TEXT)"
398                   int     rl_insert_text(str text)
399
400       "delete_text([START [,END]])"
401                   int     rl_delete_text(int start = 0, int end = rl_end)
402
403       "copy_text([START [,END]])"
404                   str     rl_copy_text(int start = 0, int end = rl_end)
405
406       "kill_text([START [,END]])"
407                   int     rl_kill_text(int start = 0, int end = rl_end)
408
409       "push_macro_input(MACRO)"
410                   int     rl_push_macro_input(str macro)
411
412       Character Input
413
414       "read_key"
415                   int     rl_read_key()
416
417       "getc(STREAM)"
418                   int     rl_getc(FILE *STREAM)
419
420       stuff_char(C)
421                   int     rl_stuff_char(int c)
422
423       execute_next(C)
424                   int     rl_execute_next(int c)
425
426       "clear_pending_input()"
427                   int     rl_clear_pending_input()                        # GRL 4.2
428
429       "set_keyboard_input_timeout(uSEC)"
430                   int     rl_set_keyboard_input_timeout(int usec)         # GRL 4.2
431
432       Terminal Management
433
434       "prep_terminal(META_FLAG)"
435                   void    rl_prep_terminal(int META_FLAG)
436
437       "deprep_terminal()"
438                   void    rl_deprep_terminal()
439
440       "tty_set_default_bindings([MAP])"
441                   void    rl_tty_set_default_bindings([Keymap|str map = rl_get_keymap()]) # GRL 4.0
442
443       "tty_unset_default_bindings([MAP])"
444                   void    rl_tty_unset_default_bindings([Keymap|str map = rl_get_keymap()]) # GRL 5.0
445
446       "tty_set_echoing(VALUE)"
447                   int     rl_tty_set_echoing(int value)                   # GRL 7.0
448
449       "reset_terminal([TERMINAL_NAME])"
450                   int     rl_reset_terminal(str terminal_name = getenv($TERM))
451
452       Utility Functions
453
454       "save_state(READLINE_STATE)"
455                   READLINE_STATE  rl_save_state()                         # GRL 6.0
456
457       "restore_state(READLINE_STATE)"
458                   int     rl_restore_state(READLINE_STATE)                # GRL 6.0
459
460       "free(MEM)"
461                   Not implemented since not required for Perl.
462                   int     rl_free(void *mem)                              # GRL 6.0
463
464       "replace_line(TEXT [,CLEAR_UNDO])"
465                   int     rl_replace_line(str text, int clear_undo = 0)   # GRL 4.3
466
467       "extend_line_buffer(LEN)"
468                   Not implemented since not required for Perl.
469                   int     rl_extend_line_buffer(int len)
470
471       "initialize"
472                   int     rl_initialize()
473
474       "ding"
475                   int     rl_ding()
476
477       alphabetic(C)
478                   int     rl_alphabetic(int C)                            # GRL 4.2
479
480       "display_match_list(MATCHES [,LEN [,MAX]])"
481                   void    rl_display_match_list(\@matches, len = $#maches, max) # GRL 4.0
482
483           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
488       Miscellaneous Functions
489
490       "macro_bind(KEYSEQ, MACRO [,MAP])"
491                   int     rl_macro_bind(const str keyseq, const str macro, Keymap map)
492
493       "macro_dumper(READABLE)"
494                   int     rl_macro_dumper(int readline)
495
496       "variable_bind(VARIABLE, VALUE)"
497                   int     rl_variable_bind(const str variable, const str value)
498
499       "variable_value(VARIABLE)"
500                   str     rl_variable_value(const str variable)           # GRL 5.1
501
502       "variable_dumper(READABLE)"
503                   int     rl_variable_dumper(int readline)
504
505       "set_paren_blink_timeout(uSEC)"
506                   int     rl_set_paren_blink_timeout(usec)                # GRL 4.2
507
508       "get_termcap(cap)"
509                   str     rl_get_termcap(cap)
510
511       "clear_history"
512               void        rl_clear_history()                              # GRL 6.3
513
514       Alternate Interface
515
516       "callback_handler_install(PROMPT, LHANDLER)"
517                   void    rl_callback_handler_install(str prompt, pfunc lhandler)
518
519       "callback_read_char"
520                   void    rl_callback_read_char()
521
522       "callback_sigcleanup"                        # GRL 7.0
523                   void    rl_callback_sigcleanup()
524
525       "callback_handler_remove"
526                   void    rl_callback_handler_remove()
527
528       Readline Signal Handling
529
530       "pending_signal()"
531                   int     rl_pending_signal()                             # GRL 7.0
532
533       "cleanup_after_signal"
534                   void    rl_cleanup_after_signal()                       # GRL 4.0
535
536       "free_line_state"
537                   void    rl_free_line_state()                            # GRL 4.0
538
539       "reset_after_signal"
540                   void    rl_reset_after_signal()                         # GRL 4.0
541
542       "check_signals"
543                   void    rl_check_signals()                              # GRL 8.0
544
545       "echo_signal_char"
546                   void    rl_echo_signal_char(int sig)                    # GRL 6.0
547
548       "resize_terminal"
549                   void    rl_resize_terminal()                            # GRL 4.0
550
551       "set_screen_size(ROWS, COLS)"
552                   void    rl_set_screen_size(int ROWS, int COLS)          # GRL 4.2
553
554       "get_screen_size()"
555                   (int rows, int cols)    rl_get_screen_size()            # GRL 4.2
556
557       "reset_screen_size()"
558                   void    rl_reset_screen_size()                          # GRL 5.1
559
560       "set_signals"
561                   int     rl_set_signals()                                # GRL 4.0
562
563       "clear_signals"
564                   int     rl_clear_signals()                              # GRL 4.0
565
566       Completion Functions
567
568       "complete_internal([WHAT_TO_DO])"
569                   int     rl_complete_internal(int what_to_do = TAB)
570
571       "completion_mode(FUNCTION)"
572                   int     rl_completion_mode(FunctionPtr|str function)    # GRL 4.3
573
574       "completion_matches(TEXT [,FUNC])"
575                   (@str)  rl_completion_matches(str text,
576                                                 pfunc func = filename_completion_function)
577
578       "filename_completion_function(TEXT, STATE)"
579                   str     rl_filename_completion_function(str text, int state)
580
581       "username_completion_function(TEXT, STATE)"
582                   str     rl_username_completion_function(str text, int state)
583
584       "list_completion_function(TEXT, STATE)"
585                   str     list_completion_function(str text, int state)   # TRG original
586
587       History Functions
588
589       Initializing History and State Management
590
591       "using_history"
592                   void    using_history()
593
594       "history_get_history_state"
595                   HISTORY_STATE   history_get_hitory_state()              # GRL 6.3
596
597       "history_set_history_state"
598                   void    history_set_hitory_state(HISTORY_STATE)         # GRL 6.3
599
600       History List Management
601
602       "add_history(STRING)"
603                   void    add_history(str string)
604
605       "add_history_time(STRING)"
606                   void    add_history_time(str string)                    # GRL 5.0
607
608       "remove_history(WHICH)"
609                   str     remove_history(int which)
610
611       "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
617       "replace_history_entry(WHICH, STRING)"
618                   str     replace_history_entry(int which, str string)
619
620       "clear_history"
621                   void    clear_history()
622
623       "StifleHistory(MAX)"
624                   int     stifle_history(int max|undef)
625
626           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
630       "unstifle_history"
631                   int     unstifle_history()
632
633           This is equivalent with "stifle_history(undef)".
634
635       "history_is_stifled"
636                   int     history_is_stifled()
637
638       "SetHistory(LINE1 [, LINE2, ...])"
639           sets the history of input, from where it can be used if the actual
640           "readline" is present.
641
642       Information About the History List
643
644       "history_list"
645                   Not implemented since not required for Perl.
646                   HIST_ENTRY **history_list()
647
648       "where_history"
649                   int     where_history()
650
651       "current_history"
652                   str     current_history()
653
654       "history_get(OFFSET)"
655                   str     history_get(offset)
656
657       "history_get_time(OFFSET)"
658                   time_t  history_get_time(offset)                        # GRL 5.0
659
660       "history_total_bytes"
661                   int     history_total_bytes()
662
663       "GetHistory"
664           returns the history of input as a list, if actual "readline" is
665           present.
666
667       Moving Around the History List
668
669       "history_set_pos(POS)"
670                   int     history_set_pos(int pos)
671
672       "previous_history"
673                   str     previous_history()
674
675       "next_history"
676                   str     next_history()
677
678       Searching the History List
679
680       "history_search(STRING [,DIRECTION])"
681                   int     history_search(str string, int direction = -1)
682
683       "history_search_prefix(STRING [,DIRECTION])"
684                   int     history_search_prefix(str string, int direction = -1)
685
686       "history_search_pos(STRING [,DIRECTION [,POS]])"
687                   int     history_search_pos(str string,
688                                              int direction = -1,
689                                              int pos = where_history())
690
691       Managing the History File
692
693       "ReadHistory([FILENAME [,FROM [,TO]]])"
694                   int     read_history(str filename = '~/.history',
695                                        int from = 0, int to = -1)
696
697                   int     read_history_range(str filename = '~/.history',
698                                              int from = 0, int to = -1)
699
700           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
708       "WriteHistory([FILENAME])"
709                   int     write_history(str filename = '~/.history')
710
711           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
715       "append_history(NELEMENTS [,FILENAME])"
716                   int     append_history(int nelements, str filename = '~/.history')
717
718       "history_truncate_file([FILENAME [,NLINES]])"
719                   int     history_truncate_file(str filename = '~/.history',
720                                                 int nlines = 0)
721
722       History Expansion
723
724       "history_expand(STRING)"
725                   (int result, str expansion) history_expand(str string)
726
727           Note that this function returns "expansion" in the scalar context.
728
729       "get_history_event(STRING, CINDEX [,QCHAR])"
730                   (str text, int cindex) = get_history_event(str  string,
731                                                              int  cindex,
732                                                              char qchar = '\0')
733
734       "history_tokenize(STRING)"
735                   (@str)  history_tokenize(str string)
736
737       "history_arg_extract(STRING, [FIRST [,LAST]])"
738                   str history_arg_extract(str string, int first = 0, int last = '$')
739
740   "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
750       Examples:
751
752           $attribs = $term->Attribs;
753           $v = $attribs->{library_version};   # rl_library_version
754           $v = $attribs->{history_base};      # history_base
755
756       Readline Variables
757
758               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
799       Signal Handling Variables
800
801               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
806       Completion Variables
807
808               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
842       History Variables
843
844               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
858       Function References
859
860               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
870   Custom Completion
871       In this section variables and functions for custom completion are
872       described along with examples.
873
874       Most of descriptions in this section came from GNU Readline Library
875       Manual <https://tiswww.cwru.edu/php/chet/readline/readline.html>.
876
877       "completion_entry_function"
878           This variable holds reference refers to a generator function for
879           "completion_matches()".
880
881           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
891           If this variable set to undef, built-in
892           "filename_completion_function" is used.
893
894           A sample generator function, "list_completion_function", is defined
895           in Gnu.pm.  You can use it as follows;
896
897               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
909           See also "completion_matches".
910
911       "attempted_completion_function"
912           A reference to an alternative function to create matches.
913
914           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
919           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
925           The default value of this variable is "undef".  You can use it as
926           follows;
927
928               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
946       "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
952           "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
958           If the value of "ENTRY_FUNC" is undef, built-in
959           "filename_completion_function" is used.
960
961           "completion_matches" is a Perl wrapper function of an internal
962           function "completion_matches()".  See also
963           "completion_entry_function".
964
965       "completion_function"
966           A variable whose content is a reference to a function which returns
967           a list of candidates to complete.
968
969           This variable is compatible with Term::ReadLine::Perl
970           <http://search.cpan.org/dist/Term-ReadLine-Perl/> and very easy to
971           use.
972
973               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
983       "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
988   "Term::ReadLine::Gnu" Specific Features
989       "Term::ReadLine::Gnu" Specific Functions
990
991       "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
999       "call_function(FUNCTION, [COUNT [,KEY]])"
1000                   int     rl_call_function(FunctionPtr|str function, count = 1, key = -1)
1001
1002       "get_all_function_names"
1003           Returns a list of all function names.
1004
1005       "shadow_redisplay"
1006           A redisplay function for password input.  You can use it as
1007           follows;
1008
1009                   $attribs->{redisplay_function} = $attribs->{shadow_redisplay};
1010                   $line = $term->readline("password> ");
1011
1012       "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
1018       "list_completion_function"
1019           See the description of section "Custom Completion".
1020
1021       "Term::ReadLine::Gnu" Specific Variables
1022
1023       "do_expand"
1024           When true, the history expansion is enabled.  By default false.
1025
1026       "completion_function"
1027           See the description of section "Custom Completion".
1028
1029       "completion_word"
1030           A reference to a list of candidates to complete for
1031           "list_completion_function".
1032
1033       "Term::ReadLine::Gnu" Specific Commands
1034
1035       "history-expand-line"
1036           The equivalent of the Bash "history-expand-line" editing command.
1037
1038       "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
1043           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
1047       "display-readline-version"
1048           Shows the version of "Term::ReadLine::Gnu" and the one of the GNU
1049           Readline Library.
1050
1051       "change-ornaments"
1052           Change ornaments interactively.
1053

FILES

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
1061           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
1065           For example, when your program calls "new" method as follows;
1066
1067                   ...
1068                   $term = new Term::ReadLine 'PerlSh';
1069                   ...
1070
1071           your ~/.inputrc can define key bindings only for the program as
1072           follows;
1073
1074                   ...
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
1082           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

EXPORTS

1087       No symbols are exported by default.  The following tags are defined and
1088       their symbols can be exported.
1089
1090       prompt
1091           RL_PROMPT_START_IGNORE RL_PROMPT_END_IGNORE
1092
1093       match_type
1094           NO_MATCH SINGLE_MATCH MULT_MATCH
1095
1096       keymap_type
1097           ISFUNC ISKMAP ISMACR
1098
1099       undo_code
1100           UNDO_DELETE UNDO_INSERT UNDO_BEGIN UNDO_END
1101
1102       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
1113       They can be exported as follows;
1114
1115               use Term::ReadLine;
1116               BEGIN {
1117                   import Term::ReadLine::Gnu qw(:keymap_type RL_STATE_INITIALIZED);
1118               }
1119

ENVIRONMENT

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

SEE ALSO

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
1140           Perl Debugger <http://perldoc.perl.org/perldebug.html>
1141                       perl -d
1142
1143           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
1147               A programmable completion feature compatible with bash is
1148               implemented.
1149
1150           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
1158           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
1164           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
1171           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
1177           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
1184           vshnu (the New Visual Shell)
1185           <http://www.cs.indiana.edu/~kinzler/vshnu/>
1186               A visual shell and CLI shell supplement.
1187
1188           If you know any other works you recommend, please let me know.
1189

AUTHOR

1191       Hiroo Hayashi "<hiroo.hayashi@computer.org>"
1192
1193       <http://search.cpan.org/~hayashi/>
1194

TODO

1196       GTK+ support in addition to Tk.
1197

BUGS

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

LICENSE

1209       Copyright (c) 1996-2016 Hiroo Hayashi.  All rights reserved.
1210
1211       This program is free software; you can redistribute it and/or modify it
1212       under the same terms as Perl itself.
1213
1214
1215
1216perl v5.30.1                      2020-01-30                            Gnu(3)
Impressum