/ 
Term-ReadLine-Perl5-1.04
River stage zero No dependents
/ readline

NAME

Term::ReadLine::readline

DESCRIPTION

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

SUBROUTINES

InitKeyMap

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

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

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.

add_line_to_history

Insert into history list if:

  • bigger than the minimal length

  • not same as last entry

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;

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

Term::ReadLine::readline

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.

Synopsis

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

What's Cool

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

What's not Cool

  • 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 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 set'able 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. n =item $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 _<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.

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.

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:

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