NAME
rlwrap - readline wrapper
SYNOPSIS
rlwrap [rlwrap-options] command ...
DESCRIPTION
rlwrap runs the specified command, intercepting user input in order to
provide readline’s line editing, persistent history and completion.
rlwrap tries to be completely transparent - you (or your shell)
shouldn’t notice any difference between command and rlwrap command -
except the added readline functionality, of course. This should even
hold true when you are re-directing, piping and sending signals from
and to command, or when command manipulates its terminal settings.
There are many options to add (programmable) completion, handle
multi-line input, colour and re-write prompts. If you don’t need them
(and you probably don’t), you can skip the rest of this manpage.
OPTIONS
-a, --always-readline [<password_prompt>]
Always remain in "readline mode", regardless of command’s
terminal settings. Use this option if you want to use rlwrap
with commands that already use readline. NB: With this option,
rlwrap will echo (and save) passwords, unless you give command’s
password prompt as an argument. The argument is optional; if
given, it has to directly follow the option without an
intervening space.
On a linux machine you can use the -N (--no-children) option to
prevent the wrapping of pagers and editors called from command;
this should make them much more usable
Many commands that need --always-readline may also need -t dumb
to prevent terminal control sequences from confusing rlwrap
(although this will annoy the above-mentioned pagers and
editors)
-A, --ansi-colour-aware
Prompts that use colour will confuse rlwrap, especially at the
end of long input lines. This option will make rlwrap better
behaved in such cases. If the prompt contains anything fancier
than ANSI colour codes, this option may actually make things
worse.
-b, --break-chars <list_of_characters>
Consider the specified characters word-breaking (whitespace is
always word-breaking). This determines what is considered a
"word", both when completing and when building a completion word
list from files specified by -f options following (not
preceding!) it. Default list (){}[],+-=&^%$#@"";|\ Unless -c is
specified, / and . (period) are included in the default list.
-c, --complete-filenames
Complete filenames (filename completion is always
case-sensitive, even with the -i option) When doing this, rlwrap
keeps track of commands working directory.
-C, --command-name <command_name>|<N>
Use command_name instead of command to determine the names of
history and completion files, and to initialise readline (as
specified in ~/.inputrc). A numeric argument N > 0 means: use
the Nth argument counting backwards from the end of the argument
list
-D, --history-no-dupes n
How agressively to weed out duplicate entries from the input
history. If n = 0, all inputs are kept in the history list, if
n = 1 (this is the default) consecutive duplicates are dropped
from the list, while n = 2 will make rlwrap drop all previous
occurrences of the current input from the list.
-f, --file file
Split file into words and add them to the completion word list.
This option can be given more than once, and adds to the default
completion list in $RLWRAP_HOME or
/usr/share/rlwrap/completions.
-g, --forget-matching regexp
Forget (i.e. drop from history list) all input lines that match
the POSIX 1003.2 regular expression regexp. The match is always
case-insensitive. regexp may be an ordinary string. For more
about regular expressions, see regex (7)
-h, --help
Print a short help message.
-H, --history-filename file
Read command history from file (and write it back there if
--histsize >= 0)
-i, --case-insensitive
Ignore case when completing (filename completion remains
case-sensitive). This option has to come before any -f options.
-I, --pass-sigint-as-sigterm
Send a TERM signal to command when an INT is received (e.g. when
you press CTRL-C).
-l, --logfile file
When in readline mode, append command’s output (including
echo’ed user input) to file (creating file when it doesn’t
exist).
-n, --no-warnings
Don’t print warnings.
-N, --no-children
(linux only) Don’t rlwrap command’s children: whenever rlwrap
notices that command is waiting for one of its children, it
switches to direct mode, handing down all keypresses
immediately. With this option commands that need
--always-readline can call editors and pagers and still be
usable.
-m, --multi-line [<newline_substitute>]
Enable multi-line input using a "newline substitute" character
sequence (" \ ", [space-backslash-space] by default). Newline
substitutes are translated to newlines before sending the input
to command. With this option, you can call an external editor
$RLWRAP_EDITOR on the (expanded) current input with the
rlwrap_call_editor key (CTRL-^ by default) The argument is
optional; if given, it has to directly follow the option
without an intervening space.
-o, --one-shot
Send an EOF to command after accepting the first line of input
-O, --only-cook regexp
Only ever "cook" prompts that match regexp
-p, --prompt-colour [<colour_name>|<Colour_name>|<colour_spec>]
Use one of the colour names black, red, green, yellow, blue,
cyan, purple (=magenta) or white, or an ANSI-conformant
<colour_spec> to colour any prompt displayed by command. An
uppercase colour name (Yellow or YELLOW ) gives a bold prompt.
Prompts that already contain (colour) escape sequences or one of
the readline "ignore markers" (ASCII 0x01 and 0x02) are not
coloured. This option implies --ansi-colour-aware. <colour
spec> has the form <attr>;<fg>[;<bg>] Example: -p’1;31’ will
give a bold red prompt on the current background (this is the
default when no argument is given). Google for ’ANSI color’ to
learn more about colour codes. The argument is optional; if
given, it has to directly follow the option without an
intervening space.
-P, --pre-given text
Start rlwrap with text in its edit buffer (this will
automatically set the --always-readline option).
-q, --quote-characters <list_of_characters>
Assume that the given characters act as quotes, e.g. when
matching parentheses. Take care to escape the list properly for
your shell (example: -q "\"’", which happens to be the default,
or -q "\"" which will be better for Lisp users)
-r, --remember
Put all words seen on in- and output on the completion list.
-R, --renice
Make rlwrap nicer than command (cf nice (1)). This may prevent
rlwrap from interrupting command to display a prompt when
command is still "thinking" about what to output next.
-s, --histsize <N>
Limit the history list to N entries, truncating the history file
(default: 300). A negative size -N means the same as N, but
treats the history file as read-only.
-S, --substitute-prompt <prompt>
Substitute the specified prompt for command’s own prompt.
Mainly useful when command doesn’t have a prompt.
-t, --set-term-name <name>
Set command’s TERM to <name>. Programs that confuse rlwrap with
fancy screen control codes can sometimes be tamed by specifying
-t dumb
-v, --version
Print rlwrap version.
-w, --wait-before-prompt <timeout>
In order to determine if command’s last output is a prompt,
rlwrap waits timeout millisecs after receiving it. Only when no
more output has arrived, it is cooked (coloured, filtered and/or
replaced by a substitute prompt) and displayed as a prompt.
Before this the prompt is displayed "uncooked". Most users won’t
notice, but heavy cookers can prepend the timeout with a minus
sign, making rlwrap hold back the prompt until it has been
cooked ("patient mode"). This will prevent flashing of the
prompt, but it will also interfere with long output lines and
make switches from direct to readline mode less reliable.
Default timeout: 40 ms
-z, --filter <filter>
Use a filter to change rlwrap’s behaviour. A filter can be used
to keep certain input out of the history, to change the prompt,
to implement simple macros or programmable completion.. rlwrap
comes with a special perl module (cf. RlwrapFilter(3pm)) for
easy filter writing. A number of example filters are installed
in the directory /usr/share/rlwrap/filters. "rlwrap -z <filter>"
displays information about a filter, "rlwrap -z listing" lists
all currently installed filters. If <filter> needs arguments,
you should quote the whole filter command line:
rlwrap -z ’filter args’ command
If this command line contains shell metacharacters, rlwrap
passes it to the system shell for parsing.
EXAMPLES
Run nc (netcat) with command-line editing and history
rlwrap nc
Wrap smbclient (which uses readline itself), keep passwords out of the
history and don’t wrap commands launched from smbclient (like more)
rlwrap -aPassword: -N smbclient //PEANUT/C
Wrap gauche (a Scheme interpreter) with a bold blue prompt, enable
mult-line editing and don’t consider single quotes as quotes (so that
the parentheses in (print ’q) match)
rlwrap -pBlue -m -q’"’ gosh
Get a list of all currently installed filters
rlwrap -z listing
Get help for the filter pipeto
rlwrap -z pipeto
Wrap sqlite3, use the pipeto filter to be able to pipe the output of
SQL commands through grep and/or less, complete (case-insensitively) on
the SQL keywords in ’sql_words’
rlwrap -a -z pipeto -i -f sql_words sqlite3 contacts.db
In a shell script, use rlwrap in ’one-shot’ mode as a replacement for
read
order=‘rlwrap -S ’Your pizza? ’-H past_orders -P Margherita -o cat‘
DIRECT MODE AND READLINE MODE
Most simple console commands put your terminal either in "cooked" or in
"raw" mode. In cooked mode the terminal will wait until you press the
ENTER key before handing the entire line to the program, in raw mode
every key you press is handed down immediately. In cooked mode you
generally can use the backspace key, but not the arrow keys, to edit
your input. Most simple console commands use cooked mode whenever they
want whole input lines, and raw mode when they want single keypresses.
More sophisticated commands tend to use raw mode all the time; they may
sometimes be rlwrappable with the -a (and -N) options.
When you rlwrap command, rlwrap will run it a in a separate session,
with its own "pseudo-terminal" (pty), and monitor this pty to see
whether the pty is in raw mode or in cooked mode. In the first case,
rlwrap will copy all input and output directly between command and your
terminal ("direct mode"). In the second case, rlwrap will use readline
to edit your input ("readline mode"), and monitor command’s output -
every last line that doesn’t end with a newline is a potential prompt.
How it handles such a candidate prompt depends on its being in
"patient" or "impatient" mode:
PATIENT AND IMPATIENT MODE
If command writes a lot of output, it tends to be written (and read) in
"chunks". Not all chunks will end with a newline, and we need to
distinguish their last lines from real prompts, especially if we want
to re-write ("cook") prompts. rlwrap solves this (almost) by waiting a
little, to see if there is more to come. "A little" is 40 msec by
default, but this can be changed with the -w option. Normally rlwrap
writes the suspected prompt as soon as it is received, replacing it
with a "cooked" version afer the wait time. This is called "impatient"
mode. If you don’t like the flashing effect (which will only occur when
you "cook" the prompt heavily) you can put rlwrap in "patient mode" by
specifying a negative value with -w (e.g. -w -40). Rlwrap will then
hold back the prompt and only print if after cooking.
COOKING PROMPTS
If and when rlwrap decides that it has a prompt, it will perform a
number of actions on it, depending on the given options: filtering
(-z), substituting (-S) and colouring (-p), in this order. The
resulting "cooked" prompt is then printed (after erasing the "raw"
prompt, if necessary)
SPECIAL KEYS
Control + O
Accept the current line, but don’t put it in the history list.
This action has a readline command name
rlwrap-accept-line-and-forget
Control + ^
Use an external editor to edit the current input (this will only
work if the -m option is set). This action has a readline
command name rlwrap-call-editor
These special keys were chosen because are not currently bound to any
readline action. If you don’t like them, (or your window manager
swallows them) they can be re-bound more sensibly by including lines
like the following in your ~/.inputrc:
"\M-\C-m": rlwrap-accept-line-and-forget # ESC-ENTER
"\C-xe": rlwrap-call-editor # CTRL-x e
cf. the readline(3) manpage for more about re-binding keys
ENVIRONMENT
RLWRAP_HOME:
directory in which the history and completion files are kept.
RLWRAP_EDITOR (or else EDITOR, or else VISUAL):
editor to use for multi-line input. Example:
export RLWRAP_EDITOR="microemacs -l%L:%C"
export RLWRAP_EDITOR="vi +%L"
The last example is the default; %L and %C are replaced by line and
column numbers corresponding to the cursor position in rlwrap’s edit
buffer
RLWRAP_FILTERDIR:
Any executable along your PATH can in theory be used as a
filter, but because filters have to follow a rather outlandish
protocol (cf. RlwrapFilter (3)) it is a good idea to keep them
separate. This is why rlwrap adds a special filter directory to
$PATH just before launching a filter. By default, this is
/usr/share/rlwrap/filters, but $RLWRAP_FILTERDIR is used if set.
SIGNALS
A number of signals are forwarded to command: HUP INT QUIT USR1 USR2
TERM and (by way of resizing command’s terminal) WINCH. Some care is
taken to handle TSTP (usually a result of a CTRL-Z from the terminal)
sensibly - for example, after suspending rlwrap in the middle of a line
edit, continuing (by typing ’fg’) will land you at the exact spot where
you suspended it.
Filters that take more than 1 second to respond can be interrupted by a
CTRL-C from the terminal (although rlwrap will not survive this)
If command changes the keystrokes that send a particular signal from
the keyboard (like emacs, which uses CTRL-G instead of CTRL-C) rlwrap
will do the same.
When command is killed by a signal, rlwrap will clean up, reset its
signal handlers an then commit suicide by sending the same signal to
itself. This means that your shell sees the same exit status as it
would have seen without rlwrap.
REDIRECTION
When the standard input is not a terminal, editing input doesn’t make
sense, so rlwrap will ignore all options and simply execute command.
When stdout (or stderr) is not a terminal, rlwrap will re-open it to
/dev/tty (the users terminal) after it has started command, so that
command’s output is redirected as expected, but keyboard input and
rlwrap error messages are still visible.
The upshot of this is that rlwrap command behaves more or less like
command when redirecting.
EXIT STATUS
non-zero after a rlwrap error, or else command’s exit status. rlwrap
will always leave the terminal in a tidy state, even after a crash.
FILES
rlwrap expects its history and completion files in $RLWRAP_HOME, but
uses .dotfiles in the user’s home directory if this variable is not
set. This will quickly become messy if you use rlwrap a lot.
$RLWRAP_HOME/command_history, ~/.command_history
History for command
$RLWRAP_HOME/command_completions, ~/.command_completions
Per-user completion word list for command. rlwrap never writes
into this list, but one can combine -l and -f options to to
simulate the effect of a -r option that works across
invocations.
/usr/share/rlwrap/completions/command
System-wide completion word list for command. This file is only
consulted if the per-user completion word list is not found.
$INPUTRC, ~/.inputrc
Individual readline initialisation file (See readline (3) for
its format). rlwrap sets its application name to command (unless
you use the -C option), enabling different behaviours for
different commands. One could e.g. put the following lines in
~/.inputrc:
$if coqtop
set show-all-if-ambiguous On
$endif
making rlwrap show all completions whenever it runs coqtop
BUGS and LIMITATIONS
Though it is flexible, delivers the goods (readline functionality), and
adheres to the Unix "many small tools" paradigm, rlwrap is a kludge.
It cannot know anything about command’s internal state, which makes
context-sensitive completion impossible. Using the readline library
from within command is still the best option.
Also, because "it takes two to tango" there is no way for rlwrap to
synchronise its internal state with command, resulting in a number of
subtle race conditions, where e.g. command may have changed the state
of its terminal before rlwrap has read command output that was written
before the state change. You will notice these races especially on a
busy machine and with heavy "cooking" and filtering, when suddenly (and
unpredictably) promtps or command output are garbled or incorrectly
coloured.
Filtering is a very recent addition, and should be considered alpha
quality.
rlwrap can try, but often fails to, handle prompts that contain control
characters. A flter may be used to clean up the prompt.
VERSION
This manpage documents rlwrap version 0.37
AUTHORS
The readline library (written by Chet Ramey) does all the hard work
behind the scenes, the pty-handling code has been taken practically
unchanged from rxvt-2.7.10 (currently maintained by Geoff C. Wing), and
completion word lists are managed by Damian Ivereigh’s libredblack
library. The few remaining lines of code were written by Hans Lub
(hanslub42@gmail.com).
SEE ALSO
readline(3), RlwrapFilter(3pm)
January 4, 2010 rlwrap(1)