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       "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
319       "invoking_keyseqs(FUNCTION [,MAP])"
320                   (@str)  rl_invoking_keyseqs(FunctionPtr|str function,
321                                               Keymap|str map = rl_get_keymap())
322
323       function_dumper([READABLE])
324                   void    rl_function_dumper(int readable = 0)
325
326       "list_funmap_names"
327                   void    rl_list_funmap_names()
328
329       "funmap_names"
330                   (@str)  rl_funmap_names()
331
332       "add_funmap_entry(NAME, FUNCTION)"
333                   int     rl_add_funmap_entry(char *name, FunctionPtr|str function)
334
335       Allowing Undoing
336
337       "begin_undo_group"
338                   int     rl_begin_undo_group()
339
340       "end_undo_group"
341                   int     rl_end_undo_group()
342
343       "add_undo(WHAT, START, END, TEXT)"
344                   int     rl_add_undo(int what, int start, int end, str text)
345
346       "free_undo_list"
347                   void    rl_free_undo_list()
348
349       "do_undo"
350                   int     rl_do_undo()
351
352       "modifying([START [,END]])"
353                   int     rl_modifying(int start = 0, int end = rl_end)
354
355       Redisplay
356
357       "redisplay"
358                   void    rl_redisplay()
359
360       "forced_update_display"
361                   int     rl_forced_update_display()
362
363       "on_new_line"
364                   int     rl_on_new_line()
365
366       "on_new_line_with_prompt"
367                   int     rl_on_new_line_with_prompt()                    # GRL 4.1
368
369       clear_visible_line()
370                   int     rl_clear_visible_line()                         # GRL 7.0
371
372       "reset_line_state"
373                   int     rl_reset_line_state()
374
375       "crlf"
376                   int     rl_crlf()
377
378       show_char(C)
379                   int     rl_show_char(int c)
380
381       "message(FMT[, ...])"
382                   int     rl_message(str fmt, ...)
383
384       "clear_message"
385                   int     rl_clear_message()
386
387       "save_prompt"
388                   void    rl_save_prompt()
389
390       "restore_prompt"
391                   void    rl_restore_prompt()
392
393       expand_prompt(PROMPT)
394                   int     rl_expand_prompt(str prompt)
395
396       set_prompt(PROMPT)
397                   int     rl_set_prompt(const str prompt)                 # GRL 4.2
398
399       Modifying Text
400
401       insert_text(TEXT)
402                   int     rl_insert_text(str text)
403
404       "delete_text([START [,END]])"
405                   int     rl_delete_text(int start = 0, int end = rl_end)
406
407       "copy_text([START [,END]])"
408                   str     rl_copy_text(int start = 0, int end = rl_end)
409
410       "kill_text([START [,END]])"
411                   int     rl_kill_text(int start = 0, int end = rl_end)
412
413       push_macro_input(MACRO)
414                   int     rl_push_macro_input(str macro)
415
416       Character Input
417
418       "read_key"
419                   int     rl_read_key()
420
421       getc(STREAM)
422                   int     rl_getc(FILE *STREAM)
423
424       stuff_char(C)
425                   int     rl_stuff_char(int c)
426
427       execute_next(C)
428                   int     rl_execute_next(int c)
429
430       clear_pending_input()
431                   int     rl_clear_pending_input()                        # GRL 4.2
432
433       set_keyboard_input_timeout(uSEC)
434                   int     rl_set_keyboard_input_timeout(int usec)         # GRL 4.2
435
436       "set_timeout(SECS, USECS)"
437                   int     rl_set_timeout(int secs, int usecs)             # GRL 8.2
438
439       clear_timeout()
440                   int     rl_clear_timeout()                              # GRL 8.2
441
442       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
446       Terminal Management
447
448       prep_terminal(META_FLAG)
449                   void    rl_prep_terminal(int META_FLAG)
450
451       deprep_terminal()
452                   void    rl_deprep_terminal()
453
454       tty_set_default_bindings([MAP])
455                   void    rl_tty_set_default_bindings([Keymap|str map = rl_get_keymap()]) # GRL 4.0
456
457       tty_unset_default_bindings([MAP])
458                   void    rl_tty_unset_default_bindings([Keymap|str map = rl_get_keymap()]) # GRL 5.0
459
460       tty_set_echoing(VALUE)
461                   int     rl_tty_set_echoing(int value)                   # GRL 7.0
462
463       reset_terminal([TERMINAL_NAME])
464                   int     rl_reset_terminal(str terminal_name = getenv($TERM))
465
466       Utility Functions
467
468       save_state(READLINE_STATE)
469                   READLINE_STATE  rl_save_state()                         # GRL 6.0
470
471       restore_state(READLINE_STATE)
472                   int     rl_restore_state(READLINE_STATE)                # GRL 6.0
473
474       free(MEM)
475                   Not implemented since not required for Perl.
476                   int     rl_free(void *mem)                              # GRL 6.0
477
478       "replace_line(TEXT [,CLEAR_UNDO])"
479                   int     rl_replace_line(str text, int clear_undo = 0)   # GRL 4.3
480
481       extend_line_buffer(LEN)
482                   Not implemented since not required for Perl.
483                   int     rl_extend_line_buffer(int len)
484
485       "initialize"
486                   int     rl_initialize()
487
488       "ding"
489                   int     rl_ding()
490
491       alphabetic(C)
492                   int     rl_alphabetic(int C)                            # GRL 4.2
493
494       "display_match_list(MATCHES [,LEN [,MAX]])"
495                   void    rl_display_match_list(\@matches, len = $#maches, max) # GRL 4.0
496
497           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
502       Miscellaneous Functions
503
504       "macro_bind(KEYSEQ, MACRO [,MAP])"
505                   int     rl_macro_bind(const str keyseq, const str macro, Keymap map)
506
507       macro_dumper(READABLE)
508                   int     rl_macro_dumper(int readline)
509
510       "variable_bind(VARIABLE, VALUE)"
511                   int     rl_variable_bind(const str variable, const str value)
512
513       variable_value(VARIABLE)
514                   str     rl_variable_value(const str variable)           # GRL 5.1
515
516       variable_dumper(READABLE)
517                   int     rl_variable_dumper(int readline)
518
519       set_paren_blink_timeout(uSEC)
520                   int     rl_set_paren_blink_timeout(usec)                # GRL 4.2
521
522       get_termcap(cap)
523                   str     rl_get_termcap(cap)
524
525       "clear_history"
526                   void    rl_clear_history()                              # GRL 6.3
527
528       "activate_mark"
529                   void    rl_activate_mark()                              # GRL 8.1
530
531       "deactivate_mark"
532                   void    rl_deactivate_mark()                            # GRL 8.1
533
534       "keep_mark_active"
535                   void    rl_keep_mark_active()                           # GRL 8.1
536
537       "mark_active_p"
538                   int     rl_mark_active_p()                              # GRL 8.1
539
540       Alternate Interface
541
542       "callback_handler_install(PROMPT, LHANDLER)"
543                   void    rl_callback_handler_install(str prompt, pfunc lhandler)
544
545       "callback_read_char"
546                   void    rl_callback_read_char()
547
548       "callback_sigcleanup"                                    # GRL 7.0
549                   void    rl_callback_sigcleanup()
550
551       "callback_handler_remove"
552                   void    rl_callback_handler_remove()
553
554       Readline Signal Handling
555
556       pending_signal()
557                   int     rl_pending_signal()                             # GRL 7.0
558
559       "cleanup_after_signal"
560                   void    rl_cleanup_after_signal()                       # GRL 4.0
561
562       "free_line_state"
563                   void    rl_free_line_state()                            # GRL 4.0
564
565       "reset_after_signal"
566                   void    rl_reset_after_signal()                         # GRL 4.0
567
568       "check_signals"
569                   void    rl_check_signals()                              # GRL 8.0
570
571       "echo_signal_char"
572                   void    rl_echo_signal_char(int sig)                    # GRL 6.0
573
574       "resize_terminal"
575                   void    rl_resize_terminal()                            # GRL 4.0
576
577       "set_screen_size(ROWS, COLS)"
578                   void    rl_set_screen_size(int ROWS, int COLS)          # GRL 4.2
579
580       get_screen_size()
581                   (int rows, int cols)    rl_get_screen_size()            # GRL 4.2
582
583       reset_screen_size()
584                   void    rl_reset_screen_size()                          # GRL 5.1
585
586       "set_signals"
587                   int     rl_set_signals()                                # GRL 4.0
588
589       "clear_signals"
590                   int     rl_clear_signals()                              # GRL 4.0
591
592       Completion Functions
593
594       complete_internal([WHAT_TO_DO])
595                   int     rl_complete_internal(int what_to_do = TAB)
596
597       completion_mode(FUNCTION)
598                   int     rl_completion_mode(FunctionPtr|str function)    # GRL 4.3
599
600       "completion_matches(TEXT [,FUNC])"
601                   (@str)  rl_completion_matches(str text,
602                                                 pfunc func = filename_completion_function)
603
604       "filename_completion_function(TEXT, STATE)"
605                   str     rl_filename_completion_function(str text, int state)
606
607       "username_completion_function(TEXT, STATE)"
608                   str     rl_username_completion_function(str text, int state)
609
610       "list_completion_function(TEXT, STATE)"
611                   str     list_completion_function(str text, int state)   # TRG original
612
613       History Functions
614
615       Initializing History and State Management
616
617       "using_history"
618                   void    using_history()
619
620       "history_get_history_state"
621                   HISTORY_STATE   history_get_hitory_state()              # GRL 6.3
622
623       "history_set_history_state"
624                   void    history_set_hitory_state(HISTORY_STATE)         # GRL 6.3
625
626       History List Management
627
628       add_history(STRING)
629                   void    add_history(str string)
630
631       add_history_time(STRING)
632                   void    add_history_time(str string)                    # GRL 5.0
633
634       remove_history(WHICH)
635                   str     remove_history(int which)
636
637       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
643       "replace_history_entry(WHICH, STRING)"
644                   str     replace_history_entry(int which, str string)
645
646       "clear_history"
647                   void    clear_history()
648
649       StifleHistory(MAX)
650                   int     stifle_history(int max|undef)
651
652           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
656       "unstifle_history"
657                   int     unstifle_history()
658
659           This is equivalent with stifle_history(undef).
660
661       "history_is_stifled"
662                   int     history_is_stifled()
663
664       "SetHistory(LINE1 [, LINE2, ...])"
665           sets the history of input, from where it can be used if the actual
666           "readline" is present.
667
668       Information About the History List
669
670       "history_list"
671                   Not implemented since not required for Perl.
672                   HIST_ENTRY **history_list()
673
674       "where_history"
675                   int     where_history()
676
677       "current_history"
678                   str     current_history()
679
680       history_get(OFFSET)
681                   str     history_get(offset)
682
683       history_get_time(OFFSET)
684                   time_t  history_get_time(offset)                        # GRL 5.0
685
686       "history_total_bytes"
687                   int     history_total_bytes()
688
689       "GetHistory"
690           returns the history of input as a list, if actual "readline" is
691           present.
692
693       Moving Around the History List
694
695       history_set_pos(POS)
696                   int     history_set_pos(int pos)
697
698       "previous_history"
699                   str     previous_history()
700
701       "next_history"
702                   str     next_history()
703
704       Searching the History List
705
706       "history_search(STRING [,DIRECTION])"
707                   int     history_search(str string, int direction = -1)
708
709       "history_search_prefix(STRING [,DIRECTION])"
710                   int     history_search_prefix(str string, int direction = -1)
711
712       "history_search_pos(STRING [,DIRECTION [,POS]])"
713                   int     history_search_pos(str string,
714                                              int direction = -1,
715                                              int pos = where_history())
716
717       Managing the History File
718
719       "ReadHistory([FILENAME [,FROM [,TO]]])"
720                   int     read_history(str filename = '~/.history',
721                                        int from = 0, int to = -1)
722
723                   int     read_history_range(str filename = '~/.history',
724                                              int from = 0, int to = -1)
725
726           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
734       WriteHistory([FILENAME])
735                   int     write_history(str filename = '~/.history')
736
737           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
741       "append_history(NELEMENTS [,FILENAME])"
742                   int     append_history(int nelements, str filename = '~/.history')
743
744       "history_truncate_file([FILENAME [,NLINES]])"
745                   int     history_truncate_file(str filename = '~/.history',
746                                                 int nlines = 0)
747
748       History Expansion
749
750       history_expand(STRING)
751                   (int result, str expansion) history_expand(str string)
752
753           Note that this function returns "expansion" in the scalar context.
754
755       "get_history_event(STRING, CINDEX [,QCHAR])"
756                   (str text, int cindex) = get_history_event(str  string,
757                                                              int  cindex,
758                                                              char qchar = '\0')
759
760       history_tokenize(STRING)
761                   (@str)  history_tokenize(str string)
762
763       "history_arg_extract(STRING, [FIRST [,LAST]])"
764                   str history_arg_extract(str string, int first = 0, int last = '$')
765
766   "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
776       Examples:
777
778           $attribs = $term->Attribs;
779           $v = $attribs->{library_version};   # rl_library_version
780           $v = $attribs->{history_base};      # history_base
781
782       Readline Variables
783
784               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
827       Signal Handling Variables
828
829               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
834       Completion Variables
835
836               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
870       History Variables
871
872               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
886       Function References
887
888               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
898   Custom Completion
899       In this section variables and functions for custom completion are
900       described along with examples.
901
902       Most of descriptions in this section came from GNU Readline Library
903       Manual <https://tiswww.cwru.edu/php/chet/readline/readline.html>.
904
905       "completion_entry_function"
906           This variable holds reference refers to a generator function for
907           completion_matches().
908
909           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
918           If this variable set to undef, built-in
919           "filename_completion_function" is used.
920
921           A sample generator function, "list_completion_function", is defined
922           in Gnu.pm.  You can use it as follows;
923
924               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
936           See also "completion_matches".
937
938       "attempted_completion_function"
939           A reference to an alternative function to create matches.
940
941           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
946           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
952           The default value of this variable is "undef".  You can use it as
953           follows;
954
955               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
973       "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
979           "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
985           If the value of "ENTRY_FUNC" is undef, built-in
986           "filename_completion_function" is used.
987
988           "completion_matches" is a Perl wrapper function of an internal
989           function completion_matches().  See also
990           "completion_entry_function".
991
992       "completion_function"
993           A variable whose content is a reference to a function which returns
994           a list of candidates to complete.
995
996           This variable is compatible with Term::ReadLine::Perl
997           <http://search.cpan.org/dist/Term-ReadLine-Perl/> and very easy to
998           use.
999
1000               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
1010       "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
1015   "Term::ReadLine::Gnu" Specific Features
1016       "Term::ReadLine::Gnu" Specific Functions
1017
1018       "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
1026       "call_function(FUNCTION, [COUNT [,KEY]])"
1027                   int     rl_call_function(FunctionPtr|str function, count = 1, key = -1)
1028
1029       "get_all_function_names"
1030           Returns a list of all function names.
1031
1032       "shadow_redisplay"
1033           A redisplay function for password input.  You can use it as
1034           follows;
1035
1036                   $attribs->{redisplay_function} = $attribs->{shadow_redisplay};
1037                   $line = $term->readline("password> ");
1038
1039       "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
1045       "list_completion_function"
1046           See the description of section "Custom Completion".
1047
1048       "Term::ReadLine::Gnu" Specific Variables
1049
1050       "do_expand"
1051           When true, the history expansion is enabled.  By default false.
1052
1053       "completion_function"
1054           See the description of section "Custom Completion".
1055
1056       "completion_word"
1057           A reference to a list of candidates to complete for
1058           "list_completion_function".
1059
1060       "Term::ReadLine::Gnu" Specific Commands
1061
1062       "history-expand-line"
1063           The equivalent of the Bash "history-expand-line" editing command.
1064
1065       "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
1070           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
1074       "display-readline-version"
1075           Shows the version of "Term::ReadLine::Gnu" and the one of the GNU
1076           Readline Library.
1077
1078       "change-ornaments"
1079           Change ornaments interactively.
1080

FILES

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
1088           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
1092           For example, when your program calls "new" method as follows;
1093
1094                   ...
1095                   $term = new Term::ReadLine 'PerlSh';
1096                   ...
1097
1098           your ~/.inputrc can define key bindings only for the program as
1099           follows;
1100
1101                   ...
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
1109           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

EXPORTS

1114       No symbols are exported by default.  The following tags are defined and
1115       their symbols can be exported.
1116
1117       prompt
1118           RL_PROMPT_START_IGNORE RL_PROMPT_END_IGNORE
1119
1120       match_type
1121           NO_MATCH SINGLE_MATCH MULT_MATCH
1122
1123       keymap_type
1124           ISFUNC ISKMAP ISMACR
1125
1126       undo_code
1127           UNDO_DELETE UNDO_INSERT UNDO_BEGIN UNDO_END
1128
1129       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
1141       They can be exported as follows;
1142
1143               use Term::ReadLine;
1144               BEGIN {
1145                   import Term::ReadLine::Gnu qw(:keymap_type RL_STATE_INITIALIZED);
1146               }
1147

ENVIRONMENT

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
1153       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

SEE ALSO

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
1172           Perl Debugger <http://perldoc.perl.org/perldebug.html>
1173                       perl -d
1174
1175           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
1179               A programmable completion feature compatible with bash is
1180               implemented.
1181
1182           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
1190           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
1196           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
1203           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
1209           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
1216           vshnu (the New Visual Shell)
1217           <http://www.cs.indiana.edu/~kinzler/vshnu/>
1218               A visual shell and CLI shell supplement.
1219
1220           If you know any other works you recommend, please let me know.
1221

AUTHOR

1223       Hiroo Hayashi "<hiroo.hayashi@computer.org>"
1224
1225       <http://search.cpan.org/~hayashi/>
1226

TODO

1228       GTK+ support in addition to Tk.
1229

BUGS

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

LICENSE

1241       Copyright (c) 1996-2020 Hiroo Hayashi.  All rights reserved.
1242
1243       This program is free software; you can redistribute it and/or modify it
1244       under the same terms as Perl itself.
1245
1246
1247
1248perl v5.36.0                      2023-01-20                            Gnu(3)
Impressum