Term::ReadLine::readline
Wraps what was initially Perl4 and now partially Perl4) into a fake Perl5 pseudo-module.
The mismatch of the package name, readline and file name Term::ReadLine::readline was intentional to make is harder to abuse this (very fragile) code...
readline
InitKeymap(*keymap, 'default', 'name', bindings...)
actually_do_binding($function1, \@sequence1, ...)
Actually inserts the binding for @sequence to $function into the current map. @sequence is an array of character ordinals.
@sequence
$function
If sequence is more than one element long, all but the last will cause meta maps to be created.
sequence
$Function will have an implicit F_ prepended to it.
$Function
F_
Accepts an array as pairs ($keyspec, $function, [$keyspec, $function]...). and maps the associated bindings to the current KeyMap.
$keyspec should be the name of key sequence in one of two forms:
$keyspec
Old (GNU readline documented) form: M-x to indicate Meta-x C-x to indicate Ctrl-x M-C-x to indicate Meta-Ctrl-x x simple char x
where 'x' above can be a single character, or the special:
special means -------- ----- space space ( ) spc space ( ) tab tab (\t) del delete (0x7f) rubout delete (0x7f) newline newline (\n) lfd newline (\n) ret return (\r) return return (\r) escape escape (\e) esc escape (\e)
New form: "chars" (note the required double-quotes)
where each char in the list represents a character in the sequence, except for the special sequences:
\\C-x Ctrl-x \\M-x Meta-x \\M-C-x Meta-Ctrl-x \\e escape. \\x x (if not one of the above)
$function should be in the form BeginningOfLine or beginning-of-line.
BeginningOfLine
beginning-of-line
It is an error for the function to not be known....
As an example, the following lines in .inputrc will bind one's xterm arrow keys:
"\e[[A": previous-history "\e[[B": next-history "\e[[C": forward-char "\e[[D": backward-char
A version readline for a dumb terminal, that is one that doesn't have many terminal editing capabilities.
&readline'readline($prompt, $default)
The main routine to call interactively read lines.
$default can be omitted. The next input line is returned or undef on EOF.
$default
undef
ctrl($ord)
Returns the ordinal number for the corresponding control code.
For example ctrl(ord('a')) returns the ordinal for Ctrl-A or 1. ctrl(ord('A')) does the same thing.
substr_with_props($prompt, $string, $from, $len, $ket, $bsel, $esel)
Gives the substr() of $prompt.$string with embedded face-change commands.
$prompt.$string
redisplay()
Updates the screen to reflect the current value if $line.
$line
For the purposes of this routine, we prepend the prompt to a local copy of $line so that we display the prompt as well. We then modify it to reflect that some characters have different sizes. That is, control-C is represented as ^C, tabs are expanded, etc.
^C
This routine is somewhat complicated by two-byte characters.... must make sure never to try do display just half of one.
Note: If an argument is given, it is used instead of the prompt.
This is some nasty code.
get_command(*keymap, $ord_command_char)
If the *keymap) has an entry for $ord_command_char, it is returned. Otherwise, the default command in $Keymap{'default'} is returned if that exists. If $Keymap{'default'} is false, 'F_Ding' is returned.
*keymap
$ord_command_char
$Keymap{'default'}
'F_Ding'
do_command(*keymap, $numericarg, $key)
If the *keymap has an entry for $key, it is executed. Otherwise, the default command for the keymap is executed.
$key
savestate()
Save whatever state we wish to save as an anonymous array. The only other function that needs to know about its encoding is getstate/preserve_state.
preserve_tate()
F_SelfInsert($count, $ord)
$ord is an ASCII ordinal; inserts $count of them into $line.
$ord
$count
Return the line as-is to the user.
Insert into history list if:
bigger than the minimal length
not same as last entry
rl_set($var_name, $value_string)
Sets the named variable as per the given value, if both are appropriate. Allows the user of the package to set such things as HorizontalScrollMode and EditingMode. Value_string may be of the form
HorizontalScrollMode horizontal-scroll-mode
Also called during the parsing of ~/.inputrc for "set var value" lines.
The previous value is returned, or undef on error.
Consider the following example for how to add additional variables accessible via rl_set (and hence via ~/.inputrc).
Want:
We want an external variable called "FooTime" (or "foo-time"). It may have values "January", "Monday", or "Noon". Internally, we'll want those values to translate to 1, 2, and 12.
How:
Have an internal variable $var_FooTime that will represent the current internal value, and initialize it to the default value. Make an array %var_FooTime whose keys and values are are the external (January, Monday, Noon) and internal (1, 2, 12) values:
$var_FooTime = $var_FooTime{'January'} = 1; #default $var_FooTime{'Monday'} = 2; $var_FooTime{'Noon'} = 12;
OnSecondByte($index)
Returns true if the byte at $index into $line is the second byte of a two-byte character.
$index
CharSize($index)
Returns the size of the character at the given $index in the current line. Most characters are just one byte in length, but if the byte at the index and the one after has the high bit set those two bytes are one character of size=2.
Assumes that $index points to the first of a 2-byte char if not pointing to a 2-byte char.
A pretty full-function package similar to GNU's readline. Includes support for EUC-encoded Japanese text.
Written by Jeffrey Friedl, Omron Corporation (jfriedl@omron.co.jp)
Comments, corrections welcome.
Thanks to the people at FSF for readline (and the code I referenced while writing this), and for Roland Schemers whose line_edit.pl I used as an early basis for this.
(see the manual for complete info)
Once this package is included (require'd), you can then call:
$text = &readline'readline($input);
to get lines of input from the user.
Normally, it reads ~/.inputrc when loaded. To suppress this, set
$readline'rl_NoInitFromFile = 1;
before requiring the package.
Call rl_bind() to add your own key bindings, as in:
&readline'rl_bind('C-L', 'possible-completions');
Call rl_set to set mode variables yourself, as in:
&readline'rl_set('TcshCompleteMode', 'On');
To change the input mode (emacs or vi) use ~/.inputrc or call
&readline::rl_set('EditingMode', 'vi'); or: &readline::rl_set('EditingMode', 'emacs');
Call rl_basic_commands to set your own command completion, as in:
&readline'rl_basic_commands('print', 'list', 'quit', 'run', 'status');
hey, 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 &readline'rl_set('tcsh-complete-mode', 'On') to turn on.
Can you say HUGE?
I can't spell, so comments riddled with misspellings.
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.
Obviously not well tested yet.
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.
rl_
Some notable internal-only variables of global proportions:
$prompt
$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 set'able variables work.
$var_EditingMode
$var_TcshCompleteMode
Other $var_ things not supported yet.
$var_
Some variables used internally, but may be accessed from outside...
$VERSION
../Makefile.PL
$rl_readline_name
$0
$rl_NoInitFromFile
@rl_History
$rl_HistoryIndex
$rl_completion_function
$rl_basic_word_break_characters
$rl_start_default_at_beginning
$rl_completer_word_break_characters
$rl_completer_terminator_character
' '
$rl_special_prefixes
$
&
@'
%
$text
&@$%
$rl_MaxHistorySize
$rl_screen_width
$rl_correct_sw
$rl_margin
$rl_CLEAR
$rl_max_numeric_arg
$rl_vi_replace_default_on_insert
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
$line_rl_mark
$_rl_japanese_mb
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 _<readline::rl_filename_list()_.
A minimal-trouble way to have command-completion is to call _readline::rl_basic_commands()_ with an array of command names, such as readline::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.
readline::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 $readline::rl_completion_function to the name of the function to run.
$readline::rl_completion_function
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:
$readline'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.
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.