```{index} single: Term::ReadLine::Gnu; Perl module ``` # Term::ReadLine::Gnu ```{pperl-module-badges} Term::ReadLine::Gnu ``` Interactive line editing, command history, and configurable key bindings, backed by the GNU Readline library. Install a readline instance, hand it a prompt, and you get the usual bash-style editing: cursor motion, word-wise kill and yank, incremental history search, filename completion, and an inputrc-controlled key map. The module is a thick binding over `libreadline.so` — nearly one hundred entry points expose readline's C surface directly, organised here by the same section names the GNU Readline manual uses. A typical script calls `new` to obtain the readline object, then `readline` in a loop with `add_history` after each accepted line. Scripts that customise behaviour reach for `rl_parse_and_bind` and `rl_variable_bind` for inputrc-style configuration, or install completion by binding `rl_completion_entry_function` via the `Attribs` tied hash. ## Functions ### Constructors #### `do_perl_setup` Force the module's deferred Perl-side setup (`%Attribs` tie, `AUTOLOAD`, constants) to run now. #### [`gnu_new`](Gnu/gnu_new) Construct a `Term::ReadLine::Gnu` object, wiring `$NAME` into `rl_readline_name` for inputrc dispatch. #### `gnu_readline_name` Return the string `"Term::ReadLine::Gnu"` for the `Term::ReadLine` backend-probing protocol. ### Basic readline #### [`rl_readline`](Gnu/rl_readline) Display a prompt, read one line with full editing, and return the entered string (or `undef` on EOF). #### `rl_initialize` Initialise (or re-initialise) readline's internal state and re-read the inputrc. Returns `0` on success. ### History #### [`add_history`](Gnu/add_history) Append `$line` to the end of the history list so it shows up in later Up-arrow recalls and searches. #### `clear_history` Delete every entry from the in-memory history list. #### `using_history` Reset the history offset pointer back to the end of the list so `previous_history` starts from the newest entry. #### `where_history` Return the current offset into the history list (the index a subsequent `current_history` would read). #### `history_set_pos` Move the history cursor to `$pos`. Returns `1` on success, `0` if the position is out of range. #### `current_history` Return the line at the current history cursor, or `undef` if the cursor is past the end. #### `history_get` Return the history line at absolute `$offset`, or `undef` if no such entry exists. #### `previous_history` Move the history cursor one step back and return that entry, or `undef` if already at the oldest line. #### `next_history` Move the history cursor one step forward and return that entry, or `undef` if already past the newest line. #### `remove_history` Delete the history entry at `$which` and return its text. #### `replace_history_entry` Replace the history entry at `$which` with `$line` and return the previous text, or `undef` if out of range. #### `stifle_history` Cap the history list at `$max` entries, or lift the cap when `$max` is `undef`. Returns the effective cap. #### `unstifle_history` Remove any stifling cap on the history list and return the previous cap (or a negative value if none was set). #### `history_is_stifled` Return non-zero if the history list is currently stifled (length-capped), zero otherwise. #### `history_total_bytes` Return the total number of bytes occupied by all history lines in memory. #### [`read_history_range`](Gnu/read_history_range) Load lines from a history file into memory. Reads the whole file by default, or lines `$from..$to` when given. #### `write_history` Write every entry in the current history list to `$filename`, overwriting the file. Returns `0` on success. #### `append_history` Append the last `$nelements` entries of the in-memory history to `$filename`, preserving existing contents. #### `history_truncate_file` Truncate `$filename` to at most `$nlines` of history, keeping the newest lines. Returns `0` on success. #### `history_expand` Apply csh-style history expansion (`!!`, `!$`, `^old^new^`) to `$line`. Returns `(code, expanded)`. **Synopsis** ```perl my ($code, $expanded) = $term->history_expand($input); **$code: 0 no change, 1 expanded, -1 error, 2 print-only** ``` #### `history_search` Search the history for an entry that contains `$string`, moving the cursor to the match. Returns the match offset or `-1`. #### `history_search_prefix` Same as `history_search`, but matches only when the history entry *starts* with `$string`. #### `history_search_pos` Search the history starting at absolute `$pos` (default: current cursor). Returns match offset or `-1`. #### `history_tokenize` Split `$text` into tokens the way Bash history expansion does (word-splitting, quote awareness). Returns a list. ### Display #### `rl_redisplay` Repaint the current line from readline's in-memory buffer. Call this after you edit the buffer programmatically. #### `rl_forced_update_display` Force a full repaint even if readline thinks nothing changed. Useful after background output corrupts the screen. #### `rl_on_new_line` Tell readline that the cursor is now on a fresh line, so the next redisplay reprints the prompt. #### `rl_on_new_line_with_prompt` Like `rl_on_new_line`, but asserts the prompt is already physically on screen — skip the reprint. #### `rl_reset_line_state` Reset the display state so the next `rl_redisplay` assumes a clean line (no partial output pending). #### `rl_message` Overlay `$text` as a status message in place of the prompt until `rl_clear_message` is called. #### `rl_clear_message` Remove the status message installed by `rl_message` and restore the original prompt. #### `rl_crlf` Emit a newline (CRLF) on the output stream, moving readline's cursor tracking with it. #### `rl_ding` Ring the terminal bell (or flash, depending on the `bell-style` inputrc setting). #### `rl_show_char` Display character `$c` using readline's usual control-character rendering (e.g. `^A` for byte 1). #### `rl_save_prompt` Save the current prompt and line state so it can be restored after a temporary message or sub-prompt. #### `rl_restore_prompt` Restore the prompt and line state previously stashed by `rl_save_prompt`. #### `rl_set_prompt` Change the prompt to `$prompt` for the next redisplay. Accepts `\[`...`\]` escapes to mark invisible regions. #### `rl_expand_prompt` Parse a prompt string for invisible-character escapes and return its visible length. ### Line editing #### `rl_insert_text` Insert `$text` into the line buffer at point, advancing the cursor past the inserted characters. #### `rl_delete_text` Delete the characters of the current line in the half-open range `[$start, $end)`. Returns the number removed. #### `rl_copy_text` Return a copy of the line buffer in the half-open range `[$start, $end)` without modifying the buffer. #### `rl_kill_text` Delete text in `[$start, $end)` and push it onto the kill ring so it becomes yankable with `C-y`. #### `rl_replace_line` Replace the entire line buffer with `$text`. Passing a truthy `$clear_undo` also drops the undo list. #### `rl_push_macro_input` Queue `$macro` as pending input so readline re-reads it character-by-character on the next key request. ### Input #### `rl_read_key` Block until one key is available on `rl_instream` and return its byte value. #### `rl_getc` Read one byte from `$stream` (defaulting to `rl_instream`), bypassing readline's macro and timeout logic. #### `rl_stuff_char` Inject one byte onto readline's pending-input queue, as if the user had just pressed it. #### `rl_execute_next` Arrange for the next call to `rl_read_key` to return `$c` without doing any terminal I/O. #### `rl_clear_pending_input` Discard any input queued with `rl_stuff_char` or `rl_execute_next`. #### `rl_set_keyboard_input_timeout` Set the multi-byte escape-sequence timeout in microseconds. Returns the previous value. ### Terminal #### `rl_prep_terminal` Put the terminal into raw mode for line editing. Pass a truthy `$meta_flag` to enable 8-bit input. #### `rl_deprep_terminal` Undo `rl_prep_terminal` and restore the terminal to cooked mode. #### `rl_reset_terminal` Re-query termcap for `$terminal_name` (default `$ENV{TERM}`), refreshing readline's idea of the terminal. #### `rl_set_screen_size` Override readline's idea of the window size with `$rows` and `$cols`. #### `rl_get_screen_size` Return the terminal size readline is currently assuming as `($rows, $cols)`. #### `rl_resize_terminal` Re-read the terminal size from the OS — typically called from a `SIGWINCH` handler. #### `rl_reset_screen_size` Force readline to re-query `TIOCGWINSZ` and reset `screenheight`/`screenwidth` from scratch. ### Character classification #### `rl_alphabetic` Return non-zero if byte `$c` is a word-constituent character under readline's locale-aware rules. ### Undo #### `rl_begin_undo_group` Open a new undo group so a sequence of edits collapses into one user-visible undo step. #### `rl_end_undo_group` Close the undo group opened by `rl_begin_undo_group`. #### `rl_do_undo` Perform one undo step. Returns `0` when no further undo is available. #### `rl_free_undo_list` Drop the entire undo history for the current line. #### `rl_modifying` Record the range `[$start, $end)` of the line buffer on the undo stack before you modify it by hand. ### Parse and configuration #### [`rl_parse_and_bind`](Gnu/rl_parse_and_bind) Apply a single line of inputrc syntax (`"\\C-x\\C-r": re-read-init-file`, `set editing-mode vi`, …). #### `rl_read_init_file` Load and apply an inputrc file. Defaults to `$ENV{INPUTRC}` or `~/.inputrc`. #### `rl_variable_bind` Set inputrc variable `$name` to the string `$value` (e.g. `completion-ignore-case`, `On`). #### `rl_variable_value` Return the current value of inputrc variable `$variable` as a string, or `undef` if it is unknown. #### `rl_variable_dumper` Print every inputrc variable and its current value to `rl_outstream`. Pass truthy `$readable` for inputrc syntax. #### `rl_function_dumper` Print every named readline command and the keys bound to it. Pass truthy `$readable` for inputrc-style output. #### `rl_macro_dumper` Print every key macro bound in the current keymap. Pass truthy `$readable` for inputrc-style output. #### `rl_get_termcap` Look up the termcap capability named `$cap` and return its string value, or `undef` if not defined. ### Signal handling #### `rl_cleanup_after_signal` Restore the terminal to cooked mode and reset signal handlers — call this from your own signal handler. #### `rl_free_line_state` Free the partially-edited line buffer so a signal-handling exit leaves readline in a clean state. #### `rl_reset_after_signal` Re-prepare the terminal and reinstall readline's signal handlers after a `SIGCONT` or similar resumption. #### `rl_check_signals` Give readline a chance to run any deferred signal handlers. #### `rl_echo_signal_char` Echo the tty-configured character for signal `$sig` (e.g. `^C` for `SIGINT`). #### `rl_pending_signal` Return the number of a signal readline has observed but not yet dispatched, or `0` if none is pending. #### `rl_set_signals` Install readline's default signal handlers (for `SIGINT`, `SIGTERM`, `SIGQUIT`, `SIGWINCH`, `SIGHUP`, …). #### `rl_clear_signals` Remove the signal handlers installed by `rl_set_signals`. ### State save and restore #### `rl_save_state` Snapshot readline's internal state and return an opaque handle you can later pass to `rl_restore_state`. #### `rl_restore_state` Reinstall the state previously captured by `rl_save_state`. ### Variable access (tied Attribs) #### `rl_fetch_str` Return readline's string global at table slot `$id` (used by the tied `%Attribs` hash). #### `rl_store_str` Write string `$value` into readline's global at table slot `$id` (used by the tied `%Attribs` hash). #### `rl_store_rl_line_buffer` Replace `rl_line_buffer` with `$value` and clamp `rl_point`/`rl_end` to the new length. #### `rl_fetch_int` Return readline's integer global at table slot `$id`, widening the native type to Perl IV. #### `rl_store_int` Write integer `$value` into readline's global at table slot `$id`, narrowing to the native type. #### `rl_store_iostream` Set `rl_instream` (`$id == 0`) or `rl_outstream` (`$id == 1`) to the given `FILE*`. #### `rl_fetch_keymap` Return the current `executing-keymap` (`$id == 0`) or `binding-keymap` (`$id == 1`) as an opaque pointer. #### [`rl_store_function`](Gnu/rl_store_function) Install a Perl code reference as the callback backing function-pointer slot `$id`. #### `rl_fetch_function` Return the Perl code reference currently stored in function-pointer slot `$id`, or `undef`. #### `rl_fetch_last_func` Return a pointer (as an integer) to the last readline command function that ran. ### Other Functions #### `stub` Stand-in for every XS entry when `libreadline.so` cannot be loaded — croaks with an install hint. ```{toctree} :hidden: :maxdepth: 1 Gnu/gnu_new Gnu/rl_readline Gnu/add_history Gnu/read_history_range Gnu/rl_parse_and_bind Gnu/rl_store_function ```