Term::ReadLine::Gnu#

📦 max

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#

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#

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#

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#

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

my ($code, $expanded) = $term->history_expand($input);

**$code: 0 no change, 1 expanded, -1 error, 2 print-only**

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#

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#

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.

On this page
Source (accessible & AI-friendly)