RL - Perl interface to the readline library
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); } }
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 programs. I've also noticed libedit doesn't handle ansi escape codes in the prompt well, even though it mentions \1 and \2 in its header file (the codes are used around ansi escape codes in readline to specify they are 0 width).
No subroutines are exported, you must access all within the RL namespace. for example, instead of readline($prompt), you would write RL::readline($prompt).
readline($prompt)
RL::readline($prompt)
This package also comes with a script called pl, which is a repl for the Perl language, to quickly test commands, or do mathematical calculations, etc.
Recommendation: Add the following to your .editrc file to get previous and next history entries that match your partially typed command (only for OS X's readline):
bind ^[[A ed-search-prev-history bind ^[[B ed-search-next-history
For Linux, you would put this into your .inputrc:
"\e[A": history-search-backward "\e[B": history-search-forward
Prompts the user for input and returns the string they gave you.
These variables in the readline library are exported to Perl space as getter/setter functions. Readonly variables do not take arguments.
Returns the value of the current line buffer. Optionally sets it to $string, if provided.
Returns the position of the cursor in the input line. Optionally sets it to $int.
Returns the position at the end of the input line. Optionally sets it to $int.
Returns the string that is shown before the place where the user types.
Returns whether the user was already prompted. Optionally, you can set it to $int.
Returns what the library version is. e.g. "EditLine wrapper".
Returns what version of readline it is in integer form. e.g. 1026.
Gets or sets the terminal name which is used to figure out which terminfo entry to use.
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.
Gets or sets the instream, rl_instream, for readline to use some way.
Gets or sets the outstream, rl_outstream, for readline to use some way.
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"});
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"});
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"); });
Bind a function to the key.
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 keybindings and variable assignments from filename.
Redisplays the contents of readline's line buffer.
Force the line to be updated and redisplayed, whether or not Readline thinks the screen display is correct.
Tell the update functions that we have moved onto a new (empty) line, usually after outputting a newline.
Make Readline use prompt for subsequent redisplay.
Insert text into the line at the current cursor position. Returns the number of characters inserted.
Return the next character available from Readline's current input stream.
Insert c into the Readline input stream.
Initialize or re-initialize Readline's internal state. It's not strictly necessary to call this; readline() calls it before reading any input.
Complete the word at or before point.
Returns a list of strings which could complete text using the completion entry function $func.
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);
A subroutine that completes usernames to be used with other subroutines that expects a subroutine like this one.
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: ");
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 completions as 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: ");
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().
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\"\\'`@$><=;|&{("
Like basic_word_break_characters() but for another part of readline.
Set this to a subroutine that returns the word break character string and readline will use it somehow.
A list of characters which can be used to quote a substring of the line.
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.
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.
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.
If non-zero, then duplicates in the matches are removed. The default is 1.
When done with completion add a slash to directories.
Specify that completion is over, don't try and complete filenames.
An integer (actually a character) specifying the completion type.
Disable completion.
Initializes internal variables for the history library.
Adds the string into readline history. You can recall the string using up and down arrow keys.
Clears the history list.
Returns a list of all the items in history.
Where in the history list we currently are.
The current entry in history.
Get's the history entry at position $int.
The sum of the bytes of all the strings in history.
Sets the history position to the given parameter.
Add the contents of filename to the history list, a line at a time. Returns 0 if successful, or errno if not.
Writes history to filename. Returns 0 if successful, errno if not.
Truncates the history file, to just nlines number of lines.
Returns the string with history expanded. For example, !! becomes the previously input string.
The logical offset of the first entry in the history list.
The number of entries currently stored in the history list.
The readline docs:
Editline init file format:
https://metacpan.org/pod/RL
https://github.com/zorgnax/perlreadline
Jacob Gelbman, <gelbman@gmail.com>
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.
To install RL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm RL
CPAN shell
perl -MCPAN -e shell install RL
For more information on module installation, please visit the detailed CPAN module installation guide.