NAME
Term::ReadLine::Perl5::readline
DESCRIPTION
Wraps what is largely Perl4 into a non-OO Perl5 module. It is ugly, but at least its a start. Please use Term::ReadLine::Per5 instead.
SUBROUTINES
get_window_size
get_window_size([$redisplay])Note: this function is deprecated. It is not in Term::ReadLine::GNU or the GNU ReadLine library. As such, it may disappear and be replaced by the corresponding Term::ReadLine::GNU routines.
Causes a query to get the terminal width. If the terminal width can't be obtained, nothing is done. Otherwise...
Set $rl_screen_width and to the current screen width. $rl_margin is then set to be 1/3 of $rl_screen_width.
any window-changeing hooks stored in array @winchhooks are run.
SIG{WINCH} is set to run this routine. Any routines set are lost. A better behavior would be to add existing hooks to @winchhooks, but hey, this routine is deprecated.
If $redisplay is passed and is true, then a redisplay of the input line is done by calling redisplay().
InitKeyMap
InitKeymap(*keymap, 'default', 'name', bindings...)
_unescape
_unescape($string) -> List of keysThis internal function that takes $string possibly containing escape sequences, and converts to a series of octal keys.
It has special rules for dealing with readline-specific escape-sequence commands.
New-style key bindings are enclosed in double-quotes. Characters are taken verbatim except the special cases:
\C-x Control x (for any x)
\M-x Meta x (for any x)
\e Escape
\* Set the keymap default (JP: added this)
(must be the last character of the sequence)
\x x (unless it fits the above pattern)Special case "\C-\M-x", should be treated like "\M-\C-x".
actually_do_binding
actually_do_binding($function1, \@sequence1, ...)
Actually inserts the binding for @sequence to $function into the current map. @sequence is an array of character ordinals.
If sequence is more than one element long, all but the last will cause meta maps to be created.
$Function will have an implicit F_ prepended to it.
rl_bind
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:
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 xwhere 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.
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-charread_an_init_file
read_an_init_file(inputrc_file)
Reads and executes inputrc_file which does things like Sets input key bindings in key maps.
If there was a problem return 0. Otherwise return 1;
readline_dumb
A version readline for a dumb terminal, that is one that doesn't have many terminal editing capabilities.
readline
&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.
ctrl
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
substr_with_props($prompt, $string, $from, $len, $ket, $bsel, $esel)
Gives the substr() of $prompt.$string with embedded face-change commands.
redisplay
redisplay()
Updates the screen to reflect the current value if $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.
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
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.
do_command
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.
savestate
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_state
preserve_tate()
F_SelfInsert
F_SelfInsert($count, $ord)
$ord is an ASCII ordinal; inserts $count of them into $line.
F_AcceptLine
Return the line as-is to the user.
rl_set
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-modeAlso 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
OnSecondByte($index)
Returns true if the byte at $index into $line is the second byte of a two-byte character.
CharSize
CharSize($index)
Returns the size of the character at the given $index in the current line. Most characters are just one byte in length. However, if the byte at the index and the one after both have the high bit set and $_rl_japanese_mb is set, those two bytes are one character of size two.
Assumes that $index points to the first of a 2-byte char if not pointing to a 1-byte char.
TODO: handle Unicode
WordBreak
WordBreak(index)
Returns true if the character at index into $line is a basic word break character, false otherwise.
kill_text
kills from D=$_[0] to $_[1] (to the killbuffer if $_[2] is true)
Bindable functions
There are pretty much in the same order as in readline.c
at_end_of_line
Returns true if $D at the end of the line.
F_ForwardChar
Move forward (right) $count characters.
F_BackwaredChar
Move backward (left) $count characters.
F_BeginningOfLine
Go to beginning of line.
F_EndOfLine
Move to the end of the line.
F_ForwardWord
Move to the end of this/next word. Done as many times as $count says.
F_BackwardWord
Move to the beginning of this/next word. Done as many times as $count says.
F_RedrawCurrentLine
Refresh the input line.
F_ClearScreen
Clear the screen and refresh the line. If given a numeric arg other than 1, simply refreshes the line.
F_QuotedInsert
Insert the next character read verbatim.
F_TabInsert
Insert a tab.
F_OperateAndGetNext
Accept the current line and fetch from the history the next line relative to current line for default.
F_BackwaredDeleteChar
Removes $count chars to left of cursor (if not at beginning of line). If $count > 1, deleted chars saved to kill buffer.
F_DeleteChar
Removes the $count chars from under the cursor. If there is no line and the last command was different, tells readline to return EOF. If there is a line, and the cursor is at the end of it, and we're in tcsh completion mode, then list possible completions. If $count > 1, deleted chars saved to kill buffer.
F_UnixWordRubout
Kill to previous whitespace.
F_UnixLineDiscard
Kill line from cursor to beginning of line.
F_TransposeChars
Switch char at dot with char before it. If at the end of the line, switch the previous two... Note: this could screw up multibyte characters.. should do correctly)
F_KillLine
delete characters from cursor to end of line.
F_BackwardKillLine
Delete characters from cursor to beginning of line.
TextInsert
TextInsert($count, $string)
F_KillWord
Delete characters to the end of the current word. If not on a word, delete to ## the end of the next word.
F_BackwardKillWord
Delete characters backward to the start of the current word, or, if currently not on a word (or just at the start of a word), to the start of the previous word.
F_Abort
Abort the current input.
F_DoLowercaseVersion
If the character that got us here is upper case, do the lower-case equivalent command.
F_DoControlVersion
do the equiv with control key... If the character that got us here is upper case, do the lower-case equivalent command.
F_DoMetaVersion
do the equiv with meta key...
F_DoEscVersion
If the character that got us here is Alt-Char, do the Esc Char equiv...
F_Undo
Undo one level.
F_RevertLine
Replace the current line to some "before" state.
F_Interrupt
(Attempt to) interrupt the current program via kill('INT')
F_DigitArgument
Give a numeric prefix to the subsequent command
(Attempt to) suspend the program via kill('TSTP')
F_Ding
Ring the bell.
Should do something with $var_PreferVisibleBell here, but what?
command/file completion routines
F_PossibleCompletions
List possible completions
F_Complete
Do a completion operation. If the last thing we did was a completion operation, we'll now list the options available (under normal emacs mode).
In TcshCompleteMode, each contiguous subsequent completion operation lists another of the possible options.
Returns true if a completion was done, false otherwise, so vi completion routines can test it.
completion_matches
completion_matches(func, text, line, start)func is a function to call as
func($text, $line, $start)where $text is the item to be completed, $line is the whole command line, and $start is the starting index of $text in $line. The function $func should return a list of items that might match.
completion_matches will return that list, with the longest common prefix prepended as the first item of the list. Therefore, the list will either be of zero length (meaning no matches) or of 2 or more.....
rl_tilde_expand
rl_tilde_expand($prefix) => list of usernamesReturns a list of completions that begin with the given prefix, $prefix. This only works if we have getpwwet() available.
rl_filename_list
rl_filename_list($pattern) => list of filesReturns a list of completions that begin with the string $pattern. Can be used to pass to completion_matches().
This function corresponds to the Term::ReadLine::GNU function rl_filename_list). But that doesn't handle tilde expansion while this does. Also, directories returned will have the '/' suffix appended as is the case returned by GNU Readline, but not Term::ReadLine::GNU. Adding the '/' suffix is useful in completion because it forces the next completion to complete inside that directory.
GNU Readline also will complete partial ~ names; for example ~roo maybe expanded to /root for the root user. When getpwent/setpwent is available we provide that.
The user of this package can set $rl_completion_function to 'rl_filename_list' to restore the default of filename matching if they'd changed it earlier, either directly or via &rl_basic_commands.
rl_filename_list_deprecated
rl_filename_list_deprecated($pattern)
This was the Term::ReadLine::Perl5 function before version 1.30, and the current Term::ReadLine::Perl function.
For reasons that are a mystery to me (rocky), there seemed to be a the need to classify the result adding a suffix for executable (*), pipe/socket (=), and symbolic link (@), and directory (/). Of these, the only useful one is directory since that will cause a further completion to continue.
vi Routines
F_ViRepeatLastCommand
Repeat the most recent one of these vi commands:
a A c C d D i I p P r R s S x X ~F_SaveLine
Prepend line with '#', add to history, and clear the input buffer (this feature was borrowed from ksh).
F_ViNonePosition
Come here if we see a non-positioning keystroke when a positioning keystroke is expected.
ViPositionEsc
Comes here if we see escchar, but not an arrow key or other mapped sequence, when a positioning keystroke is expected.
F_ViFirstWord
Go to first non-space character of line.
Go to the numbered history line, as listed by the 'H' command, i.e. the current $line is line 1, the youngest line in @rl_History is 2, etc.
F_ViSearch
Search history for matching string. As with vi in nomagic mode, the ^, $, \<, and \> positional assertions, the \* quantifier, the \. character class, and the \[ character class delimiter all have special meaning here.
F_ViChangeEntireLine
Kill entire line and enter input mode
F_ViChangeChar
Kill characters and enter input mode
F_ViChangeLine
Delete characteres from cursor to end of line and enter VI input mode.