CONSTRUCTOR
$f = new RlwrapFilter
$f = RlwrapFilter -> new(prompt_handler => sub {"Hi! > "}, minimal_rlwrap_version => "0.35", ...)
Return a new RlwrapFilter object.
SETTING/GETTINGHANDLERS
Handlers are user-defined callbacks that specify one or more of an RlwrapFilter object's handler methods
(handle_input, handle_prompt) They get called from the 'run' method in response to a message sent from
rlwrap. Messages consist of a tag indicating which handler should be called (e.g. TAG_INPUT,
TAG_HISTORY) and the message text. Usually, a filter overrides only one or at most two methods.
CALLINGCONVENTIONS
In many cases (e.g. TAG_INPUT, TAG_OUTPUT, TAG_PROMPT) the message text is a simple string. Their
handlers are called with the message text (i.e. the un-filtered input, output, prompt) as their only
argument. For convenience, $_ is set to the same value. They should return the re-written message text.
Some handlers (those for TAG_COMPLETION and TAG_HOTKEY) are a little more complex: their message text
(accessible via $_) is a tab-separated list of fields; they get called with multiple arguments and are
evaluated in list context.
The message handlers are called in a fixed cyclic order: prompt, completion, history, input, echo,
output, prompt, ... etc ad infinitum. Rlwrap may always skip a handler when in direct mode; on the other
hand, completion and output handlers may get called more than once in succession. If a handler is left
undefined, the result is as if the message text were returned unaltered (in fact, rlwrap knows when this
is the case and won't even bother to send the message)
It is important to note that the filter, and hence all its handlers, are bypassed when command is in
direct mode, i.e. when it asks for single keystrokes (and also, for security reasons, when it doesn't
echo, e.g. when asking for a password). If you don't want this to happen, use rlwrap-a to force rlwrap
to remain in readline mode and to apply the filter to all of command's in- and output. This will make
editors and pagers (which respond to single keystrokes) unusable, unless you use rlwrap's -N option
(linux only)
The getters/setters for the respective handlers are listed below:
$handler = $f -> prompt_handler, $f -> prompt_handler(\&handler)
The prompt handler re-writes prompts and gets called when rlwrap decides it is time to "cook" the
prompt, by default some 40 ms after the last output has arrived. Of course, rlwrap cannot read the
mind of command, so what looks like a prompt to rlwrap may actually be the beginning of an output
line that took command a little longer to formulate. If this is a problem, specify a longer "cooking"
time with rlwrap's -w option, use the prompts_are_never_empty method or "reject" the prompt (cf. the
prompt_rejected method)
$handler = $f -> completion_handler, $f -> completion_handler(\&handler)
The completion handler gets called with three arguments: the entire input line, the prefix (partial
word to complete), and rlwrap's own completion list. It should return a (possibly revised) list of
completions. As an example, suppose the user has typed "She played for A<TAB>". The handler will be
called like this:
myhandler("She played for A", "A", "Arsenal", "Arendal", "Anderlecht")
it could then return a list of stronger clubs: ("Ajax", "AZ67", "Arnhem")
$handler = $f -> history_handler, $f -> history_handler(\&handler)
Every input line is submitted to this handler, the return value is put in rlwrap's history. Returning
an empty or undefined value will keep the input line out of the history.
$handler = $f -> hotkey_handler, $f -> hotkey_handler(\&handler)
If, while editing an input line, the user presses a key that is bound to "rlwrap_hotkey" in .inputrc,
the handler is called with five arguments: the hotkey, the prefix (i.e. the part of the current
input line before the cursor), the remaining part of the input line (postfix), the history as one
string ("line 1\nline 2\n...line N", and the history position. It has to return a similar list,
except that the first element will be printed in the "echo area" if it is changed from its original
value.
Example: if the current input line is "pea soup" (with the cursor on the space), and the user
presses CTRL+P, which happens to be bound to "rlwrap-hotkey" in .inputrc, the handler is called like
this:
my_handler("\0x10", "pea", " soup", "tomato soup\nasparagus..", 12) # 16 = CTRL-P
If you prefer peanut soup, the handler should return
("Mmmm!", "peanut", " soup", "asparagus..", 11)
after which the input line will be "peanut soup" (with the cursor again on the space), the echo area
will display "Mmmm!", and any reference to inferior soups will have been purged from the history.
If the returned input line ends with a newline rlwrap will immediately accept the result.
$handler = $f -> input_handler, $f -> input_handler(\&handler)
Every input line (which may consist of multiple \n-separated lines, when using bracketed paste) is
submitted to this handler, The handler's return value is written to command's pty (pseudo-terminal).
$handler = $f -> echo_handler, $f -> echo_handler(\&handler)
The first line of output that is read back from command's pty is the echo'ed input line. If your
input handler alters the input line, it is the altered input that will be echo'ed back. If you don't
want to confuse the user, use an echo handler that returns your original input.
If you use rlwrap in --multi-line mode, additional echo lines will have to be handled by the output
handler
$handler = $f -> output_handler, $f -> output_handler(\&handler)
All command output after the echo line is submitted to the output handler (including newlines). This
handler may get called many times in succession, dependent on the size of command's write() calls,
and the whims of your system's scheduler. Therefore your handler should be prepared to rewrite your
output in "chunks", where you even don't have the guarantee that the chunks contain entire unbroken
lines.
If you want to handle command's entire output in one go, you can specify an output handler that
returns an empty string, and then use $filter -> cumulative_output in your prompt handler to send the
re-written output "out-of-band" just before the prompt:
$filter -> output_handler(sub {""});
$filter -> prompt_handler(
sub{ $filter -> send_output_oob(mysub($filter -> cumulative_output));
"Hi there > "
});
Note that when rlwrap is run in --multi-line mode the echo handler will still only handle the first
echo line. The remainder will generally be echoed back preceded by a continuation prompt; it is up
to the output handler what to do with it.
$handler = $f -> signal_handler, $f -> signal_handler(\&handler)
As rlwrap is transparent to signals, signals get passed on to command. This handler gets called (as
handler($signo)) for signals SIGHUP, SIGINT, SIGQUIT, SIGTERM, SIGCONT, SIGUSR1, SIGUSR2, and
SIGWINCH, before the signal is delivered. It receives (and should return) $signo as a string. The
returned signal is delivered to command; return "0" to ignore the signal altogether. Output can be
written out-of-band (to rlwrap) or cloak_and_dagger (to command, see below)
$handler = $f -> message_handler, $f -> message_handler(\&handler)
This handler gets called (as handler($message, $tag)) for every incoming message, and every tag
(including out-of-band tags), before all other handlers. Its return value is ignored, but it may be
useful for logging and debugging purposes. The $tag is an integer that can be converted to a tag name
by the 'tag2name' method
OTHERMETHODS
$f -> help_text("Usage...")
Set the help text for this filter. It will be displayed by rlwrap -z <filter>. The second line of the
help text is used by "rlwrap -z listing"; it should be a short description of what the filter does.
$f -> minimal_rlwrap_version("x.yy")
Die unless rlwrap is version x.yy or newer
$dir = $f -> cwd
return the name of command's current working directory. This uses the /proc filesystem, and may only
work on newer linux systems (on older linux and on Solaris, it will return something like
"/proc/12345/cwd", useful to find the contents of command's working directory, but not its name)
$text = $f -> cumulative_output
return the current cumulative output. All (untreated) output gets appended to the cumulative output
after the output_handler has been called. The cumulative output starts with a fresh slate with every
OUTPUT message that directly follows an INPUT message (ignoring out-of-band messages and rejected
prompts)
When necessary (i.e. when rlwrap is in "impatient mode") the prompt is removed from
$filter->cumulative_output by the time the prompt handler is called.
$tag = $f -> previous_tag
The tag of the last preceding in-band message. A tag is an integer between 0 and 255, its name can be
found with the following method:
$name = $f -> tag2name($tag)
Convert the tag (an integer) to its name (e.g. "TAG_PROMPT")
$name = $f -> name2tag($tag)
Convert a valid tag name like "TAG_PROMPT" to a tag (an integer)
$f -> send_output_oob($text)
Make rlwrap display $text. $text is sent "out-of-band" : rlwrap will not see it until just after it
has sent the next message to the filter
$f -> send_ignore_oob($text)
Send an out-of-band TAG_IGNORE message to rlwrap. rlwrap will silently discard it, but it can be
useful when debugging filters
$f -> tweak_readline_oob($readline_function, @parameters)
Send a specially formatted out-of-band message in order to tweak readline (i.e. to make rlwrap call a
readline function or set a readline variable). See the GNU Readline documentation for details.
At this moment, the following tweaks are recognised:
$filter -> tweak_readline_oob("rl_variable_bind", $rl_variable_name, $value);
# ... only for bindable readline variables like those in .inputrc
$filter -> tweak_readline_oob("rl_completer_word_break_characters", $chars);
$filter -> tweak_readline_oob("rl_completer_quote_characters", $chars);
$filter -> tweak_readline_oob("rl_filename_completion_desired", "0" or "1");
The parameters should not contain "::" (two consecutive colons). This method can be called at any
moment, even before $filter -> run
$f -> add_to_completion_list(@words)
$f -> remove_from_completion_list(@words)
Permanently add or remove the words in @words to/from rlwrap's completion list.
$f -> cloak_and_dagger($question, $prompt, $timeout);
Send $question to command's input and read back everything that comes back until $prompt is seen at
"end-of-chunk", or no new chunks arrive for $timeout seconds, whichever comes first. Return the
response (without the final $prompt). rlwrap remains completely unaware of this conversation.
$f -> cloak_and_dagger_verbose($verbosity)
If $verbosity evaluates to a true value, make rlwrap print all questions sent to command by the
"cloak_and_dagger" method, and command's responses. By default, $verbosity = 0; setting it to 1 will
mess up the screen but greatly facilitate the (otherwise rather tricky) use of "cloak_and_dagger"
$self -> prompt_rejected
A special text ("_THIS_CANNOT_BE_A_PROMPT_") to be returned by a prompt handler to "reject" the
prompt. This will make rlwrap skip cooking the prompt. $self->previous_tag and
$self->cumulative_output will not be touched.
$text = $f -> prompts_are_never_empty($val)
If $val evaluates to a true value, automatically reject empty prompts.
$f -> command_line
In scalar context: the rlwrapped command and its arguments as a string ("command -v blah") in list
context: the same as a list ("command", "-v", "blah")
$f -> running_under_rlwrap
Whether the filter is run by rlwrap, or directly from the command line
$f -> run
Start an event loop that reads rlwrap's messages from the input pipe, calls the appropriate handlers
and writes the result to the output pipe. This method never returns.
Install Now
PNG Icons
