Ubuntu Manpage: rlwrap - readline wrapper

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.

-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. 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.

-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 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

-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" 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 can become
       annoying 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 for no other reason than that they  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

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 (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 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 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 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 (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 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.

       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.41

AUTHORS

       The  readline  library (written by Brian Fox and 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).