NAME
RL - Perl interface to the readline library
SYNOPSIS
use RL;
while (1) {
my $line = RL::readline("prompt: ");
if (!defined $line) {
print "\n";
last;
}
if ($line =~ /^(q|quit|e|exit)$/) {
last;
}
if (length($line)) {
print "$line\n";
RL::add_history($line);
}
}DESCRIPTION
This module provides an interface to the readline library. On Linux, it would be the readline library provided by GNU. On OS X, it is the emulated readline library that is actually the libedit library. This library only provides the subset of functionality that both provide, so some things are missing intentionally. This also includes an interface to the history library functions.
If you're using a Mac, you may notice bash reads .inputrc since bash is statically linked with GNU readline, but this library isnt available for linking into other program.
No subroutines are exported, you must access all within the RL namespace. for example, instead of readline($prompt), you would write RL::readline($prompt).
MAIN INTERFACE
readline($prompt)
Prompts the user for input and returns the string they gave you.
READLINE VARIABLES
line_buffer([$string])
Returns the value of the current line buffer. Optionally sets it to $string, if provided.
point([$int])
Returns the position of the cursor in the input line. Optionally sets it to $int.
end([$int])
Returns the position at the end of the input line. Optionally sets it to $int.
prompt
Returns the string that is shown before the place where the user types.
already_prompted([$int])
Returns whether the user was already prompted. Optionally, you can set it to $int.
library_version
Returns what the library version is. e.g. "EditLine wrapper".
readline_version
Returns what version of readline it is in integer form. e.g. 1026.
terminal_name([$string])
Gets or sets the terminal name which is used to figure out which terminfo entry to use.
readline_name([$string])
Gets or sets the readline name which is used to supply conditional parameters in the .inputrc (or .editrc) config file that influence your program individually.
instream([$fh])
Gets or sets the instream, rl_instream, for readline to use some way.
outstream([$fh])
Gets or sets the outstream, rl_outstream, for readline to use some way.
startup_hook($func)
Sets the startup hook, rl_startup_hook, that gets called when readline initializes itself. Set it to undef to remove the hook. For example:
RL::startup_hook(sub {print "Hello, world\n"});pre_input_hook($func)
Sets the pre input hook, rl_pre_input_hook, that gets called after the prompt but before readline reads input from the user. Set to undef to remove the hook. For example:
RL::pre_input_hook(sub {print "Hello, world\n"});getc_function($func)
Sets the getc function that readline uses to read a character from the user. Set it to undef to get back default behavior. For example:
RL::getc_function(sub {
sleep 1;
return ord("x");
});BINDING KEYS
bind_key($key, $func)
Bind a function to the key.
parse_and_bind($line)
Parses a line as if it were in the .inputrc or .editrc file. For example:
RL::initialize();
RL::parse_and_bind("bind -v\n");Would set vi mode on OS X's readline. Note: you need to call initialize first or else you get a segfault.
read_init_file($filename)
Read keybindings and variable assignments from filename.
REDISPLAY
redisplay
Redisplays the contents of readline's line buffer.
forced_update_display
Force the line to be updated and redisplayed, whether or not Readline thinks the screen display is correct.
on_new_line
Tell the update functions that we have moved onto a new (empty) line, usually after outputting a newline.
set_prompt(prompt)
Make Readline use prompt for subsequent redisplay.
MODIFYING TEXT
insert_text(text)
Insert text into the line at the current cursor position. Returns the number of characters inserted.
CHARACTER INPUT
read_key
Return the next character available from Readline's current input stream.
stuff_char($char)
Insert c into the Readline input stream.
UTILITY FUNCTIONS
initialize
Initialize or re-initialize Readline's internal state. It's not strictly necessary to call this; readline() calls it before reading any input.
COMPLETION FUNCTIONS
complete($count, $key)
Complete the word at or before point.
completion_matches($text, $func)
Returns a list of strings which could complete text using the completion entry function $func.
filename_completion_function($text, $state)
A function that completes filenames. Use it to provide completion_matches() or completion_entry_function() a function that completes filenames. For example:
my @array = RL::completion_matches(
"Re", \&RL::filename_completion_function);
print "$_\n" for @array;or:
RL::completion_entry_function(
\&RL::filename_completion_function);username_completion_function($text, $func)
A subroutine that completes usernames to be used with other subroutines that expects a subroutine like this one.
COMPLETION VARIABLES
completion_entry_function($func)
Sets the subroutine for completion entries. If set to undef, it will revert to filename completion. The subroutine is supplied with the text of the word under the cursor and a state counter, which will start at 0 and increment until you return undef. For example:
my @list = ("Apple", "Pear", "Banana", "Orange");
my $index = 0;
RL::completion_entry_function(sub {
my ($text, $state) = @_;
if ($state == 0) {
$index = 0;
}
my $item;
for (; $index < @list; $index++) {
$item = $list[$index];
if ($item =~ /$text/i) {
$index++;
return $item;
}
}
return undef;
});
RL::readline("prompt: ");attempted_completion_function($func)
Calling this lets you specify a different format of completion function to the completion_entry_function(). This callback is executed when the user presses tab, and receives $text, a $start position, and an $end position, and you return a list of completionsas as an array. The first element is the part to complete right away.
So if you typed "a" and the completions were "abc1", "abc2", and "abc3", the list returned would be "abc", "abc1", "abc2", and "abc3". Hitting tab would complete up to "abc" and then let you see the other possible completions. A helper function called completion_helper() is provided to help go from a list of possible completions to the format required by this function. For example:
RL::attempted_completion_function(sub {
my ($text, $start, $end) = @_;
my @array = ("Cat", "Dog", "Fish", "Bread", "Fax", "Fox",
"Chipmunk", "Chimpanzee", "Cheetah", "Mouse",
"Three Toed Sloth");
return RL::completion_helper($text, \@array);
});
RL::readline("prompt: ");completion_helper($text, $array)
This subroutine takes text and a list of possible completions and returns a list of completions which could possibly match the text. It returns the result in the format required by attempted_completion_function().
basic_word_break_characters([$string])
This is the list of characters that readline will consider a word break. readline can only replace what it considers to be one word. The default is " \t\n\"\\'`@$><=;|&{("
completer_word_break_characters([$string])
Like basic_word_break_characters() but for another part of readline.
completion_word_break_hook($func)
Set this to a subroutine that returns the word break character string and readline will use it somehow.
completer_quote_characters([$string])
A list of characters which can be used to quote a substring of the line.
special_prefixes([$string])
The list of characters that are word break characters, but should be left in text when it is passed to the completion function. Programs can use this to help determine what kind of completing to do. For instance, Bash sets this variable to "$@" so that it can complete shell variables and hostnames.
completion_query_items([$int])
Up to this many items will be displayed in response to a possible-completions call. After that, readline asks the user if she is sure she wants to see them all. The default value is 100. A negative value indicates that Readline should never ask the user.
completion_append_character([$int])
When a single completion alternative matches at the end of the command line, this character is appended to the inserted completion text. The default is a space character (` '). Setting this to the null character (`\0') prevents anything being appended automatically. This can be changed in application-specific completion functions to provide the "most sensible word separator character" according to an application-specific command line syntax specification.
ignore_completion_duplicates([$int])
If non-zero, then duplicates in the matches are removed. The default is 1.
filename_completion_desired([$int])
When done with completion add a slash to directories.
attempted_completion_over([$int])
Specify that completion is over, don't try and complete filenames.
completion_type([$int])
An integer (actually a character) specifying the completion type.
inhibit_completion([$int])
Disable completion.
HISTORY INITIALIZATION
using_history
Initializes internal variables for the history library.
HISTORY LIST MANAGEMENT
add_history($string)
Adds the string into readline history. You can recall the string using up and down arrow keys.
clear_history
Clears the history list.
INFORMATION ABOUT THE HISTORY LIST
history_list
Returns a list of all the items in history.
where_history
Where in the history list we currently are.
current_history
The current entry in history.
history_get($int)
Get's the history entry at position $int.
history_total_bytes
The sum of the bytes of all the strings in history.
MOVING AROUND THE HISTORY LIST
history_set_pos($int)
Sets the history position to the given parameter.
MANAGING THE HISTORY FILE
read_history($filename)
Add the contents of filename to the history list, a line at a time. Returns 0 if successful, or errno if not.
write_history($filename)
Writes history to filename. Returns 0 if successful, errno if not.
history_truncate_file($filename, $nlines)
Truncates the history file, to just nlines number of lines.
HISTORY EXPANSION
history_expand($string)
Returns the string with history expanded. For example, !! becomes the previously input string.
HISTORY VARIABLES
history_base
The logical offset of the first entry in the history list.
history_length
The number of entries currently stored in the history list.
SEE ALSO
The readline docs:
- https://cnswww.cns.cwru.edu/php/chet/readline/readline.html
- https://cnswww.cns.cwru.edu/php/chet/readline/history.html
- https://cnswww.cns.cwru.edu/php/chet/readline/rluserman.html
Editline init file format:
METACPAN
REPOSITORY
https://github.com/zorgnax/perlreadline
AUTHOR
Jacob Gelbman, <gelbman@gmail.com>
COPYRIGHT AND LICENSE
Copyright (C) 2017 by Jacob Gelbman
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.18.2 or, at your option, any later version of Perl 5 you may have available.