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       "activate_mark"
515                   void    rl_activate_mark()                              # GRL 8.1
516
517       "deactivate_mark"
518                   void    rl_deactivate_mark()                            # GRL 8.1
519
520       "keep_mark_active"
521                   void    rl_keep_mark_active()                           # GRL 8.1
522
523       "mark_active_p"
524                   int     rl_mark_active_p()                              # GRL 8.1
525
526       Alternate Interface
527
528       "callback_handler_install(PROMPT, LHANDLER)"
529                   void    rl_callback_handler_install(str prompt, pfunc lhandler)
530
531       "callback_read_char"
532                   void    rl_callback_read_char()
533
534       "callback_sigcleanup"                        # GRL 7.0
535                   void    rl_callback_sigcleanup()
536
537       "callback_handler_remove"
538                   void    rl_callback_handler_remove()
539
540       Readline Signal Handling
541
542       "pending_signal()"
543                   int     rl_pending_signal()                             # GRL 7.0
544
545       "cleanup_after_signal"
546                   void    rl_cleanup_after_signal()                       # GRL 4.0
547
548       "free_line_state"
549                   void    rl_free_line_state()                            # GRL 4.0
550
551       "reset_after_signal"
552                   void    rl_reset_after_signal()                         # GRL 4.0
553
554       "check_signals"
555                   void    rl_check_signals()                              # GRL 8.0
556
557       "echo_signal_char"
558                   void    rl_echo_signal_char(int sig)                    # GRL 6.0
559
560       "resize_terminal"
561                   void    rl_resize_terminal()                            # GRL 4.0
562
563       "set_screen_size(ROWS, COLS)"
564                   void    rl_set_screen_size(int ROWS, int COLS)          # GRL 4.2
565
566       "get_screen_size()"
567                   (int rows, int cols)    rl_get_screen_size()            # GRL 4.2
568
569       "reset_screen_size()"
570                   void    rl_reset_screen_size()                          # GRL 5.1
571
572       "set_signals"
573                   int     rl_set_signals()                                # GRL 4.0
574
575       "clear_signals"
576                   int     rl_clear_signals()                              # GRL 4.0
577
578       Completion Functions
579
580       "complete_internal([WHAT_TO_DO])"
581                   int     rl_complete_internal(int what_to_do = TAB)
582
583       "completion_mode(FUNCTION)"
584                   int     rl_completion_mode(FunctionPtr|str function)    # GRL 4.3
585
586       "completion_matches(TEXT [,FUNC])"
587                   (@str)  rl_completion_matches(str text,
588                                                 pfunc func = filename_completion_function)
589
590       "filename_completion_function(TEXT, STATE)"
591                   str     rl_filename_completion_function(str text, int state)
592
593       "username_completion_function(TEXT, STATE)"
594                   str     rl_username_completion_function(str text, int state)
595
596       "list_completion_function(TEXT, STATE)"
597                   str     list_completion_function(str text, int state)   # TRG original
598
599       History Functions
600
601       Initializing History and State Management
602
603       "using_history"
604                   void    using_history()
605
606       "history_get_history_state"
607                   HISTORY_STATE   history_get_hitory_state()              # GRL 6.3
608
609       "history_set_history_state"
610                   void    history_set_hitory_state(HISTORY_STATE)         # GRL 6.3
611
612       History List Management
613
614       "add_history(STRING)"
615                   void    add_history(str string)
616
617       "add_history_time(STRING)"
618                   void    add_history_time(str string)                    # GRL 5.0
619
620       "remove_history(WHICH)"
621                   str     remove_history(int which)
622
623       "free_history(HISTENT)"
624                   Not implemented since Term::ReadLine::Gnu does not support the
625                   member 'data' of HIST_ENTRY structure. remove_history() frees
626                   the memory.
627                   histdata_t      free_history_entry(HIST_ENTRY *histent) # GRL 5.0
628
629       "replace_history_entry(WHICH, STRING)"
630                   str     replace_history_entry(int which, str string)
631
632       "clear_history"
633                   void    clear_history()
634
635       "StifleHistory(MAX)"
636                   int     stifle_history(int max|undef)
637
638           stifles the history list, remembering only the last "MAX" entries.
639           If "MAX" is undef, remembers all entries.  This is a replacement of
640           "unstifle_history()".
641
642       "unstifle_history"
643                   int     unstifle_history()
644
645           This is equivalent with "stifle_history(undef)".
646
647       "history_is_stifled"
648                   int     history_is_stifled()
649
650       "SetHistory(LINE1 [, LINE2, ...])"
651           sets the history of input, from where it can be used if the actual
652           "readline" is present.
653
654       Information About the History List
655
656       "history_list"
657                   Not implemented since not required for Perl.
658                   HIST_ENTRY **history_list()
659
660       "where_history"
661                   int     where_history()
662
663       "current_history"
664                   str     current_history()
665
666       "history_get(OFFSET)"
667                   str     history_get(offset)
668
669       "history_get_time(OFFSET)"
670                   time_t  history_get_time(offset)                        # GRL 5.0
671
672       "history_total_bytes"
673                   int     history_total_bytes()
674
675       "GetHistory"
676           returns the history of input as a list, if actual "readline" is
677           present.
678
679       Moving Around the History List
680
681       "history_set_pos(POS)"
682                   int     history_set_pos(int pos)
683
684       "previous_history"
685                   str     previous_history()
686
687       "next_history"
688                   str     next_history()
689
690       Searching the History List
691
692       "history_search(STRING [,DIRECTION])"
693                   int     history_search(str string, int direction = -1)
694
695       "history_search_prefix(STRING [,DIRECTION])"
696                   int     history_search_prefix(str string, int direction = -1)
697
698       "history_search_pos(STRING [,DIRECTION [,POS]])"
699                   int     history_search_pos(str string,
700                                              int direction = -1,
701                                              int pos = where_history())
702
703       Managing the History File
704
705       "ReadHistory([FILENAME [,FROM [,TO]]])"
706                   int     read_history(str filename = '~/.history',
707                                        int from = 0, int to = -1)
708
709                   int     read_history_range(str filename = '~/.history',
710                                              int from = 0, int to = -1)
711
712           adds the contents of "FILENAME" to the history list, a line at a
713           time.  If "FILENAME" is false, then read from ~/.history.  Start
714           reading at line "FROM" and end at "TO".  If "FROM" is omitted or
715           zero, start at the beginning.  If "TO" is omitted or less than
716           "FROM", then read until the end of the file.  Returns true if
717           successful, or false if not.  "read_history()" is an alias of
718           "read_history_range()".
719
720       "WriteHistory([FILENAME])"
721                   int     write_history(str filename = '~/.history')
722
723           writes the current history to "FILENAME", overwriting "FILENAME" if
724           necessary.  If "FILENAME" is false, then write the history list to
725           ~/.history.  Returns true if successful, or false if not.
726
727       "append_history(NELEMENTS [,FILENAME])"
728                   int     append_history(int nelements, str filename = '~/.history')
729
730       "history_truncate_file([FILENAME [,NLINES]])"
731                   int     history_truncate_file(str filename = '~/.history',
732                                                 int nlines = 0)
733
734       History Expansion
735
736       "history_expand(STRING)"
737                   (int result, str expansion) history_expand(str string)
738
739           Note that this function returns "expansion" in the scalar context.
740
741       "get_history_event(STRING, CINDEX [,QCHAR])"
742                   (str text, int cindex) = get_history_event(str  string,
743                                                              int  cindex,
744                                                              char qchar = '\0')
745
746       "history_tokenize(STRING)"
747                   (@str)  history_tokenize(str string)
748
749       "history_arg_extract(STRING, [FIRST [,LAST]])"
750                   str history_arg_extract(str string, int first = 0, int last = '$')
751
752   "Term::ReadLine::Gnu" Variables
753       Following GNU Readline/History Library variables can be accessed by a
754       Perl program.  See GNU Readline Library Manual
755       <https://tiswww.cwru.edu/php/chet/readline/readline.html> and GNU
756       History Library Manual
757       <https://tiswww.cwru.edu/php/chet/readline/history.html> for details of
758       each variable.  You can access them by using "Attribs" methods.  Names
759       of keys in this hash conform to standard conventions with the leading
760       "rl_" stripped.
761
762       Examples:
763
764           $attribs = $term->Attribs;
765           $v = $attribs->{library_version};   # rl_library_version
766           $v = $attribs->{history_base};      # history_base
767
768       Readline Variables
769
770               str rl_line_buffer
771               int rl_point
772               int rl_end
773               int rl_mark
774               int rl_done
775               int rl_num_chars_to_read (GRL 4.1)
776               int rl_pending_input
777               int rl_dispatching
778               int rl_erase_empty_line (GRL 4.0)
779               str rl_prompt (read only)
780               str rl_display_prompt
781               int rl_already_prompted (GRL 4.1)
782               str rl_library_version (read only)
783               int rl_readline_version (read only)
784               int rl_gnu_readline_p (GRL 4.1, read only)
785               str rl_terminal_name
786               str rl_readline_name
787               filehandle rl_instream
788               filehandle rl_outstream
789               int rl_prefer_env_winsize (GRL 5.1)
790               pfunc rl_last_func (GRL 4.2, read only)
791               pfunc rl_startup_hook
792               pfunc rl_pre_input_hook (GRL 4.0)
793               pfunc rl_event_hook
794               pfunc rl_getc_function
795               pfunc rl_signal_event_hook (GRL 6.3)
796               pfunc rl_input_available_hook (GRL 6.3)
797               pfunc rl_redisplay_function
798               pfunc rl_prep_term_function (GRL 2.1)
799               pfunc rl_deprep_term_function (GRL 2.1)
800               Keymap rl_executing_keymap (read only)
801               Keymap rl_binding_keymap (read only)
802               str rl_executing_macro (GRL 4.2, read only)
803               int rl_executing_key (GRL 6.3, read only)
804               str rl_executing_keyseq (GRL 6.3, read only)
805               int rl_key_sequence_length (read only)
806               int rl_readline_state (GRL 4.2)
807               int rl_explicit_arg (read only)
808               int rl_numeric_arg (read only)
809               int rl_editing_mode (read only)
810
811       Signal Handling Variables
812
813               int rl_catch_signals (GRL 4.0)
814               int rl_catch_sigwinch (GRL 4.0)
815               int rl_persistent_signal_handlers (GRL 7.0)
816               int rl_change_environment (GRL 6.3)
817
818       Completion Variables
819
820               pfunc rl_completion_entry_function
821               pfunc rl_attempted_completion_function
822               pfunc rl_filename_quoting_function
823               pfunc rl_filename_dequoting_function
824               pfunc rl_char_is_quoted_p
825               pfunc rl_ignore_some_completions_function
826               pfunc rl_directory_completion_hook
827               pfunc rl_directory_rewrite_hook (GRL 4.2)
828               pfunc rl_filename_stat_hook (GRL 6.3)
829               pfunc rl_filename_rewrite_hook (GRL 6.1)
830               pfunc rl_completion_display_matches_hook (GRL 4.0)
831               str rl_basic_word_break_characters
832               str rl_basic_quote_characters
833               str rl_completer_word_break_characters
834               pfunc rl_completion_word_break_hook (GRL 5.0)
835               str rl_completer_quote_characters
836               str rl_filename_quote_characters
837               str rl_special_prefixes
838               int rl_completion_query_items
839               int rl_completion_append_character
840               int rl_completion_suppress_append (GRL 4.3)
841               int rl_completion_quote_character (GRL 5.0, read only)
842               int rl_completion_suppress_quote (GRL 5.0)
843               int rl_completion_found_quote (GRL 5.0, read only)
844               int rl_completion_mark_symlink_dirs (GRL 4.3)
845               int rl_ignore_completion_duplicates
846               int rl_filename_completion_desired
847               int rl_filename_quoting_desired
848               int rl_attempted_completion_over
849               int rl_sort_completion_matches (GRL 6.0)
850               int rl_completion_type (read only)
851               int rl_completion_invoking_key (GRL 6.0, read only)
852               int rl_inhibit_completion
853
854       History Variables
855
856               int history_base
857               int history_length
858               int history_max_entries (called `max_input_history', read only)
859               int history_write_timestamps (GRL 5.0)
860               char history_expansion_char
861               char history_subst_char
862               char history_comment_char
863               str history_word_delimiters (GRL 4.2)
864               str history_search_delimiter_chars
865               str history_no_expand_chars
866               int history_quotes_inhibit_expansion
867               int history_quoting_state
868               pfunc history_inhibit_expansion_function
869
870       Function References
871
872               rl_getc
873               rl_redisplay
874               rl_callback_read_char
875               rl_display_match_list
876               rl_filename_completion_function
877               rl_username_completion_function
878               list_completion_function
879               shadow_redisplay
880               Tk_getc
881
882   Custom Completion
883       In this section variables and functions for custom completion are
884       described along with examples.
885
886       Most of descriptions in this section came from GNU Readline Library
887       Manual <https://tiswww.cwru.edu/php/chet/readline/readline.html>.
888
889       "completion_entry_function"
890           This variable holds reference refers to a generator function for
891           "completion_matches()".
892
893           A generator function is called repeatedly from
894           "completion_matches()", returning a string each time.  The
895           arguments to the generator function are "TEXT" and "STATE".  "TEXT"
896           is the partial word to be completed.  "STATE" is zero the first
897           time the function is called, allowing the generator to perform any
898           necessary initialization, and a positive non-zero integer for each
899           subsequent call.  When the generator function returns "undef" this
900           signals "completion_matches()" that there are no more possibilities
901           left.
902
903           If this variable set to undef, built-in
904           "filename_completion_function" is used.
905
906           A sample generator function, "list_completion_function", is defined
907           in Gnu.pm.  You can use it as follows;
908
909               use Term::ReadLine;
910               ...
911               my $term = new Term::ReadLine 'sample';
912               my $attribs = $term->Attribs;
913               ...
914               $attribs->{completion_entry_function} =
915                   $attribs->{list_completion_function};
916               ...
917               $attribs->{completion_word} =
918                   [qw(reference to a list of words which you want to use for completion)];
919               $term->readline("custom completion>");
920
921           See also "completion_matches".
922
923       "attempted_completion_function"
924           A reference to an alternative function to create matches.
925
926           The function is called with "TEXT", "LINE_BUFFER", "START", and
927           "END".  "LINE_BUFFER" is a current input buffer string.  "START"
928           and "END" are indices in "LINE_BUFFER" saying what the boundaries
929           of "TEXT" are.
930
931           If this function exists and returns null list or "undef", or if
932           this variable is set to "undef", then an internal function
933           "rl_complete()" will call the value of "completion_entry_function"
934           to generate matches, otherwise the array of strings returned will
935           be used.
936
937           The default value of this variable is "undef".  You can use it as
938           follows;
939
940               use Term::ReadLine;
941               ...
942               my $term = new Term::ReadLine 'sample';
943               my $attribs = $term->Attribs;
944               ...
945               sub sample_completion {
946                   my ($text, $line, $start, $end) = @_;
947                   # If first word then username completion, else filename completion
948                   if (substr($line, 0, $start) =~ /^\s*$/) {
949                       return $term->completion_matches($text,
950                                                        $attribs->{'username_completion_function'});
951                   } else {
952                       return ();
953                   }
954               }
955               ...
956               $attribs->{attempted_completion_function} = \&sample_completion;
957
958       "completion_matches(TEXT, ENTRY_FUNC)"
959           Returns an array of strings which is a list of completions for
960           "TEXT".  If there are no completions, returns "undef".  The first
961           entry in the returned array is the substitution for "TEXT".  The
962           remaining entries are the possible completions.
963
964           "ENTRY_FUNC" is a generator function which has two arguments, and
965           returns a string.  The first argument is "TEXT".  The second is a
966           state argument; it is zero on the first call, and non-zero on
967           subsequent calls.  "ENTRY_FUNC" returns "undef" to the caller when
968           there are no more matches.
969
970           If the value of "ENTRY_FUNC" is undef, built-in
971           "filename_completion_function" is used.
972
973           "completion_matches" is a Perl wrapper function of an internal
974           function "completion_matches()".  See also
975           "completion_entry_function".
976
977       "completion_function"
978           A variable whose content is a reference to a function which returns
979           a list of candidates to complete.
980
981           This variable is compatible with Term::ReadLine::Perl
982           <http://search.cpan.org/dist/Term-ReadLine-Perl/> and very easy to
983           use.
984
985               use Term::ReadLine;
986               ...
987               my $term = new Term::ReadLine 'sample';
988               my $attribs = $term->Attribs;
989               ...
990               $attribs->{completion_function} = sub {
991                   my ($text, $line, $start) = @_;
992                   return qw(a list of candidates to complete);
993               };
994
995       "list_completion_function(TEXT, STATE)"
996           A sample generator function defined by "Term::ReadLine::Gnu".
997           Example code at "completion_entry_function" shows how to use this
998           function.
999
1000   "Term::ReadLine::Gnu" Specific Features
1001       "Term::ReadLine::Gnu" Specific Functions
1002
1003       "CallbackHandlerInstall(PROMPT, LHANDLER)"
1004           This method provides the function "rl_callback_handler_install()"
1005           with the following additional feature compatible with "readline"
1006           method; ornament feature, Term::ReadLine::Perl
1007           <http://search.cpan.org/dist/Term-ReadLine-Perl/> compatible
1008           completion function, history expansion, and addition to history
1009           buffer.
1010
1011       "call_function(FUNCTION, [COUNT [,KEY]])"
1012                   int     rl_call_function(FunctionPtr|str function, count = 1, key = -1)
1013
1014       "get_all_function_names"
1015           Returns a list of all function names.
1016
1017       "shadow_redisplay"
1018           A redisplay function for password input.  You can use it as
1019           follows;
1020
1021                   $attribs->{redisplay_function} = $attribs->{shadow_redisplay};
1022                   $line = $term->readline("password> ");
1023
1024       "filename_list"
1025           Returns candidates of filenames to complete.  This function can be
1026           used with "completion_function" and is implemented for the
1027           compatibility with Term::ReadLine::Perl
1028           <http://search.cpan.org/dist/Term-ReadLine-Perl/>.
1029
1030       "list_completion_function"
1031           See the description of section "Custom Completion".
1032
1033       "Term::ReadLine::Gnu" Specific Variables
1034
1035       "do_expand"
1036           When true, the history expansion is enabled.  By default false.
1037
1038       "completion_function"
1039           See the description of section "Custom Completion".
1040
1041       "completion_word"
1042           A reference to a list of candidates to complete for
1043           "list_completion_function".
1044
1045       "Term::ReadLine::Gnu" Specific Commands
1046
1047       "history-expand-line"
1048           The equivalent of the Bash "history-expand-line" editing command.
1049
1050       "operate-and-get-next"
1051           The equivalent of the Korn shell
1052           "operate-and-get-next-history-line" editing command and the Bash
1053           "operate-and-get-next".
1054
1055           This command is bound to "\C-o" by default for the compatibility
1056           with the Bash and Term::ReadLine::Perl
1057           <http://search.cpan.org/dist/Term-ReadLine-Perl/>.
1058
1059       "display-readline-version"
1060           Shows the version of "Term::ReadLine::Gnu" and the one of the GNU
1061           Readline Library.
1062
1063       "change-ornaments"
1064           Change ornaments interactively.
1065

FILES

1067       ~/.inputrc
1068           Readline init file.  Using this file it is possible that you would
1069           like to use a different set of key bindings.  When a program which
1070           uses the GNU Readline library starts up, the init file is read, and
1071           the key bindings are set.
1072
1073           The conditional init constructs is supported.  The program name
1074           which is specified by the first argument of "new" method is used as
1075           the application construct.
1076
1077           For example, when your program calls "new" method as follows;
1078
1079                   ...
1080                   $term = new Term::ReadLine 'PerlSh';
1081                   ...
1082
1083           your ~/.inputrc can define key bindings only for the program as
1084           follows;
1085
1086                   ...
1087                   $if PerlSh
1088                   Meta-Rubout: backward-kill-word
1089                   "\C-x\C-r": re-read-init-file
1090                   "\e[11~": "Function Key 1"
1091                   $endif
1092                   ...
1093
1094           For further details, see the section "Readline Init File" in the
1095           GNU Readline Library Manual
1096           <https://tiswww.cwru.edu/php/chet/readline/readline.html>
1097

EXPORTS

1099       No symbols are exported by default.  The following tags are defined and
1100       their symbols can be exported.
1101
1102       prompt
1103           RL_PROMPT_START_IGNORE RL_PROMPT_END_IGNORE
1104
1105       match_type
1106           NO_MATCH SINGLE_MATCH MULT_MATCH
1107
1108       keymap_type
1109           ISFUNC ISKMAP ISMACR
1110
1111       undo_code
1112           UNDO_DELETE UNDO_INSERT UNDO_BEGIN UNDO_END
1113
1114       rl_state
1115           RL_STATE_NONE RL_STATE_INITIALIZING RL_STATE_INITIALIZED
1116           RL_STATE_TERMPREPPED RL_STATE_READCMD RL_STATE_METANEXT
1117           RL_STATE_DISPATCHING RL_STATE_MOREINPUT RL_STATE_ISEARCH
1118           RL_STATE_NSEARCH RL_STATE_SEARCH RL_STATE_NUMERICARG
1119           RL_STATE_MACROINPUT RL_STATE_MACRODEF RL_STATE_OVERWRITE
1120           RL_STATE_COMPLETING RL_STATE_SIGHANDLER RL_STATE_UNDOING
1121           RL_STATE_INPUTPENDING RL_STATE_TTYCSAVED RL_STATE_CALLBACK
1122           RL_STATE_VIMOTION RL_STATE_MULTIKEY RL_STATE_VICMDONCE
1123           RL_STATE_CHARSEARCH RL_STATE_REDISPLAYING RL_STATE_DONE
1124
1125       They can be exported as follows;
1126
1127               use Term::ReadLine;
1128               BEGIN {
1129                   import Term::ReadLine::Gnu qw(:keymap_type RL_STATE_INITIALIZED);
1130               }
1131

ENVIRONMENT

1133       The environment variable "PERL_RL" governs which ReadLine clone is
1134       loaded.  See the ENVIRONMENT section on Term::ReadLine
1135       <http://search.cpan.org/dist/Term-ReadLine/> for further details.
1136

SEE ALSO

1138       Term::ReadLine::Gnu Project Home Page <https://github.com/hirooih/perl-
1139       trg>
1140       GNU Readline Library Manual
1141       <https://tiswww.cwru.edu/php/chet/readline/readline.html>
1142       GNU History Library Manual
1143       <https://tiswww.cwru.edu/php/chet/readline/history.html>
1144       Sample and test programs (eg/* and t/*) in the "Term::ReadLine::Gnu"
1145       distribution <http://search.cpan.org/dist/Term-ReadLine-Gnu/>
1146       Term::ReadLine <http://search.cpan.org/dist/Term-ReadLine/>
1147       Works which use Term::ReadLine::Gnu
1148           Distributions which depend on Term::ReadLine::Gnu on CPAN
1149           <http://www.cpan.org/>
1150               <https://metacpan.org/requires/distribution/Term-ReadLine-Gnu>
1151
1152           Perl Debugger <http://perldoc.perl.org/perldebug.html>
1153                       perl -d
1154
1155           Perl Shell (psh) <http://gnp.github.io/psh/>
1156               The Perl Shell is a shell that combines the interactive nature
1157               of a Unix shell with the power of Perl.
1158
1159               A programmable completion feature compatible with bash is
1160               implemented.
1161
1162           SPP (Synopsys Plus Perl)
1163           <http://vlsiweb.stanford.edu/~jsolomon/SPP/>
1164               SPP (Synopsys Plus Perl) is a Perl module that wraps around
1165               Synopsys' shell programs.  SPP is inspired by the original
1166               dc_perl written by Steve Golson, but it's an entirely new
1167               implementation.  Why is it called SPP and not dc_perl?  Well,
1168               SPP was written to wrap around any of Synopsys' shells.
1169
1170           PFM (Personal File Manager for Unix/Linux) <http://p-f-
1171           m.sourceforge.net/>
1172               Pfm is a terminal-based file manager written in Perl, based on
1173               PFM.COM for MS-DOS (originally by Paul Culley and Henk de
1174               Heer).
1175
1176           The soundgrab <https://sourceforge.net/projects/soundgrab/>
1177               soundgrab is designed to help you slice up a big long raw audio
1178               file (by default 44.1 kHz 2 channel signed sixteen bit little
1179               endian) and save your favorite sections to other files. It does
1180               this by providing you with a cassette player like command line
1181               interface.
1182
1183           PDL (The Perl Data Language) <http://pdl.perl.org/>
1184               PDL (``Perl Data Language'') gives standard Perl the ability to
1185               compactly store and speedily manipulate the large N-dimensional
1186               data arrays which are the bread and butter of scientific
1187               computing.
1188
1189           PIQT (Perl Interactive DBI Query Tool)
1190           <http://piqt.sourceforge.net/>
1191               PIQT is an interactive query tool using the Perl DBI database
1192               interface. It supports ReadLine, provides a built in scripting
1193               language with a Lisp like syntax, an online help system, and
1194               uses wrappers to interface to the DBD modules.
1195
1196           vshnu (the New Visual Shell)
1197           <http://www.cs.indiana.edu/~kinzler/vshnu/>
1198               A visual shell and CLI shell supplement.
1199
1200           If you know any other works you recommend, please let me know.
1201

AUTHOR

1203       Hiroo Hayashi "<hiroo.hayashi@computer.org>"
1204
1205       <http://search.cpan.org/~hayashi/>
1206

TODO

1208       GTK+ support in addition to Tk.
1209

BUGS

1211       Submit a bug report to the bug tracker on GitHub
1212       <https://github.com/hirooih/perl-trg/issues>.
1213       "add_defun()" can define up to 16 functions.
1214       Some functions and variables do not have test code yet.  Your
1215       contribution is welcome.  See t/readline.t for details.
1216       If the pager command (| or ||) in Perl debugger causes segmentation
1217       fault, you need to fix perl5db.pl.  See
1218       <https://rt.perl.org/Public/Bug/Display.html?id=121456> for details.
1219

LICENSE

1221       Copyright (c) 1996-2020 Hiroo Hayashi.  All rights reserved.
1222
1223       This program is free software; you can redistribute it and/or modify it
1224       under the same terms as Perl itself.
1225
1226
1227
1228perl v5.36.0                      2022-07-22                            Gnu(3)
Impressum