Readline - GNU Readline binding for perl6
NAME
Readline - GNU Readline binding for perl6
SYNOPSIS
my $readline = Readline.new; while my $response = $readline.readline( "prompt here (<cr> to exit)> " ) { $readline.add-history( $response ) if $response ~~ /\S/; say "[$response]"; }
LIBRARY
By default the Perl 6 module searches for libreadline.so.* and takes the most recent match it can find.
If you're on OS X, it searches for libreadline.*.dylib. On OpenBSD it searches for libereadline.so.*.
While I'd prefer to use LibraryCheck's technique of just attempting to link to a library, it doesn't seem to work inside of the is native(&func) attribute. So instead, it defaults to v7 (the current version as of 2018-07-14) and searches for other versions along a fixed set of library paths, taken from bug reports.
I'll eventually put this into a proper library-find method.
METHODS
readline( Str $prompt ) returns Str
initialize( ) returns int32
Initialize or re-initialize Readline's internal state. It's not strictly necessary to call this; readline() calls it before reading any input.
ding( ) returns int32
Ring the terminal bell, obeying the setting of $bell-style.
add-defun( Str $str, &callback (int32, int32 --> int32), Str $key ) returns int32
Add name to the list of named functions. Make function be the function that gets called. If $key is not -1, then bind it to function using rl_bind_key().
Editor's note - $key is an integer in the underlying C API - If you want to use the actual C function call, please call rl_add_defun() instead.
Using this function alone is sufficient for most applications. It is the recommended way to add a few functions to the default functions that Readline has built in. If you need to do something other than adding a function to Readline, you may need to use the underlying functions described below.
variable-value( Str $variable ) returns Str
Return a string representing the value of the Readline variable $variable. For boolean variables, this string is either `on' or `off'.
variable-bind( Str $variable, Str $value ) returns int32
Make the Readline variable $variable have value $alue. This behaves as if the readline command `set variable value' had been executed in an inputrc file (see section 1.3.1 Readline Init File Syntax).
set-key( Str $str, &callback (int32, int32 --> int32), Keymap $map )
Equivalent to rl-bind-keyseq-in-map().
macro-bind( Str $keyseq, Str $macro, Keymap $map ) returns int32
Bind the key sequence $keyseq to invoke the macro $macro. The binding is performed in $map. When $keyseq is invoked, the macro will be inserted into the line. This function is deprecated; use rl_generic_bind() instead.
named-function( Str $s ) returns &callback (int32, int32 --> int32)
Return the function with name name.
function-of-keyseq( Str $keyseq, Keymap $map, Pointer[int32] $type ) returns &callback (int32, int32 --> int32)
Return the function invoked by $keyseq in keymap $map. If $map is Nil, the current keymap is used. If $type is not Nil, the type of the object is returned in the int variable it points to (one of ISFUNC, ISKMAP, or ISMACR).
list-funmap-names( )
Print the names of all bindable Readline functions to rl_outstream.
invoking-keyseqs-in-map( Pointer[&callback (int32, int32 --> int32)] $p-cmd, Keymap $map ) returns CArray[Str]
Return an array of strings representing the key sequences used to invoke function in the keymap $map.
invoking-keyseqs( Pointer[&callback (int32, int32 --> int32)] $p-cmd ) returns CArray[Str]
Return an array of strings representing the key sequences used to invoke function in the current keymap.
function-dumper( Bool $readable )
Print the readline function names and the key sequences currently bound to them to $rl_outstream. If $readable is True, the list is formatted in such a way that it can be made part of an inputrc file and re-read.
Editor's note - The Perl6 layer translates True values of $readable to non-zero, so if you want to specify a particular int32 value, please use the underlying rl_function_dumper() call.
macro-dumper( Bool $readable )
Print the key sequences bound to macros and their values, using the current keymap, to $rl_outstream. If $readable is True, the list is formatted in such a way that it can be made part of an inputrc file and re-read.
Editor's note - The Perl6 layer translates True values of $readable to non-zero, so if you want to specify a particular int32 value, please use the underlying rl_macro_dumper() call.
variable-dumper( Bool $readable )
Print the readline variable names and their current values to $rl_outstream. If readable is True, the list is formatted in such a way that it can be made part of an inputrc file and re-read.
Editor's note - The Perl6 layer translates True values of $readable to non-zero, so if you want to specify a particular int32 value, please use the underlying rl_variable_dumper() call.
read-init-file( Str $filename )
Read keybindings and variable assignments from $filename (see section 1.3 Readline Init File).
parse-and-bind( Str $line ) returns int32
Parse $line as if it had been read from the inputrc file and perform any key bindings and variable assignments found (see section 1.3 Readline Init File).
add-funmap-entry( Str $name, &callback (int32, int32 --> int32) ) returns int32
Add $name to the list of bindable Readline command names, and make function the function to be called when name is invoked.
funmap-names( ) returns CArray[Str]
Return a NULL terminated array of known function names. The array is sorted. The array itself is allocated, but not the strings inside. You should free the array, but not the pointers, using free or rl_free when you are done.
push-macro-input( Str $macro )
Cause $macro to be inserted into the line, as if it had been invoked by a key bound to a macro. Not especially useful; use rl_insert_text() instead.
free-undo-list( )
Free the existing undo list.
do-undo( ) returns int32
Undo the first thing on the undo list. Returns False if there was nothing to undo, True if something was undone.
Editor's note - The underlying C function returns non-zero on error, this is mapped onto a Perl6 Bool type. If you want the original behavior, call the underlying rl_do_undo() function rather than the Perl6 layer.
begin-undo-group( ) returns int32
Begins saving undo information in a group construct. The undo information usually comes from calls to rl_insert_text() and rl_delete_text(), but could be the result of calls to rl_add_undo().
end-undo-group( ) returns int32
Closes the current undo group started with rl_begin_undo_group (). There should be one call to rl_end_undo_group() for each call to rl_begin_undo_group().
modifying( int32 $start, int32 $end ) returns int32
Tell Readline to save the text between $start and $end as a single undo unit. It is assumed that you will subsequently modify that text.
redisplay( )
Change what's displayed on the screen to reflect the current contents of rl_line_buffer.
on-new-line( ) returns int32
Tell the update functions that we have moved onto a new (empty) line, usually after outputting a newline.
on-new-line-with-prompt( ) returns int32
Tell the update functions that we have moved onto a new line, with $rl_prompt already displayed. This could be used by applications that want to output the prompt string themselves, but still need Readline to know the prompt string length for redisplay. It should be used after setting rl_already_prompted.
forced-update-display( ) returns int32
Force the line to be updated and redisplayed, whether or not Readline thinks the screen display is correct.
clear-message( ) returns int32
Clear the message in the echo area. If the prompt was saved with a call to rl_save_prompt before the last call to rl_message, call rl_restore_prompt before calling this function.
reset-line-state( ) returns int32
Reset the display state to a clean state and redisplay the current line starting on a new line.
crlf( ) returns int32
Move the cursor to the start of the next screen line.
show-char( Str $c ) returns int32
Display character c on rl_outstream. If Readline has not been set to display meta characters directly, this will convert meta characters to a meta-prefixed key sequence. This is intended for use by applications which wish to do their own redisplay.
Editor's note - $key is an integer in the underlying C API - If you want to use the actual C function call, please call rl_show_char() instead.
save-prompt( )
Save the local Readline prompt display state in preparation for displaying a new message in the message area with rl_message().
restore-prompt( )
Restore the local Readline prompt display state saved by the most recent call to rl_save_prompt. if rl_save_prompt was called to save the prompt before a call to rl_message, this function should be called before the corresponding call to rl_clear_message.
replace-line( Str $text, int32 $clear-undo )
Replace the contents of $rl_line_buffer with $text. The point and mark are preserved, if possible. If $clear-undo is non-zero, the undo list associated with the current line is cleared.
insert-text( Str $text ) returns int32
Insert $text into the line at the current cursor position. Returns the number of characters inserted.
delete-text( int32 $start, int32 $end ) returns int32
Delete the text between $start and $end in the current line. Returns the number of characters deleted.
kill-text( int32 $start, int32 $end ) returns int32
Copy the text between $start and $end in the current line to the kill ring, appending or prepending to the last kill if the last command was a kill command. The text is deleted. If $start is less than $end, the text is appended, otherwise prepended. If the last command was not a kill, a new kill ring slot is used.
copy-text( int32 $start, int32 $end ) returns Str
Return a copy of the text between $start and $end in the current line.
prep-terminal( int32 $meta-flag )
Modify the terminal settings for Readline's use, so readline() can read a single character at a time from the keyboard. The $meta-flag argument should be non-zero if Readline should read eight-bit input.
deprep-terminal( )
Undo the effects of rl_prep_terminal(), leaving the terminal in the state in which it was before the most recent call to rl_prep_terminal().
tty-set-default-bindings( Keymap $map )
Read the operating system's terminal editing characters (as would be displayed by stty) to their Readline equivalents. The bindings are performed in keymap $map.
tty-unset-default-bindings( Keymap $map )
Reset the bindings manipulated by $rl_tty_set_default_bindings so that the terminal editing characters are bound to $rl_insert. The bindings are performed in keymap $map.
reset-terminal( Str $terminal-name ) returns int32
Reinitialize Readline's idea of the terminal settings using $terminal-name as the terminal type (e.g., vt100). If terminal_name is NULL, the value of the TERM environment variable is used.
resize-terminal( )
Update Readline's internal screen size by reading values from the kernel.
set-screen-size( int32 $rows, int32 $cols )
Set Readline's idea of the terminal size to $rows rows and $cols columns. If either $rows or $cols is less than or equal to 0, Readline's idea of that terminal dimension is unchanged.
If an application does not want to install a SIGWINCH handler, but is still interested in the screen dimensions, Readline's idea of the screen size may be queried.
get-screen-size( Pointer[int32] $rows, Pointer[int32] $cols )
Return Readline's idea of the terminal's size in the variables pointed to by the arguments.
reset-screen-size( )
Cause Readline to reobtain the screen size and recalculate its dimensions.
get-termcap( Str $cap ) returns Str
Retrieve the string value of the termcap capability $cap. Readline fetches the termcap entry for the current terminal name and uses those capabilities to move around the screen line and perform other terminal-specific operations, like erasing a line. Readline does not use all of a terminal's capabilities, and this function will return values for only those capabilities Readline uses.
extend-line-buffer( int32 $len )
Ensure that rl_line_buffer has enough space to hold $len characters, possibly reallocating it if necessary.
alphabetic( Str $c ) returns Bool
Return True if c is an alphabetic character.
Editor's note - The underlying C function returns non-zero on error, this is mapped onto a Perl6 Bool type. If you want the original behavior, call the underlying rl_alphabetic() function rather than the Perl6 layer.
Editor's note - $c is an integer in the underlying C API - If you want to use the actual C function call, please call rl_alphabetic() instead.
free( Pointer $mem )
Deallocate the memory pointed to by $mem. $mem must have been allocated by malloc.
set-paren-blink-timeout( int32 $c ) returns int32
Set the time interval (in microseconds) that Readline waits when showing a balancing character when blink-matching-paren has been enabled.
complete-internal( int32 $what-to-do ) returns int32
Complete the word at or before point. $what-to-do says what to do with the completion. A value of `?' means list the possible completions. `TAB' means do standard completion. `*' means insert all of the possible completions. `!' means to display all of the possible completions, if there is more than one, as well as performing partial completion. `@' is similar to `!', but possible completions are not listed if the possible completions share a common prefix.
username-completion-function ( Str $text, int32 $i ) returns Str # XXX doesn't exist?
A completion generator for usernames. $text contains a partial username preceded by a random character (usually `~'). As with all completion generators, state is zero on the first call and non-zero for subsequent calls.
filename-completion-function ( Str $text, int32 $i ) returns Str # XXX Doesn't exist?
A generator function for filename completion in the general case. $text is a partial filename. The Bash source is a useful reference for writing application-specific completion functions (the Bash completion functions call this and other Readline functions).
completion-mode( Pointer[&callback (int32, int32 --> int32)] $cfunc ) returns int32
Returns the appropriate value to pass to rl_complete_internal() depending on whether $cfunc was called twice in succession and the values of the show-all-if-ambiguous and show-all-if-unmodified variables. Application-specific completion functions may use this function to present the same interface as rl_complete().
save-state( readline_state $sp ) returns int32
Save a snapshot of Readline's internal state to $sp. The contents of the readline_state structure are documented in `readline.h'. The caller is responsible for allocating the structure.
tilde-expand( Str $str ) returns Str
Return a new string which is the result of tilde-expanding $str.
tilde-expand-word( Str $filename ) returns Str
Do the work of tilde expansion on $filename. $filename starts with a tilde. If there is no expansion, call $tilde_expansion_failure_hook.
tilde-find-word( Str $word, int32 $offset, Pointer[int32] $p-end-offset ) returns Str
Find the portion of the string beginning with ~ that should be expanded.
restore-state( readline_state $sp ) returns int32
Restore Readline's internal state to that stored in $sp, which must have been saved by a call to rl_save_state(). The contents of the readline_state structure are documented in `readline.h'. The caller is responsible for freeing the structure.