<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from Term/ReadLine/Gnu.rs. Do not edit. -->


# Term::ReadLine::Gnu

<div class="pperl-badges"><span class="pperl-badge pperl-tier-max" title="Minimum feature tier: max. Available in all builds from \`--features native-max\` upward.">📦 max</span></div>

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.md)

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.md)

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.md)

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.md)

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.md)

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.md)

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.