/ 
Term-ReadLine-Perl5-1.45
River stage zero No dependents
/ Term::ReadLine::Perl5::readline-guide

Term::ReadLine::Perl5::readline-guide

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.

Synopsis

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');

What's Cool

  • 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.

What's not Cool

  • 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 and variables

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.

Some notable internal-only variables of global proportions:

$prompt line prompt (passed from user)
$line the line being input
$D `Dot'' index into $line of the cursor's location.
$InsertMode usually true. False means overwrite mode.
$InputLocMsg string for error messages, such as "[~/.inputrc line 2]"
%emacs_keymap keymap for emacs-mode bindings:
@emacs_keymap bindings indexed by ASCII ordinal
$emacs_keymap{'name'} Is "emacs_keymap"
$emacs_keymap{'default'} is "SelfInsert" (default binding)
%vi_keymap keymap for vi input mode bindings
%vicmd_keymap keymap for vi command mode bindings
%vipos_keymap keymap for vi positioning command bindings
%visearch_keymap keymap for vi search pattern input mode bindings
%KeyMap current keymap in effect.
$LastCommandKilledText needed so that subsequent kills accumulate
$lastcommand name of command previously run
$lastredisplay text placed upon screen during previous &redisplay
C$<si> screen index; index into $line of leftmost char &redisplay'ed
$force_redraw if set to true, causes &redisplay to be verbose.
$AcceptLine when set, its value is returned from &readline.
$ReturnEOF unless this also set, in which case undef is returned.
@Pending characters to be used as input.
@undo array holding all states of current line, for undoing.
$KillBuffer top of kill ring (well, don't have a kill ring yet)
@tcsh_complete_selections For tcsh mode, possible 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.

Some variables used internally, but may be accessed from outside...

$VERSION

Version of this package. It is used up by ../Makefile.PL

$rl_readline_name

Name of program, possibly $0. Used in .initrc if/endif stuff.

$rl_NoInitFromFile If defined when package is require'd, ~/.inputrc will not be read.
@rl_History array of previous lines input.
$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.

$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?)

How Command Completion Works

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.

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.

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.

Author

Originally written by Jeffrey Friedl, Omron Corporation (jfriedl@omron.co.jp)

Comments, corrections welcome. Someone please volunteer to rewrite this!

Thanks

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.

See also