VRL(3) VRL(3)
NAME
vrl - command-line editing library
SYNOPSIS
char *readline(prompt)
char *prompt;
void add_history(line)
char *line;
int rl_reset_terminal(terminal_name)
char *terminal_name;
DESCRIPTION
Vrl is a library that allows an application to read a line
from the terminal, giving the user additional editing
capabilities like cursor movement, filename completion and
command history.
It is a kind of a lightweight version of the GNU readline
library, having the necessary functions but smaller and
faster (like Rick Salz' editline library). It has been
developed to work with the rc-shell, but may be useful for
other things as well.
readline() will display the given prompt on the screen,
and allows the user to enter a line of text. When the user
is done with it, the line will be returned to the caller
with the trailing newline removed. The caller should
free() the buffer afterward. If the user generates an
EOF, NULL is returned.
add_history() should be used to add commands to the his-
tory, readline() does not do that itself.
Normally, the vrl library will check $TERM and $TERMCAP,
and reinitialise if either of them changes. If a shell
does not update these variables in its own environment, it
should use rl_reset_terminal() to inform the vrl library
about this.
The vrl library will catch SIGWINCH so that it is informed
of window size changes, and re-generates it just before it
returns from readline(). The tty's susp, intr and quit
characters will generate SIGTSTP, SIGINT, and SIGQUIT just
before returning an empty line to the caller.
EDITING COMMANDS
The available commands are listed below:
^A Move to the start of the line
^B Move cursor backward
vrl-1.3 1
VRL(3) VRL(3)
^D Delete char under cursor. If the line is empty and
the previous character typed was not a delete-char
command, EOF is generated.
^E Move to the end of the line
^F Move cursor forward
^H Delete char left of cursor
^I Apply filename completion to the word under the
cursor (^I is the [TAB] key)
^J Accept the line (^J usually corresponds to the
[NEWLINE] or [ENTER] key)
^K Delete to the end of the line
^L Redisplay the line
^M Accept the line
^N Display next history line
^O Re-read the initialisation file
^P Display previous history line
^R Backward history search
^T Transpose chars
^U Kill the whole line
^V Insert next character as is, even if it is a com-
mand
^W Delete the word under the cursor
^? Delete char under the cursor (^? usually corre-
sponds to the [DEL] key)
ESC-ESC or ESC-?
List all possible completions without changing the
command-line.
ESC-* Replace the expression with all matching filenames.
ESC-v Display the version of the vrl library on stdout
In addition to this, the following keypad and keyboard
function keys are recognised:
vrl-1.3 2
VRL(3) VRL(3)
Left-arrow
Move cursor backward
Right-arrow
Move cursor forward
Up-arrow
Display previous history line
Down-arrow
Display next history line
Delete-key
Delete char under cursor
Backspace-key
Delete char left of cursor
Insert-key
Toggle insert/overwrite mode
Home-key
Move to the start of the line
End-key
Move to the end of the line
Lastly, the following special characters (as set with
stty(1) ) are recognised. They are ignored if they happen
to correspond to one of the built-in command characters.
erase Delete char left of cursor (usually ^H or ^?)
kill Kill the whole line (usually ^U)
eof Accept the line if it is not empty, EOF otherwise
(usually ^D)
werase Delete the word under the cursor (usually ^W)
lnext Insert the next character as is (usually ^V)
reprint
Redisplay the line (usually ^R)
susp Suspend the current process. Vrl will send a SIGT-
STP to the application, and readline() will return
an empty line (usually ^Z)
intr Interrupt the current process. Vrl will send a SIG-
INT to the application, and readline() will return
an empty line (usually ^C)
quit Interrupt the current process. Vrl will send a
vrl-1.3 3
VRL(3) VRL(3)
SIGQUIT to the application, and readline() will
return an empty line (usually ^)
FILENAME COMPLETION
The filename completion function acts on the text under
the cursor. The text may contain wildcards like '*' and
'?', and environment variables are expanded,
If the completion is unique, the text will be replaced by
the filename. If the completion is ambiguous, the text
will be replaced by the common prefix of all the possible
completions. Whether they are listed is controlled by the
"completion" flag described below.
INITIALISATION FILE
At startup, the vrl library will look for a file named
.vrlrc in the user's home directory. This file should con-
tain one keyword+value pair per line, empty lines and
lines starting with a '#' are ignored.
The '^O' command (see above) can be used to force vrl to
re-read this file.
The following option keywords are recognised:
beep on | off
If set to "on", vrl will beep when the requested
operation is impossible, setting it to "off"
silences it. Default is "on".
insertmode on | off
If "on", characters typed will be inserted. If set
to "off", new characters will overwrite the exist-
ing ones. Default is "on".
histmax <num>
The maximum number of entries to store in the com-
mand history.
histmode all | norepeat | nodups
This option defines how commands are added to the
history. If set to "all", every command is added
without hesitation. When set to "norepeat", a com-
mand is only added if it is different from the pre-
vious one. Lastly, when it is set to "nodups", the
command is added but all previous occurrences in
the history are removed. Default is "norepeat".
completion always | nochange | never
This option defines what happens when a filename
completion is ambiguous. If set to "always", all
alternatives are listed automatically, "nochange"
means that they are only listed when the filename
to complete didn't change (i.e. it didn't become
vrl-1.3 4
VRL(3) VRL(3)
longer), and setting it to "never" means that noth-
ing will be listed, ever. Default is "nochange".
ansicursorkeys on | off
On some terminals (e.g. xterm), you can't type
ahead with the cursor keys since they don't gener-
ate the same sequence as when the keypad is acti-
vated. The symptom is that instead of displaying
the previous command on cursor-up, ^[[A is dis-
played. Setting this option to "on" allows vrl to
recognise ^[[A, ^[[B, ^[[C, and ^[[D as alterna-
tives for cursor-up, -down, -right, and -left,
which makes type-ahead possible on a number of ter-
minals (e.g. xterm, vt100, ...). Default is "on".
FILES
$HOME/.vrlrc The user's personal initialisation file
SEE ALSO
editline(3), readline(3)
AUTHOR
Gert-Jan Vons <vons@usa.net>
vrl-1.3 5
