Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Term::ReadLine::Zoid(3User Contributed Perl DocumentatiTerm::ReadLine::Zoid(3)

NAME
       Term::ReadLine::Zoid - another ReadLine package

SYNOPSIS
	       # In your app:
	       use Term::ReadLine;
	       my $term	= Term::ReadLine->new("my app");

	       my $prompt = "eval: ";
	       my $OUT = $term->OUT || \*STDOUT;
	       while ( defined ($_ = $term->readline($prompt)) ) {
		       # Think while (<STDIN>) {}
		       my $res = eval($_);
		       warn $@ if $@;
		       print $OUT $res,	"\n" unless $@;
	       }

	       # In some rc file
	       export PERL_RL=Zoid

DESCRIPTION
       This package provides a set of modules that form	an interactive input
       buffer written in plain perl with minimal dependencies. It features
       almost all key-bindings described in the	posix spec for the sh(1)
       utility with some extensions like multiline editing; this includes a
       vi-command mode with a save-buffer (for copy-pasting) and an undo-
       stack.

       Historically this code was part of the Zoidberg shell, but this
       implementation is complete independent from zoid	and uses the
       Term::ReadLine interface, so it can be used with	other perl programs.

       ( The documentation sometimes referes to	'the application', this	is the
       program using the ReadLine module for input. )

ENVIRONMENT
       The Term::ReadLine interface module uses	the "PERL_RL" variable to
       decide which module to load; so if you want to use this module for all
       your perl applications, try something like:

	       export PERL_RL=Zoid

KEY MAPPING
       The function name is given between parenthesis, these can be used for
       privat key maps.

   Default keymap
       The default key mapping is as follows:

       escape, ^[  (switch_mode_command)
	   Place the line editor in command mode, see
	   Term::ReadLine::Zoid::ViCommand.

       ^C  (return_empty_string)
	   End editing and return an empty string.

       ^D  (delete_char_or_eof)
	   For a single	line buffer ends editing and returns "undef" if	the
	   line	is empty, else it deletes a char.  For a multiline buffer,
	   ends	editing	and returns the	lines to the application if the	cursor
	   is on the last line and this	line is	empty, else it deletes a char.

	   Note	that the delete_char_or_eof function does what delete_char
	   should do to	be compatible with GNU readline	lib.

       delete  (delete_char)
       backspace, ^H, ^?  (backward_delete_char)
	   Delete and backspace	kill the current or previous character.	 The
	   key '^?' is by default considered a backspace because most modern
	   keyboards use this key for the "backspace" key and an escape
	   sequence for	the "delete" key.  Of course '^H' is also considered a
	   backspace.

       tab, ^I	(complete)
	   Try to complete the bigword on left of the cursor.

	   There is no default completion included in this package, so unless
	   you define a	custom expansion it doesn't do anything. See the
	   "completion_function" option.

	   Uses	the PAGER environment variable to find a suitable pager	when
	   there are more completions to be shown then would fit on the
	   screen.

	   See also the	"autolist" and "maxcomplete" options.

       return, ^J  (accept_line)
	   End editing and return the edit line	to the application unless the
	   newline is escaped.

	   If _all_ lines in the buffer	end with a single '\', the newline is
	   considered escaped you can continue typing on the next line.	This
	   behaviour can be a bit unexpected because this module has multiline
	   support which historic readline implementations have	not,
	   historically	the escaping of	a newline is done by the application
	   not by the library.	The surpress this behaviour, and let the
	   application do it's thing, disable the "automultiline" option.

	   To enter the	real multiline editing mode, press 'escape m', see
	   Term::ReadLine::Zoid::MultiLine.

       ^O  (operate_and_get_next)
	   Return the current buffer to	the application	but remember where we
	   are in history.  This can be	used to	quickly	(re-)execute series of
	   commands from history.

       ^K  (kill_line)
	   Delete from cursor to the end of the	line.

       ^L  (clear_screen)
	   Clear entire	screen.	In contrast with other readline	libraries, the
	   prompt will remain at the bottom of the screen.

       ^R  (switch_mode_isearch)
	   Enter incremental search mode, see Term::ReadLine::Zoid::ISearch.

       ^U  (unix_line_discard)
	   This	is also	known as the "kill" char. It deletes all characters on
	   the edit line and puts them in the save buffer. You can paste them
	   back	in later with 'escape-p'.

       ^V  (quoted_insert)
	   Insert next key literally, ignoring any key-bindings.

	   WARNING: control or escape chars in the editline can	cause
	   unexpected results

       ^W  (unix_word_rubout)
	   Delete the word before the cursor.

       insert  (overwrite_mode)
	   Toggle replace bit.

       home, ^A	 (beginning_of_line)
	   Move	cursor to the begin of the edit	line.

       end, ^E	(end_of_line)
	   Move	cursor to the end of the edit line.

       left, ^B	 (backward_char)
       right, ^F  (forward_char)
	   These keys can be used to move the cursor in	the edit line.

       up, page_up, ^P	(previous_history)
       down, page_down,	^N  (next_history)
	   These keys are used to rotate the history.

   Multi-line keymap
       The following keys are different	in mutline mode, the others fall back
       to the default behaviour.

       return (insert_line)
	   Insert a newline at the current cursor position.

       up (backward_line)
	   Move	the cursor one line up.

       down (forward_line)
	   Move	the cursor one line down.

       page_up (page_up)
	   Move	the cursor one screen down, or to the bottom of	the buffer.

       page_down (page_down)
	   Move	the cursor one screen up, or to	the top	of the buffer.

   Unmapped functions
       return_eof
	   End editing and return "undef".

       return_eof_maybe
	   End editing and return "undef" if the buffer	is completely empty.

       possible_completions
	   Like	complete but only shows	the completions	without	actually doing
	   them.

       redraw_current_line
	   Redraw the current line. This is done all the time automaticly so
	   you'll almost never need to call this one explicitly.

ATTRIBS
       The hash	with options can be accessed with the "Attribs"	method.	 These
       can be modified from the	rc-file	(see "FILES") or can be	set from the
       "PERL_RL" environment variable. For example to disable the "autolist"
       feature you can set "PERL_RL='Zoid autolist=0'" before you start	the
       application.

       ( Also they can be altered interactively	using the mini-buffer of the
       command mode, see Term::ReadLine::Zoid::ViCommand. )

       autohistory
	   If enabled lines are	added to the history automaticly, subject to
	   "MinLine". By default enabled.

       autoenv
	   If enabled the environment variables	"COLUMNS" and "LINES" are kept
	   up to date. By default enabled.

       autolist
	   If set completions are listed directly when a completion fails, if
	   not set you need to press "tab" twice to see	a list of possible
	   completions.	 By default enabled.

       automultiline
	   See "return"	for a description. By default enabled.

       beat
	   This	option can contain a CODE reference.  It is called on the
	   heartbeat event.

       bell
	   This	option can contain a CODE reference.  The default is "print
	   "\cG"", which makes the terminal ring a bell.

       comment_begin
	   This	option can be set to a string, if the edit line	starts with
	   this	string the line	is regarded to be a comment and	is not
	   returned to the application,	but it will appear in the history if
	   'autohistory' is also set. Defaults to "#".

	   When	there are multiple lines in the	buffer they all	need to	start
	   with	the comment string for the buffer to be	regarded as a comment.

       completion_function
	   This	option can contain either a code ref or	the name of a function
	   to perform completion. For compatibility with Term::ReadLine::Perl
	   the global scalar $readline::rl_completion_function will be checked
	   if this option isn't	defined.

	   The function	will get the following arguments: $word, $buffer,
	   $start.  Where $word	is the word before the cursor, while $buffer
	   is the complete text	on the command line; $start is the offset of
	   $word in $buffer.

	   The function	should return a	list of	possible completions of	$word.
	   The completion list is checked for double entries.

	   There is no default.

	   FIXME tell about the	meta fields for	advanced completion

       default_mode
	   Specifies the mode the buffer starts	in when	you do a "readline()",
	   also	other modes return to this mode	if you exit them.  The default
	   is 'insert' which is	the single-line	insert mode.  If you always
	   want	to edit	in multiline mode set this option to 'multiline'.

       maxcomplete
	   Maximum number of completions to be displayed, when the number of
	   completions is bigger the user is asked before displaying them. If
	   set to zero completions are always displayed.

	   If this option is set to the	string 'pager' the user	is asked when
	   the number of completions is	to big to fit on screen	and a pager
	   would be used.

       minline
	   This	option controls	which lines are	included in the	history, lines
	   shorter then	this number are	ignored. When set to "0" all lines are
	   included in the history, when set to	"undef"	all lines are ignored.
	   Defaults to "0".

       PS2 This	option can contain the prompt to be used for extra buffer
	   lines.  It defaults to "> ".

	   Although the	"PS1" prompt (as specified as an argument to the
	   "readline()"	method)	can contain newlines, the PS2 prompt can't.

       RPS1
	   This	option can contain a string that will be shown on the right
	   side	of the screen.	This is	known as the "right prompt" and	the
	   idea	is stolen from zsh(1).

       title
	   Used	to set the terminal title, defaults to the appname.

       low_latency
	   Changes the escape sequences	are read from input.  If true delays
	   evalution of	the escape key till the	next char is known.  By
	   default disabled.

FILES
       This module reads a rc-file on intialisation, either
       $HOME/.perl_rl_zoid_rc, $HOME/.zoid/perl_rl_zoid_rc or
       /etc/perl_rl_zoid_rc.  The rc-file is a perl script with	access to the
       Term::ReadLine::Zoid object through the method "current()".  If you
       want to have different behaviour	for different applications, try	to
       check for "$rl->{appname}".

	       # in for	example	~/.perl_rl_zoid_rc
	       my $rl =	Term::ReadLine::Zoid->current();

	       # set low latency
	       $rl->Attribs()->{low_latency} = 1;

	       # alias control-space to	escape
	       $rl->bindchr( chr(0), 'escape' );

	       # create	an ad hoc macro
	       $rl->bindkey('^P', sub {	$rl->press('mplayer -vo	sdl ') } );

METHODS
   ReadLine api
       Functions specified by the Term::ReadLine documentation.

       "new($appname, $IN, $OUT)"
	   Simple constructor. Arguments are the application name (used	for
	   default prompt and title string) and	optional filehandles for input
	   and output.

       "ReadLine()"
	   Returns the name of the current ReadLine module actually used.

       "readline($prompt, $preput)"
	   Returns a string entered by the user.  The final newline is
	   stripped, though the	string might contain newlines elsewhere.

	   The prompt only supports the	escape "!" for the history number of
	   the current line, use "!!" for a literal "!".  All other escapes
	   you need to parse yourself, before supplying	the prompt.  The
	   prompt defaults to "$appname	!> ".

	   If you want to do more with your prompt see Env::PS1.

	   $preput can be used to set some text	on the edit line allready.

       "addhistory($line)"
       "AddHistory($line)"
	   Add a command to the	history	(subject to the	"minline" option).

	   If "autohistory" is set this	method will be called automaticly by
	   "readline".

       "IN()"
	   Returns the filehandle used for input.

       "OUT()"
	   Returns the filehandle used for output.

       "MinLine($value)"
	   Sets	"minline" option to $value and returns old value.

       "findConsole()"
	   TODO	- what uses does this have ?

       "Attribs()"
	   Returns a reference to the options hash.

       "Features()"
	   Returns a reference to a hash with names of implemented features.

	   Be aware that the naming scheme is quite arbitrary, this module
	   uses	the same names as Term::ReadLine::Gnu for common features.

   Extended api
       "SetHistory(@hist)"
       "GetHistory()"
	   Simple acces	to the history arry, the "set" function	supports both
	   a list and a	reference, the "get" function uses "wantarray".	 Not
	   sure	which behaviour	is compatible with T:RL::Gnu.

       "TermSize()"
	   Returns number of columns and lines on the terminal.

       "continue()"
	   This	method can be called to	continue the previous "readline()"
	   call.  Can be used to build a custom	auto-mulitline feature.

       "current()"
	   Returns the current T:RL::Zoid object, for use in rc	files, see
	   "FILES".

       "bindkey($key, $sub, $map)"
	   Bind	a CODE reference to a key, the function	gets called when the
	   key is typed	with the key name as an	argument. The $map argument is
	   optional and	can be either "default", "command", "isearch" or
	   "multiline".

	   If $sub is not a reference it is considered an alias; these aliases
	   are not recursive.

	   For alphanumeric characters the name	is the character itself,
	   special characters have long	speaking names and control characters
	   are prefixed	with a '^'.

	   Binding combination with the	meta- or alt-key is not	supported (see
	   "NOTES").

   Private api
       Methods for use in overload classes.

       Avoid using these methods from the application.

       "switch_mode($mode)"
	   Switch to input mode	$mode; changes the key map and reblesses the
	   object if the "_on_switch" key returns a class name.

       "reset()"
	   Reset all temporary attributes.

       "save()"
	   Returns a ref with a	copy of	some temporary attributes.  Can	be
	   used	to switch between multiple edit	lines in combination with
	   "restore".

       "restore($save)"
	   Restores saved attributes.

       "set_history($int)"
	   Sets	history	entry $int in the buffer.

       "longest_match(@completion)"
	   Returns the longest match among the completions followed by the
	   completions itself. Used for	completion functions.

DEVELOPMENT
       FIXME minimum subroutines new mode-class

       FIXME how to set	up a keymap

       FIXME how to add	a keymap/mode

NOTES
       With most modern	keymappings the	combination of the meta	key (alt) with
       a letter	is identical with an escape character followed by that letter.

       Some functioality may in	time be	moved to the ::Base package.

TODO
       UTF8 support, or	general	charset	support, would be nice but at the
       moment I	lack the means to test these things. If	anyone has ideas or
       suggestions about this please contact me.

BUGS
       Line wrap doesn't always	displays the last character on the line	right,
       no functional bug though.

       If the buffer size exceeds the screen size some bugs appear in the
       rendering.

       Please mail the author if you find any other bugs.

AUTHOR
       Jaap Karssenberg	|| Pardus [Larus] <pardus@cpan.org>

       Copyright (c) 2004 Jaap G Karssenberg. All rights reserved.  This
       program is free software; you can redistribute it and/or	modify it
       under the same terms as Perl itself.

SEE ALSO
       Term::ReadLine::Zoid::ViCommand,	Term::ReadLine::Zoid::MultiLine,
       Term::ReadLine::Zoid::ISearch, Term::ReadLine::Zoid::FileBrowse,
       Term::ReadLine::Zoid::Base, Term::ReadLine, Env::PS1, Zoidberg

perl v5.32.0			  2020-08-10	       Term::ReadLine::Zoid(3)

NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | KEY MAPPING | ATTRIBS | FILES | METHODS | DEVELOPMENT | NOTES | TODO | BUGS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Term::ReadLine::Zoid&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help