"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/rlwrap.man.in" between
rlwrap-0.45.tar.gz and rlwrap-0.45.1.tar.gz

About: rlwrap is a "readline wrapper" allowing the editing of keyboard input for any command.

rlwrap.man.in  (rlwrap-0.45):rlwrap.man.in  (rlwrap-0.45.1)
.TH rlwrap 1 "Fanuary 5, 2021" .TH rlwrap 1 "Fanuary 5, 2021"
.SH NAME .SH NAME
rlwrap \- readline wrapper rlwrap \- readline wrapper
.de OP .de OP
.ie \\n(.$-1 .RI "[\ \fB\\$1\fP " "\\$2" "\ ]" .ie \\n(.$-1 .RI "[\ \fB\\$1\fP " "\\$2" "\ ]"
.el .RB "[\ " "\\$1" "\ ]" .el .RB "[\ " "\\$1" "\ ]"
.. ..
.de OB
.ie '@HAVE_LONG_OPTS@'yes' .B \\$1[\\$3], \\$2[=\\$3]
.el .B \\$1 \\$3
..
.de OA .de OA
.ie '@HAVE_OPTIONAL_ARGS@'yes' The argument is optional; if given, it has to \ .ie '@HAVE_OPTIONAL_ARGS@'yes' The argument is optional; if given, it has to \
directly follow the option without an directly follow a short option without an intervening space (\fB\\$1\\$3\fP) and
intervening space. a long option with an equals sign (\fB\\$2=\\$3\fP).
.el On this system, you \fBmust\fP give a (dummy) argument. .el On this system, optional arguments don't work, so, if necessary, use a (dum
my) argument (\fB\\$1 \\$4\fP).
.. ..
.de OL .de OL
.ie '@HAVE_LONG_OPTS@'yes' .B \\$1, \\$2 \\$3 .ie '@HAVE_LONG_OPTS@'yes' .B \\$1, \\$2 \\$3
.el .B \\$1 \\$3 .el .B \\$1 \\$3
.. ..
.SH SYNOPSIS .SH SYNOPSIS
.B rlwrap .B rlwrap
.I [rlwrap\-options] .I [rlwrap\-options]
.I command \.\.\. .I command \.\.\.
.SH DESCRIPTION .SH DESCRIPTION
\fBrlwrap\fP runs the specified \fIcommand\fP, intercepting user input \fBrlwrap\fP runs the specified \fIcommand\fP, intercepting user input
in order to provide \fBreadline\fP's line editing, persistent history in order to provide \fBreadline\fP's line editing, persistent history
and completion. and completion.
\fBrlwrap\fP tries (and \fIalmost\fP succeeds) to be completely transparent \- y ou \fBrlwrap\fP tries (and \fIalmost\fP succeeds) to be completely transparent \- y ou
skipping to change at line 41 skipping to change at line 48
sending signals from and to \fIcommand\fP, and when \fIcommand\fP sending signals from and to \fIcommand\fP, and when \fIcommand\fP
manipulates its terminal settings, working directory or (with the \fB-U\fP optio n) command line. manipulates its terminal settings, working directory or (with the \fB-U\fP optio n) command line.
There are many options to add (programmable) completion, handle There are many options to add (programmable) completion, handle
multi\-line input, colour and re\-write prompts. If you don't need 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, them (and you probably don't), you can skip the rest of this manpage,
although some of those options could make your command line quite a bit more although some of those options could make your command line quite a bit more
comfortable... comfortable...
.SH OPTIONS .SH OPTIONS
.TP .TP
.OL \-a \-\-always\-readline [\fIpassword_prompt\fP] .OB \-a \-\-always\-readline \fIpassword_prompt\fP
Always remain in "readline mode", regardless of \fIcommand\fP's terminal setting Always remain in "readline mode" (see below), regardless of \fIcommand\fP's term
s. inal settings.
If \fBrlwrap\fP "does nothing" this is the option to use, as \fIcommand\fP is ap parently already If \fBrlwrap\fP "does nothing" this is the option to use, as \fIcommand\fP is ap parently already
doing its own line editing. doing its own line editing.
\fBNB\fP: With this \fBNB\fP: With this
option, rlwrap will echo (and save) passwords, unless you give \fIcommand\fP's option, rlwrap will echo (and save) passwords, unless you give \fIcommand\fP's
password prompt as an argument. password prompt as an argument.
.OA \-a \-\-always\-readline Password:
.OA \-a \-\-always\-readline Password: brumbleslurgh
The \fB\-N\fP (\fB\-\-no\-children\fP) option can be used to avoid wrapping The \fB\-N\fP (\fB\-\-no\-children\fP) option can be used to avoid wrapping
pagers and editors called from \fIcommand\fP; this should make them much more us able pagers and editors called from \fIcommand\fP; this should make them much more us able
.TP .TP
.OL \-A \-\-ansi\-colour\-aware [\fI!\fP] .OB \-A \-\-ansi\-colour\-aware \fI!\fP
Prompts that use colour, or use other CSI codes to e.g. set window titles or Prompts that use colour, or use other CSI codes to e.g. set window titles or
enable bracketed-paste will confuse rlwrap, especially at the end of enable bracketed-paste will confuse rlwrap, especially at the end of
long input lines. This option will usually (but by no means always) make rlwrap better behaved in such long input lines. This option will usually (but by no means always) make rlwrap better behaved in such
cases. cases.
Giving '!' as an argument will make \fBrlwrap\fP remove all color codes Giving '!' as an argument will make \fBrlwrap\fP remove all color codes
from the prompt. from the prompt.
.OA \-A \-\-ansi\-colour\-aware ! ''
.TP .TP
.OL \-b \-\-break\-chars \fIlist_of_characters\fP .OL \-b \-\-break\-chars \fIlist_of_characters\fP
Consider the specified characters word\-breaking (whitespace is Consider the specified characters word\-breaking (whitespace is
always word\-breaking). This determines what is considered a "word", always word\-breaking). This determines what is considered a "word",
both when completing and when building a completion word list from both when completing and when building a completion word list from
files specified by \fB\-f\fP options following (not preceding!) it. files specified by \fB\-f\fP options following (not preceding!) it.
Default list (){}[],'+\-=&^%$#@";|\\ Unless \-c is specified, \" "quote to keep emacs happy Default list (){}[],'+\-=&^%$#@";|\\ Unless \-c is specified, \" "quote to keep emacs happy
/ and \. (period) are included in the default list. / and \. (period) are included in the default list.
.TP .TP
skipping to change at line 143 skipping to change at line 153
.OL \-I \-\-pass\-sigint\-as\-sigterm .OL \-I \-\-pass\-sigint\-as\-sigterm
Send a TERM signal to \fIcommand\fP when an INT is received (e.g. when you Send a TERM signal to \fIcommand\fP when an INT is received (e.g. when you
press CTRL\-C). press CTRL\-C).
.TP .TP
.OL \-l \-\-logfile \fIfile\fP .OL \-l \-\-logfile \fIfile\fP
When in readline mode, append \fIcommand\fP's output (including echo'ed user inp ut) to When in readline mode, append \fIcommand\fP's output (including echo'ed user inp ut) to
\fIfile\fP (creating \fIfile\fP when it doesn't exist). \fIfile\fP (creating \fIfile\fP when it doesn't exist).
.TP .TP
.OL \-m \-\-multi\-line [\fInewline_substitute\fP] .OB \-m \-\-multi\-line \fInewline_substitute\fP
Enable multi\-line input using a "newline substitute" character Enable multi\-line input using a "newline substitute" character
sequence (" \\ ", [space\-backslash\-space] by default). Newline sequence (" \\ ", [space\-backslash\-space] by default). Newline
substitutes are translated to newlines before sending the input to substitutes are translated to newlines before sending the input to
\fIcommand\fP. With this option, you can call an external editor \fIcommand\fP. With this option, you can call an external editor
$RLWRAP_EDITOR on the (expanded) current input with the $RLWRAP_EDITOR on the (expanded) current input with the
\fIrlwrap_call_editor\fP key (CTRL\-^ by default) \fIrlwrap_call_editor\fP key (CTRL\-^ by default)
.OA \-m \-\-multi\-line ';;' .OA \-m \-\-multi\-line ';;' "' \\\\ '"
.TP .TP
.OL \-M \-\-multi\-line\-ext \fI.ext\fP .OL \-M \-\-multi\-line\-ext \fI.ext\fP
Call multi-line-editor on temporary files with filename extension \fI.ext\fP (us eful for e.g. automatic syntax colouring) Call multi-line-editor on temporary files with filename extension \fI.ext\fP (us eful for e.g. automatic syntax colouring)
.TP .TP
.OL \-n \-\-no\-warnings .OL \-n \-\-no\-warnings
Don't print warnings. Don't print warnings.
.TP .TP
skipping to change at line 174 skipping to change at line 184
.TP .TP
.OL \-o \-\-one\-shot .OL \-o \-\-one\-shot
Send an EOF to \fIcommand\fP after accepting the first line of input Send an EOF to \fIcommand\fP after accepting the first line of input
.TP .TP
.OL \-O \-\-only\-cook \fIregexp\fP .OL \-O \-\-only\-cook \fIregexp\fP
Only ever "cook" prompts that match \fIregexp\fP, which can be preceded by '!', meaning that \fBall\fP matching candidate prompts will be cooked Only ever "cook" prompts that match \fIregexp\fP, which can be preceded by '!', meaning that \fBall\fP matching candidate prompts will be cooked
immediately ("confident mode"). immediately ("confident mode").
.TP .TP
.OL \-p \-\-prompt\-colour [\fIcolour_name|Colour_name|colour_spec\fP] .OB \-p \-\-prompt\-colour \fIcolour\fP
Use one of the colour names \fIblack, red, green, yellow, blue, cyan, purple (=m agenta)\fP or \fIwhite\fP, or an ANSI\-conformant <colour_spec> to colour any pr ompt displayed by Use one of the colour names \fIblack, red, green, yellow, blue, cyan, purple (=m agenta)\fP or \fIwhite\fP, or an ANSI\-conformant <colour_spec> to colour any pr ompt displayed by
\fIcommand\fP. An uppercase colour name (\fIYellow\fP or \fIYELLOW\fP ) gives a bold prompt. Prompts that already contain \fIcommand\fP. An uppercase colour name (\fIYellow\fP or \fIYELLOW\fP ) gives a bold prompt. Prompts that already contain
(colour) escape sequences or one of the readline "ignore markers" (ASCII 0x01 an d 0x02) are not coloured. This option implies \-\-ansi\-colour\-aware. (colour) escape sequences or one of the readline "ignore markers" (ASCII 0x01 an d 0x02) are not coloured. This option implies \-\-ansi\-colour\-aware.
\fIcolour spec\fP has the form You can also use a \fIcolour spec\fP of the form
<attr>;<fg>[;<bg>] Example: \-p'1;31' will give a bold red prompt on the <attr>;<fg>[;<bg>], for example \-p'1;31' will give a bold red prompt on the
current background (this is the default when no argument is current background (this is the default when no argument is
given). Google for 'ANSI color' to learn more about colour codes. given). Google for 'ANSI color' to learn more about colour codes.
.OA \-p \-\-prompt\-colour '0;31' .OA \-p \-\-prompt\-colour 'Red' 'Red'
.TP .TP
.OL \-P \-\-pre\-given \fItext\fP .OL \-P \-\-pre\-given \fItext\fP
Start \fBrlwrap\fP with \fItext\fP in its edit buffer (this will automatically Start \fBrlwrap\fP with \fItext\fP in its edit buffer (this will automatically
set the \-\-always\-readline option). set the \-\-always\-readline option).
.TP .TP
.OL \-q \-\-quote\-characters \fIlist_of_characters\fP .OL \-q \-\-quote\-characters \fIlist_of_characters\fP
Assume that the given characters act as quotes, e.g. when matching 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 parentheses. Take care to escape the list properly for your shell (example: \-q "\\"'", which happens to be the
skipping to change at line 298 skipping to change at line 308
.TP .TP
In a shell script, use \fBrlwrap\fP in 'one\-shot' mode as a replacement for \fB read\fP In a shell script, use \fBrlwrap\fP in 'one\-shot' mode as a replacement for \fB read\fP
.B order=$(rlwrap\ -pYellow\ \-S\ 'Your pizza?\ '\ \-H past_orders\ \-P\ Margher ita\ \-o\ cat) .B order=$(rlwrap\ -pYellow\ \-S\ 'Your pizza?\ '\ \-H past_orders\ \-P\ Margher ita\ \-o\ cat)
.SH DIRECT MODE AND READLINE MODE .SH DIRECT MODE AND READLINE MODE
Most simple console commands put your terminal either in "cooked" or Most simple console commands put your terminal either in "cooked" or
in "raw" mode. In cooked mode the terminal will wait until you press 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 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 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 you generally can use the backspace key, but not the arrow keys, to
edit your input. Most simple console commands use cooked mode whenever edit your input.
they want whole input lines, and raw mode when they want single
keypresses. More sophisticated commands tend to use raw mode all the When you \fBrlwrap\fP \fIcommand\fP, \fBrlwrap\fP will run it a in a
time; they may sometimes be rlwrappable with the \fB\-a\fP (and \fB\-N\fP) optio separate session, under its own (controlling) "pseudo\-terminal"
ns. (pty), and monitor this pty to see whether it is in raw, or in cooked
mode. In the first case, \fBrlwrap\fP will copy all input and output
When you \fBrlwrap\fP \fIcommand\fP, \fBrlwrap\fP will run it a directly between \fIcommand\fP and your terminal ("direct mode"). In
in a separate session, under its own (controlling) "pseudo\-terminal" (pty), the second case, \fBrlwrap\fP will use readline to edit your input
and monitor this pty to see whether it is in raw, or in ("readline mode"), and monitor \fBcommand\fP's output \- every last
cooked mode. In the first case, \fBrlwrap\fP will copy all input line that doesn't end with a newline is a potential prompt. How it
and output directly between \fIcommand\fP and your terminal ("direct handles such a candidate prompt depends on its being in "patient" or
mode"). In the second case, \fBrlwrap\fP will use readline to edit your input (" "impatient" mode, see below.
readline mode"), and monitor
\fBcommand\fP's output \- every last line that doesn't end with a newline is a p Simple console commands use cooked mode whenever they want whole input
otential prompt. How it handles such a candidate prompt depends on its being in lines, and raw mode when they want single keypresses. Those are the
"patient" or "impatient" mode: progams for which \fBrlwrap\fP is most useful. More sophisticated
commands have their own line editor and hence use raw mode all the
time. With those commands, \fBrlwrap\fP will appear to "do nothing".
Therefore, if \fBrlwrap\fP is in direct mode when the user presses
ENTER for the first time it will give a warning that it needs
\fB\-\-always\-readline\fP to do anything at all (warnings can be
suppressed with the \fB\-n\fP option)
.SH PATIENT, IMPATIENT AND CONFIDENT MODE .SH PATIENT, IMPATIENT AND CONFIDENT MODE
If \fIcommand\fP writes a lot of output, it tends to be written (and If \fIcommand\fP 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 read) in "chunks". Not all chunks will end with a newline, and we need
to distinguish their last lines ("candidate prompts") from real prompts, especia lly if we to distinguish their last lines ("candidate prompts") from real prompts, especia lly if we
want to re\-write ("cook") prompts. \fBrlwrap\fP solves this (almost) want to re\-write ("cook") prompts. \fBrlwrap\fP solves this (almost)
by waiting a little, to see if there is more to come. "A little" is 40 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 \fB\-w\fP option. msec by default, but this can be changed with the \fB\-w\fP option.
Normally \fBrlwrap\fP writes the candidate prompt as soon as it is Normally \fBrlwrap\fP writes the candidate prompt as soon as it is
received, replacing it with a "cooked" version after the wait received, replacing it with a "cooked" version after the wait
skipping to change at line 365 skipping to change at line 385
.TP .TP
.B (Not currently bound) .B (Not currently bound)
\fIrlwrap-hotkey-without-history\fP acts like \fIrlwrap-hotkey\fP, but the histo ry (which can be quite large) is not passed to the filter. This is more efficien t if the filter wouldn't do anything useful with the history anyway. \fIrlwrap-hotkey-without-history\fP acts like \fIrlwrap-hotkey\fP, but the histo ry (which can be quite large) is not passed to the filter. This is more efficien t if the filter wouldn't do anything useful with the history anyway.
.PP .PP
The special keys were chosen for no other reason than that they are not currentl y bound to any The special keys were chosen for no other reason than that they are not currentl y bound to any
readline action. If you don't like them, (or your window manager swallows them) they (and the other 4 commands) readline action. If you don't like them, (or your window manager swallows them) they (and the other 4 commands)
can be re\-bound more sensibly by including lines like the can be re\-bound more sensibly by including lines like the
following in your \fB~/.inputrc\fP: following in your \fB~/.inputrc\fP:
.PP .PP
.nf .nf
"\eM\-\eC\-m" : rlwrap\-accept\-line\-and\-forget # ESC\-ENTER to acc "\eM\-\eC\-m": rlwrap\-accept\-line\-and\-forget # ESC\-ENTER to acc
ept but keep out of history ept but keep out of history
"\eC\-x" : rlwrap\-call\-editor # CTRL\-x e to edit (mu "\eC\-x": rlwrap\-call\-editor # CTRL\-x e to edit (mu
lti-line) input in editor of your choice lti-line) input in editor of your choice
$if erl # (only) for the Erlang she ll: $if erl # (only) for the Erlang she ll:
"\eC\-g": rlwrap\-direct\-keypress # pass CTRL\-g directly to enter 'user switch' command "\eC\-g": rlwrap\-direct\-keypress # pass CTRL\-g directly to enter 'user switch' command
$endif $endif
"\eC\-t" : rlwrap\-direct\-prefix # make it possible to d "\eC\-t": rlwrap\-direct\-prefix # make it possible to d
efine direct keypresses that start with CTRL\-t ... efine direct keypresses that start with CTRL\-t ...
"\eC\-tx" : rlwrap\-direct\-keypress # ... in that case: pas "\eC\-tx": rlwrap\-direct\-keypress # ... in that case: pas
s CTRL\-t + x directly. s CTRL\-t + x directly.
"\eC\-y" : rlwrap\-hotkey\-without\-history # CTRL\-y to filter in "\eC\-y": rlwrap\-hotkey\-without\-history # CTRL\-y to filter in
put line (and e.g. insert X selection) put line (and e.g. insert X selection)
.fi .fi
.PP .PP
cf. the \fBreadline(3)\fP manpage. (NB: take care to not use keys that are alrea dy caught by your window manager, or by the terminal driver, like CTRL+S, as \fB rlwrap\fP will never see those) cf. the \fBreadline(3)\fP manpage. (NB: take care to not use keys that are alrea dy caught by your window manager, or by the terminal driver, like CTRL+S, as \fB rlwrap\fP will never see those)
.SH ENVIRONMENT .SH ENVIRONMENT
.TP .TP
\fBRLWRAP_HOME\fP: \fBRLWRAP_HOME\fP:
directory in which the history and completion files are kept. directory in which the history and completion files are kept.
.TP .TP
\fBRLWRAP_EDITOR\fP (or else \fBEDITOR\fP, or else \fBVISUAL\fP): \fBRLWRAP_EDITOR\fP (or else \fBEDITOR\fP, or else \fBVISUAL\fP):
editor to use for multi\-line input (and rlwrap-edit-history). Example: editor to use for multi\-line input (and rlwrap-edit-history). Example:
 End of changes. 16 change blocks. 
40 lines changed or deleted 58 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)