++ed by:
SHARYANTO PERLANCAR

2 PAUSE user(s)
1 non-PAUSE user(s).

Rocky Bernstein

NAME

Term::ReadLine::Perl5::readline

DESCRIPTION

A non-OO package similar to GNU's readline. The preferred OO Package is Term::ReadLine::Perl5. But that uses this internally.

It could be made better by removing more of the global state and moving it into the Term::ReadLine::Perl5 side.

There is some support for EUC-encoded Japanese text. This should be rewritten for Perl Unicode though.

Someone please volunteer to rewrite this!

See also Term::ReadLine::Perl5::readline-guide.

SUBROUTINES

InitKeyMap

InitKeymap(*keymap, 'default', 'name', bindings...)

_unescape

    _unescape($string) -> List of keys

This 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".

bind_parsed_keyseq

bind_parsed_keyseq($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.

0 is returned if there is no error.

GNU ReadLine-ish Routines

Many of these aren't the the name GNU readline uses, nor do they correspond to GNU ReadLine functions. Sigh.

rl_bind_keyseq

rl_bind_keyseq($keyspec, $function)

Bind the key sequence represented by the string keyseq to the function function, beginning in the current keymap. This makes new keymaps as necessary. The return value is non-zero if keyseq is invalid. $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 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.

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

rl_bind

Accepts an array as pairs ($keyspec, $function, [$keyspec, $function]...). and maps the associated bindings to the current KeyMap.

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

rl_filename_list

  rl_filename_list($pattern) => list of files

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

rl_parse_and_bind

rl_parse_and_bind($line)

Parse $line as if it had been read from the inputrc file and perform any key bindings and variable assignments found.

rl_basic_commands

Called with a list of possible commands, will allow command completion on those commands, but only for the first word on a line. For example:

    &rl_basic_commands('set', 'quit', 'type', 'run');

This is for people that want quick and simple command completion. A more thoughtful implementation would set $rl_completion_function to a routine that would look at the context of the word being completed and return the appropriate possibilities.

rl_read_init_file

rl_read_initfile($filename) Read keybindings and variable assignments from filename $filename.

BINDABLE FUNCTIONS

There are pretty much in the same order as in readline.c

Commands For Moving

F_BeginningOfLine

Move to the start of the current line.

F_EndOfLine

Move to the end of the line.

F_ForwardChar

Move forward (right) $count characters.

F_BackwardChar

Move backward (left) $count characters.

F_ForwardWord

Move forward to the end of the next word. Words are composed of letters and digits.

Done as many times as $count says.

F_BackwardWord

Move back to the start of the current or previous word. Words are composed of letters and digits.

Done as many times as $count says.

F_ClearScreen

Clear the screen and redraw the current line, leaving the current line at the top of the screen.

If given a numeric arg other than 1, simply refreshes the line.

F_RedrawCurrentLine

Refresh the current line. By default, this is unbound.

Commands tor Manipulating the History

F_AcceptLine

Accept the line regardless of where the cursor is. If this line is non-empty, it may be added to the history list for future recall with add_history(). If this line is a modified history line, the history line is restored to its original state.

F_PreviousHistory

Move `back' through the history list, fetching the previous command.

F_PreviousHistory

Move `forward' through the history list, fetching the next command.

F_BeginningOfHistory

Move to the first line in the history.

F_EndOfHistory

Move to the end of the input history, i.e., the line currently being entered.

F_ReverseSearchHistory

Search backward starting at the current line and moving `up' through the history as necessary. This is an incremental search.

Search forward starting at the current line and moving `down' through the the history as necessary. This is an increment

F_HistorySearchBackward

Search backward through the history for the string of characters between the start of the current line and the point. The search string must match at the beginning of a history line. This is a non-incremental search. By default, this command is unbound.

F_HistorySearchForward

Search forward through the history for the string of characters between the start of the current line and the point. The search string may match anywhere in a history line. This is a non-incremental search. By default, this command is unbound.

Commands For Changing Text

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_BackwardDeleteChar

Removes $count chars to left of cursor (if not at beginning of line). If $count > 1, deleted chars saved to kill buffer.

F_QuotedInsert

Add the next character typed to the line verbatim. This is how to insert key sequences like C-q, for example.

F_TabInsert

Insert a tab character.

F_SelfInsert

F_SelfInsert($count, $ord)

$ord is an ASCII ordinal; inserts $count of them into global $line.

Insert yourself.

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_TransposeWords

Drag the word before point past the word after point, moving point past that word as well. If the insertion point is at the end of the line, this transposes the last two words on the line.

F_UpcaseWord

Uppercase the current (or following) word. With a negative argument, uppercase the previous word, but do not move the cursor.

F_DownCaseWord

Lowercase the current (or following) word. With a negative argument, lowercase the previous word, but do not move the cursor.

F_CapitalizeWord

Capitalize the current (or following) word. With a negative argument, capitalize the previous word, but do not move the cursor.

F_OverwriteMode

Toggle overwrite mode. With an explicit positive numeric argument, switches to overwrite mode. With an explicit non-positive numeric argument, switches to insert mode. This command affects only emacs mode; vi mode does overwrite differently. Each call to readline() starts in insert mode. In overwrite mode, characters bound to self-insert replace the text at point rather than pushing the text to the right. Characters bound to backward-delete-char replace the character before point with a space.

By default, this command is unbound.

Killing and Yanking

F_KillLine

delete characters from cursor to end of line.

F_BackwardKillLine

Delete characters from cursor to beginning of line.

F_UnixLineDiscard

Kill line from cursor to beginning of line.

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_UnixWordRubout

Kill to previous whitespace.

F_KillRegion

Kill the text in the current region. By default, this command is unbound.

F_CopyRegionAsKill

Copy the text in the region to the kill buffer, so it can be yanked right away. By default, this command is unbound.

F_Yank

Yank the top of the kill ring into the buffer at point.

Specifying Numeric Arguments

F_DigitArgument

Add this digit to the argument already accumulating, or start a new argument. M-- starts a negative argument.

F_UniversalArgument

This is another way to specify an argument. If this command is followed by one or more digits, optionally with a leading minus sign, those digits define the argument. If the command is followed by digits, executing universal-argument again ends the numeric argument, but is otherwise ignored. As a special case, if this command is immediately followed by a character that is neither a digit or minus sign, the argument count for the next command is multiplied by four. The argument count is initially one, so executing this function the first time makes the argument count four, a second time makes the argument count sixteen, and so on. By default, this is not bound to a key.

Letting Readline Type For You

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.

F_PossibleCompletions

List possible completions

F_PossibleCompletions

Insert all completions of the text before point that would have been generated by possible-completions.

Miscellaneous Commands

F_ReReadInitFile

Read in the contents of the inputrc file, and incorporate any bindings or variable assignments found there.

F_Abort

Abort the current editing command and ring the terminal's bell (subject to the setting of bell-style).

F_Undo

Incremental undo, separately remembered for each line.

F_RevertLine

Undo all changes made to this line. This is like executing the undo command enough times to get back to the beginning.

F_TildeExpand

Perform tilde expansion on the current word.

F_SetMark

Set the mark to the point. If a numeric argument is supplied, the mark is set to that position.

F_ExchangePointAndMark

Set the mark to the point. If a numeric argument is supplied, the mark is set to that position.

F_OperateAndGetNext

Accept the current line and fetch from the history the next line relative to current line for default.

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_Interrupt

(Attempt to) interrupt the current program via kill('INT')

(Attempt to) suspend the program via kill('TSTP')

F_Ding

Ring the bell.

Should do something with $var_PreferVisibleBel here, but what?

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.

F_ViTtoggleCase

# Like the emacs case transforms.

Note: this doesn't work for multi-byte characters.

F_ViHistoryLine

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.

Internal Routines

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().

readline

    &readline::readline($prompt, $default)>

The main routine to call interactively read lines. Parameter $prompt is the text you want to prompt with If it is empty string, no preceding prompt text is given. It is undef a default value of "INPUT> " is used.

Parameter $default is the default value; it can be can be omitted. The next input line is returned or undef on EOF.

substr_with_props

substr_with_props($prompt, $string, $from, $len, $ket, $bsel, $esel)

Gives the substr() of $prompt.$string with embedded face-change commands.

rl_redisplay

rl_redisplay()

Updates the screen to reflect the current value of global $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.

This is some nasty code.

redisplay

redisplay[($prompt)]

If an argument $prompt is given, it is used instead of the prompt. Updates the screen to reflect the current value of global $line via rl_redisplay.

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()

OnSecondByte

OnSecondByte($index)

Returns true if the byte at $index into $line is the second byte of a two-byte character.

CharSize

BCharSize($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)

at_end_of_line

Returns true if $D at the end of the line.

changecase

     changecase($count, $up_down_caps)

Translated from GNU's readline.c.

If $up_down_caps is 'up' to upcase $count words; 'down' to downcase them, or something else to capitalize them.

If $count is negative, the dot is not moved.

    search($position, $string)

Checks if $string is at position $rl_History[$position] and returns $position if found or -1 if not found.

This is intended to be the called first in a potentially repetitive search, which is why the unusual return value. See also searchStart.

search

    searchStart($position, $reverse, $string)

$reverse should be either +1, or -1;

Checks if $string is at position $rl_History[$position+$reverse] and returns $position if found or -1 if not found.

This is intended to be the called first in a potentially repetitive search, which is why the unusual return value. See also search.

TextInsert

TextInsert($count, $string)

complete_internal

The meat of command completion. Patterned closely after GNU's.

The supposedly partial word at the cursor is "completed" as per the single argument: "\t" complete as much of the word as is unambiguous "?" list possibilities. "*" replace word with all possibilities. (who would use this?)

A few notable variables used: $rl_completer_word_break_characters -- characters in this string break a word. $rl_special_prefixes -- but if in this string as well, remain part of that word.

Returns true if a completion was done, false otherwise, so vi completion routines can test it.

use_basic_commands

  use_basic_commands($text, $line, $start);

Used as a completion function by &rl_basic_commands. Return items from @rl_basic_commands that start with the pattern in $text.

$start should be 0, signifying matching from the beginning of the line, for this to work. Otherwise we return the empty list. $line is ignored, but needs to be there in to match the completion-function API.

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

pretty_print_list

Print an array in columns like ls -C. Originally based on stuff (lsC2.pl) by utashiro@sran230.sra.co.jp (Kazumasa Utashiro).

See Array::Columnize for a more flexible and more general routine.

get_position

    get_position($count, $ord, $fulline_ord, $poshash)

Interpret vi positioning commands

read_an_init_file

read_an_init_file(inputrc_file, [include_depth])

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;

SEE ALSO

Term::ReadLine::Perl5