Term::ReadLine::Perl5::readline, described here, is non-OO package similar to GNU's readline. The preferred OO Package is Term::ReadLine::Perl5. But that uses this internally. Also see the newer but unfinished Term::ReadLine::Perl5::OO.
Some support is available for EUC-encoded Japanese text. But this should be rewritten for Perl Unicode.
use Term::ReadLine::Perl5::readline; $text = &Term::ReadLine::Perl5::readline::readline('waddyawant? ');
to get a line of input from the user.
Normally, it reads ~/.inputrc when loaded. To suppress this, set
$rl_NoInitFromFile = 1;
before requiring the package.
Call rl_bind() to add your own key bindings, as in:
&rl_bind('C-L', 'possible-completions');
Call rl_set to set mode variables yourself, as in:
&rl_set('TcshCompleteMode', 'On');
To change the input mode (emacs or vi) use ~/.inputrc or call
&rl_set('EditingMode', 'vi'); or: &rl_set('EditingMode', 'emacs');
Call rl_basic_commands to set your own command completion, as in:
&rl_basic_commands('print', 'list', 'quit', 'run', 'status');
It's in Perl.
Pretty full GNU readline-like library...
support for ~/.inputrc
horizontal scrolling
command/file completion
rebinding
history (with search)
undo
numeric prefixes
supports multi-byte characters (at least for the Japanese I use).
Has a tcsh-like completion-function mode.call &rl_set('tcsh-complete-mode', 'On') to turn on.
It is huge
Uses lots of global state
Written by someone that has never really used readline.
History mechanism is slightly different than GNU... may get fixed someday, but I like it as it is now...
Killbuffer not a ring.. just one level.
Not well tested.
Written by someone that doesn't have a bell on his terminal, so
proper readline use of the bell may not be here.
Functions beginning with F_ are functions that are mapped to keys. Variables and functions beginning rl_ may be accessed/set/called/read from outside the package. Other things are internal.
F_
rl_
Some notable internal-only variables of global proportions:
$prompt
$line
$D
$InsertMode
$InputLocMsg
%emacs_keymap
@emacs_keymap
$emacs_keymap{'name'}
$emacs_keymap{'default'}
%vi_keymap
%vicmd_keymap
%vipos_keymap
%visearch_keymap
%KeyMap
$LastCommandKilledText
$lastcommand
$lastredisplay
$force_redraw
$AcceptLine
$ReturnEOF
@Pending
@undo
$KillBuffer
@tcsh_complete_selections
Some internal variables modified by &rl_set(). See comment at &rl_set for info about how these setable variables work.
$var_EditingMode
a keymap typeglob like %emacs_keymap or %vi_keymap
$var_TcshCompleteMode
If true, the completion function works like in tcsh. That is, the first time you try to complete something, the common prefix is completed for you. Subsequent completion tries thout other commands in between) cycles the command line through the various possibilities. If/when you get the one you want, just continue typing.
Other $var_ things not supported yet.
$var_
Some variables used internally, but may be accessed from outside...
$VERSION
Version of this package. It is used up by ../Makefile.PL
../Makefile.PL
$rl_readline_name
Name of program, possibly $0. Used in .initrc if/endif stuff.
$0
$rl_NoInitFromFile
@rl_History
$rl_HistoryIndex
history pointer (for moving about history array)
$rl_completion_function
See "How Command Completion Works".
$rl_basic_word_break_characters
string of characters that can cause a word break for forward-word, etc.
$rl_start_default_at_beginning
Normally, the user's cursor starts at the end of any default text passed to readline. If this variable is true, it starts at the beginning.
$rl_completer_word_break_characters
like $rl_basic_word_break_characters (and in fact defaults to it), but for the completion function.
$rl_completer_terminator_character
what to insert to separate a completed token from the rest. Reset at beginning of completion to ' ' so completion function can change it.
' '
$rl_special_prefixes
characters that are part of this string as well as of $rl_completer_word_break_characters cause a word break for the completer function, but remain part of the word. An example: consider when the input might be perl code, and one wants to be able to complete on variable and function names, yet still have the sigil ($, &, @', %) part of the $text to be completed. Then set this var to &@$% and make sure each of these characters is in $rl_completer_word_break_characters as well.
$
&
@'
%
$text
&@$%
$rl_MaxHistorySize
maximum size that the history array may grow.
$rl_screen_width
width readline thinks it can use on the screen.
$rl_correct_sw
is substructed from the real width of the terminal
$rl_margin
scroll by moving to within this far from a margin.
$rl_CLEAR
what to output to clear the screen.
$rl_max_numeric_arg
maximum numeric arg allowed.
$rl_vi_replace_default_on_insert
Normally, the text you enter is added to any default text passed to readline. If this variable is true, default text will start out highlighted (if supported by your terminal) and text entered while the default is highlighted (during the _first_ insert mode only) will replace the entire default line. Once you have left insert mode (hit escape), everything works as normal.
This behavior similar to many GUI controls' behavior, which select the default text so that new text replaces the old.
Use with $rl_start_default_at_beginning for normal-looking behavior (though it works just fine without it).
Notes/Bugs:
Control characters (like C-w) do not actually terminate this replace mode, for the same reason it does not work in emacs mode.
Spine-crawlingly scary subroutine redefinitions
$rl_mark
start of the region
$line_rl_mark
the line on which $rl_mark is active
$_rl_japanese_mb
For character movement suppose Japanese (which?!) multi-byte encoding. (How to make a sane default?)
When asked to do a completion operation, readline isolates the word to the immediate left of the cursor (i.e. what's just been typed). This information is then passed to some function (which may be supplied by the user of this package) which will return an array of possible completions.
If there is just one, that one is used. Otherwise, they are listed in some way depending upon $var_TcshCompleteMode.
The default is to do filename completion. The function that performs this task is rl_filename_list().
A minimal-trouble way to have command-completion is to call rl_basic_commands() with an array of command names, such as rl_basic_commands('quit', 'run', 'set', 'list'). Those command names will then be used for completion if the word being completed begins the line. Otherwise, completion is disallowed.
rl_basic_commands('quit', 'run', 'set', 'list')
The way to have the most power is to provide a function to readline which will accept information about a partial word that needs completed, and will return the appropriate list of possibilities. This is done by setting $rl_completion_function to the name of the function to run.
That function will be called with three args ($text, $line, $start). $text is the partial word that should be completed. $line is the entire input line as it stands, and $start is the index of the $text in C$<line>. That is, zero if $text is at the beginning of $line.
($text, $line, $start)
$start
A cool completion function will look at $line and $start and give context- sensitive completion lists. Consider something that will do completion for two commands:
cat FILENAME finger USERNAME status [this|that|other]
It (untested) might look like:
$rl_completion_function = "main::complete"; sub complete { local($text, $_, $start) = @_; ## return commands which may match if at the beginning.... return grep(/^$text/, 'cat', 'finger') if $start == 0; return &rl_filename_list($text) if /^cat\b/; return &my_namelist($text) if /^finger\b/; return grep(/^text/, 'this', 'that','other') if /^status\b/; (); }
A real completion function would be more robust.
Originally written by Jeffrey Friedl, Omron Corporation (jfriedl@omron.co.jp)
Comments, corrections welcome. Someone please volunteer to rewrite this!
Thanks to the people at FSF for readline (and the code referenced while writing this), and for Roland Schemers whose line_edit.pl Jefrey used as an early basis for this.
Term::ReadLine::Perl5::readline documents more of the nitty gritty details as this is embedded along with the code
Term::ReadLine::Perl5 is the OO package most programmers should use.
Term::ReadLine::Perl5::OO is the newer but unfinished fully OO version.
To install Term::ReadLine::Perl5, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Term::ReadLine::Perl5
CPAN shell
perl -MCPAN -e shell install Term::ReadLine::Perl5
For more information on module installation, please visit the detailed CPAN module installation guide.