MAN page from RedHat EL 6 rlwrap-0.42-1.el6.x86_64.rpm

rlwrap

Section: User Commands (1)
Updated: November 14, 2014
Index

NAME

rlwrap - readline wrapper

SYNOPSIS

rlwrap[rlwrap-options]command ...

DESCRIPTION

rlwrap runs the specified command, intercepting user inputin order to provide readline's line editing, persistent historyand completion.

rlwrap tries to be completely transparent - you(or your shell) shouldn't notice any difference between command and rlwrapcommand - except the added readline functionality, of course.This should even hold true when you are re-directing, piping andsending signals from and to command, or when commandmanipulates its terminal settings.

There are many options to add(programmable) completion, handle multi-line input, colour andre-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 alreadyuse readline. NB: With thisoption, rlwrap will echo (and save) passwords, unless you give command'spassword prompt as an argument.The argument is optional; if given, it has to directly follow the option without anintervening 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 confusingrlwrap (although this will annoy the above-mentioned pagers andeditors)

-A, --ansi-colour-aware

Prompts that use colour will confuse rlwrap, especially at the end oflong input lines. This option will make rlwrap better behaved in such cases.If the prompt contains anything fancier than ANSI colour codes, this optionmay actually make things worse.

-b, --break-chars list_of_characters

Consider the specified characters word-breaking (whitespace isalways word-breaking). This determines what is considered a "word",both when completing and when building a completion word list fromfiles 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 ofhistory and completion files, and to initialise readline (as specified in~/.inputrc). A numeric argument N > 0 means: use the Nth argument countingbackwards 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, ifn = 1 (this is the default) consecutive duplicates are droppedfrom the list, while n = 2 will make rlwrap drop allprevious occurrences of the current input from the list.

-e, --extra-char-after-completion char

By default, rlwrap appends a space after any inserted completion text. Use this option to change this to '' (don't insert anything) or some other character.

-f, --file file

Split file into words and add them to the completion word list. Thisoption can be given more than once, and adds to the defaultcompletion list in $RLWRAP_HOME or /usr/share/rlwrap/completions.

Specifying -f . will make rlwrap use the current history file as acompletion word list.

-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 ordinarystring. 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 youpress CTRL-C).

-l, --logfile file

When in readline mode, append command's output (including echo'ed user input) tofile (creating file when it doesn't exist).

-n, --no-warnings

Don't print warnings.

-N, --no-children

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.

This option needs /proc/command_pid/wchan, so it only works with linux kernels configured with CONFIG_KALLSYMS.

-m, --multi-line [newline_substitute]

Enable multi-line input using a "newline substitute" charactersequence (" \ ", [space-backslash-space] by default). Newlinesubstitutes are translated to newlines before sending the input tocommand. With this option, you can call an external editor$RLWRAP_EDITOR on the (expanded) current input with therlwrap_call_editor key (CTRL-^ by default)The argument is optional; if given, it has to directly follow the option without anintervening space.

-M, --multi-line-ext .ext

Call multi-line-editor on temporary files with filename extension .ext (useful for e.g. automatic syntax colouring)

-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 bycommand. 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 thecurrent background (this is the default when no argument isgiven). Google for 'ANSI color' to learn more about colour codes.The argument is optional; if given, it has to directly follow the option without anintervening space.

-P, --pre-given text

Start rlwrap with text in its edit buffer (this will automaticallyset the --always-readline option).

-q, --quote-characters list_of_characters

Assume that the given characters act as quotes, e.g. when matchingparentheses. Take care to escape the list properly for your shell (example: -q "\"'", which happens to be thedefault, 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

-U, --mirror-arguments

(linux only) Keep track of command's arguments as seen by the ps (1) command, and mirror them in rlwrap's own argumentsThis is mainly useful for commands that overwrite command-line password arguments that would be exposed by rlwrap without this option.

-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

-W, --polling

EXPERIMENTAL: Wake up every timeout millisecs, where timeout is the same as for the -w (--wait-before-prompt) option, 40 ms by default. This is used to sense the slave's interrupt character and ISIG flag and to adjust stdin's terminal settings accordingly, even before you press a key. Try this option e.g. when CTRL-C acts differently on command with, and without, rlwrap.

-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 multi-line editing (using .scm as filename extension) and don't consider single quotes as quotes (so that the parentheses in e.g. (print 'q) match): rlwrap -pBlue -m -M .scm -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 -pYellow -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" orin "raw" mode. In cooked mode the terminal will wait until you pressthe ENTER key before handing the entire line to the program, in rawmode every key you press is handed down immediately. In cooked modeyou generally can use the backspace key, but not the arrow keys, toedit your input. Most simple console commands use cooked mode wheneverthey want whole input lines, and raw mode when they want singlekeypresses. More sophisticated commands tend to use raw mode all thetime; they may sometimes be rlwrappable with the -a (and -N) options.

When you rlwrap command, rlwrap will run it ain a separate session, with its own "pseudo-terminal" (pty),and monitor this pty to see whether the pty is in raw mode or incooked mode. In the first case, rlwrap will copy all inputand output directly between command and your terminal ("directmode"). 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 (andread) in "chunks". Not all chunks will end with a newline, and we needto distinguish their last lines from real prompts, especially if wewant to re-write ("cook") prompts. rlwrap solves this (almost)by waiting a little, to see if there is more to come. "A little" is 40msec by default, but this can be changed with the -w option.Normally rlwrap writes the suspected prompt as soon as it isreceived, replacing it with a "cooked" version afer the waittime. This is called "impatient" mode. If you don't like the flashingeffect (which can become annoying when you "cook" the prompt heavily) youcan 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 willperform 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 thenprinted (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 actionhas 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 -moption is set). This actionhas a readline command name rlwrap-call-editor

These special keys were chosen for no other reason than that they are not currently bound to anyreadline action. If you don't like them, (or your window manager swallows them) theycan be re-bound more sensibly by including lines like thefollowing 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

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="vi +%L"    export RLWRAP_EDITOR="vim '+call cursor(%L,%C)'"

The first example above is the default; %L and %C are replaced byline and column numbers corresponding to the cursor position inrlwrap's edit buffer

RLWRAP_FILTERDIR:: Any executable along your PATH can in theorybe used as a filter, but because filters have to follow a rather outlandishprotocol (cf. RlwrapFilter (3)) it is a good idea to keep themseparate. 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 handleTSTP (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 beinterrupted by a CTRL-C from the terminal (although rlwrap will not survive this)

If command changes the keystrokes that send a particular signalfrom the keyboard (like emacs, which uses CTRL-G instead of CTRL-C)rlwrap will do the same (but only after the next keystroke - use the --polling option to make rlwrap more transparent in this respect)

When command is killed by a signal, rlwrap will clean up,reset its signal handlers an then commit suicide by sending the samesignal 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 makesense, so rlwrap will ignore all options and simplyexecute command. When stdout (or stderr) is not a terminal, rlwrap will re-openit to /dev/tty (the users terminal) after it has startedcommand, so that command's output is redirected asexpected, but keyboard input and rlwrap error messages are still visible.

The upshot of this is that rlwrap command behaves more orless like command when redirecting.

EXIT STATUS

non-zero after a rlwrap error, or else command's exitstatus. 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'shome directory if this variable is not set. This will quickly become messy if you use rlwrap for many different commands.

$RLWRAP_HOME/command_history, ~/.command_history

History for command

$RLWRAP_HOME/command_completions, ~/.command_completions

Per-user completion word list for command. rlwrap neverwrites into this list, but one can combine -l and -foptions to to simulate the effect of a -r option that worksacross invocations.

/usr/share/rlwrap/completions/command

System-wide completion word list for command. This file is onlyconsulted if the per-user completion word list is not found.

$INPUTRC, ~/.inputrc

Individual readline initialisation file (See readline (3) forits format). rlwrap sets its application name tocommand (this can be overridden by 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 aboutcommand's internal state, which makes context-sensitive completionimpossible. Using the readline library from within command isstill the best option.

Also, because "it takes two to tango" there is no way for rlwrapto synchronise its internal state with command, resulting in anumber of subtle race conditions, where e.g. command may havechanged the state of its terminal before rlwrap has readcommand output that was written before the state change. Youwill notice these races especially on a busy machine and with heavy"cooking" and filtering, when suddenly (and unpredictably) promtps orcommand output are garbled or incorrectly coloured.
rlwrap can try, but often fails to, handle prompts that containcontrol characters. A flter may be used to clean up the prompt.

VERSION

This manpage documents rlwrap version 0.42

AUTHORS

The readline library (written by Brian Fox and Chet Ramey) does all the hard workbehind the scenes, the pty-handling code has been taken practicallyunchanged from rxvt-2.7.10 (currently maintained by Geoff C. Wing),and completion word lists are managed by Damian Ivereigh's libredblacklibrary. The few remaining lines of code were written by Hans Lub(hanslub42AATTgmail.com).

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
DIRECT MODE AND READLINE MODE
PATIENT AND IMPATIENT MODE
COOKING PROMPTS
SPECIAL KEYS
ENVIRONMENT
SIGNALS
REDIRECTION
EXIT STATUS
FILES
BUGS and LIMITATIONS
VERSION
AUTHORS
SEE ALSO

This document was created byman2html,using the manual pages.