1RlwrapFilter(3pm) User Contributed Perl Documentation RlwrapFilter(3pm)
2
6 RlwrapFilter - Perl class for rlwrap filters
7
9 use lib $ENV{RLWRAP_FILTERDIR};
10 use RlwrapFilter;
11 $filter = new RlwrapFilter;
13 $filter -> output_handler(sub {s/apple/orange/; $_}); # re-write output
15 $filter -> prompt_handler(\&pimp_the_prompt); # change prompt
16 $filter -> history_handler(sub {s/with password \w+/with password ****/; $_}); # keep passwords out of history
17 $filter -> run;
19
21 rlwrap (1) (<https://github.com/hanslub42/rlwrap>) is a tiny utility
22 that sits between the user and any console command, in order to bestow
23 readline capabilities (line editing, history recall) to commands that
24 don't have them.
25 Since version 0.32, rlwrap can use filters to script almost every
27 aspect of rlwrap's interaction with the user: changing the history, re-
28 writing output and input, calling a pager or computing completion word
29 lists from the current input.
30 Filters can be combined in a pipeline using the special pipeline
32 filter.
33 RlwrapFilter makes it very simple to write rlwrap filters in perl. A
35 filter only needs to instantiate a RlwrapFilter object, change a few of
36 its default handlers and then call its 'run' method.
37 There is also a Python 3 module rlwrapfilter.py, distributed together
39 with rlwrap, that provides more or less the same API as its perl
40 counterpart.
41
43 CONSTRUCTOR
44 $f = new RlwrapFilter
45 $f = RlwrapFilter -> new(prompt_handler => sub {"Hi! > "},
46 minimal_rlwrap_version => "0.35", ...)
47 Return a new RlwrapFilter object.
48 SETTING/GETTING HANDLERS
50 Handlers are user-defined callbacks that specify one or more of an
51 RlwrapFilter object's handler methods (handle_input, handle_prompt)
52 They get called from the 'run' method in response to a message sent
53 from rlwrap. Messages consist of a tag indicating which handler should
54 be called (e.g. TAG_INPUT, TAG_HISTORY) and the message text. Usually,
55 a filter overrides only one or at most two methods.
56 CALLING CONVENTIONS
58 In many cases (e.g. TAG_INPUT, TAG_OUTPUT, TAG_PROMPT) the message text
59 is a simple string. Their handlers are called with the message text
60 (i.e. the un-filtered input, output, prompt) as their only argument.
61 For convenience, $_ is set to the same value. They should return the
62 re-written message text.
63 Some handlers (those for TAG_COMPLETION and TAG_HOTKEY) are a little
65 more complex: their message text (accessible via $_) is a tab-separated
66 list of fields; they get called with multiple arguments and are
67 evaluated in list context.
68 The message handlers are called in a fixed cyclic order: prompt,
70 completion, history, input, echo, output, prompt, ... etc ad infinitum.
71 Rlwrap may always skip a handler when in direct mode; on the other
72 hand, completion and output handlers may get called more than once in
73 succession. If a handler is left undefined, the result is as if the
74 message text were returned unaltered (in fact, rlwrap knows when this
75 is the case and won't even bother to send the message)
76 It is important to note that the filter, and hence all its handlers,
78 are bypassed when command is in direct mode, i.e. when it asks for
79 single keystrokes (and also, for security reasons, when it doesn't
80 echo, e.g. when asking for a password). If you don't want this to
81 happen, use rlwrap -a to force rlwrap to remain in readline mode and to
82 apply the filter to all of command's in- and output. This will make
83 editors and pagers (which respond to single keystrokes) unusable,
84 unless you use rlwrap's -N option (linux only)
85 The getters/setters for the respective handlers are listed below:
87 $handler = $f -> prompt_handler, $f -> prompt_handler(\&handler)
89 The prompt handler re-writes prompts and gets called when rlwrap
90 decides it is time to "cook" the prompt, by default some 40 ms
91 after the last output has arrived. Of course, rlwrap cannot read
92 the mind of command, so what looks like a prompt to rlwrap may
93 actually be the beginning of an output line that took command a
94 little longer to formulate. If this is a problem, specify a longer
95 "cooking" time with rlwrap's -w option, use the
96 prompts_are_never_empty method or "reject" the prompt (cf. the
97 prompt_rejected method)
98 $handler = $f -> completion_handler, $f ->
100 completion_handler(\&handler)
101 The completion handler gets called with three arguments: the entire
102 input line, the prefix (partial word to complete), and rlwrap's own
103 completion list. It should return a (possibly revised) list of
104 completions. As an example, suppose the user has typed "She played
105 for A<TAB>". The handler will be called like this:
106 myhandler("She played for A", "A", "Arsenal", "Arendal", "Anderlecht")
108 it could then return a list of stronger clubs: ("Ajax", "AZ67",
110 "Arnhem")
111 $handler = $f -> history_handler, $f -> history_handler(\&handler)
113 Every input line is submitted to this handler, the return value is
114 put in rlwrap's history. Returning an empty or undefined value will
115 keep the input line out of the history.
116 $handler = $f -> hotkey_handler, $f -> hotkey_handler(\&handler)
118 If, while editing an input line, the user presses a key that is
119 bound to "rlwrap_hotkey" in .inputrc, the handler is called with
120 five arguments: the hotkey, the prefix (i.e. the part of the
121 current input line before the cursor), the remaining part of the
122 input line (postfix), the history as one string ("line 1\nline
123 2\n...line N", and the history position. It has to return a similar
124 list, except that the first element will be printed in the "echo
125 area" if it is changed from its original value.
126 Example: if the current input line is "pea soup" (with the cursor
128 on the space), and the user presses CTRL+P, which happens to be
129 bound to "rlwrap-hotkey" in .inputrc, the handler is called like
130 this:
131 my_handler("\0x10", "pea", " soup", "tomato soup\nasparagus..", 12) # 16 = CTRL-P
133 If you prefer peanut soup, the handler should return
135 ("Mmmm!", "peanut", " soup", "asparagus..", 11)
137 after which the input line will be "peanut soup" (with the cursor
139 again on the space), the echo area will display "Mmmm!", and any
140 reference to inferior soups will have been purged from the history.
141 If the returned input line ends with a newline rlwrap will
143 immediately accept the result.
144 $handler = $f -> input_handler, $f -> input_handler(\&handler)
146 Every input line (which may consist of multiple \n-separated lines,
147 when using bracketed paste) is submitted to this handler, The
148 handler's return value is written to command's pty (pseudo-
149 terminal).
150 $handler = $f -> echo_handler, $f -> echo_handler(\&handler)
152 The first line of output that is read back from command's pty is
153 the echo'ed input line. If your input handler alters the input
154 line, it is the altered input that will be echo'ed back. If you
155 don't want to confuse the user, use an echo handler that returns
156 your original input.
157 If you use rlwrap in --multi-line mode, additional echo lines will
159 have to be handled by the output handler
160 $handler = $f -> output_handler, $f -> output_handler(\&handler)
162 All command output after the echo line is submitted to the output
163 handler (including newlines). This handler may get called many
164 times in succession, dependent on the size of command's write()
165 calls, and the whims of your system's scheduler. Therefore your
166 handler should be prepared to rewrite your output in "chunks",
167 where you even don't have the guarantee that the chunks contain
168 entire unbroken lines.
169 If you want to handle command's entire output in one go, you can
171 specify an output handler that returns an empty string, and then
172 use $filter -> cumulative_output in your prompt handler to send the
173 re-written output "out-of-band" just before the prompt:
174 $filter -> output_handler(sub {""});
176 $filter -> prompt_handler(
178 sub{ $filter -> send_output_oob(mysub($filter -> cumulative_output));
179 "Hi there > "
180 });
181 Note that when rlwrap is run in --multi-line mode the echo handler
183 will still only handle the first echo line. The remainder will
184 generally be echoed back preceded by a continuation prompt; it is
185 up to the output handler what to do with it.
186 $handler = $f -> signal_handler, $f -> signal_handler(\&handler)
188 As rlwrap is transparent to signals, signals get passed on to
189 command. This handler gets called (as handler($signo)) for signals
190 SIGHUP, SIGINT, SIGQUIT, SIGTERM, SIGCONT, SIGUSR1, SIGUSR2, and
191 SIGWINCH, before the signal is delivered. It receives (and should
192 return) $signo as a string. The returned signal is delivered to
193 command; return "0" to ignore the signal altogether. Output can be
194 written out-of-band (to rlwrap) or cloak_and_dagger (to command,
195 see below)
196 $handler = $f -> message_handler, $f -> message_handler(\&handler)
198 This handler gets called (as handler($message, $tag)) for every
199 incoming message, and every tag (including out-of-band tags),
200 before all other handlers. Its return value is ignored, but it may
201 be useful for logging and debugging purposes. The $tag is an
202 integer that can be converted to a tag name by the 'tag2name'
203 method
204 OTHER METHODS
206 $f -> help_text("Usage...")
207 Set the help text for this filter. It will be displayed by rlwrap
208 -z <filter>. The second line of the help text is used by "rlwrap -z
209 listing"; it should be a short description of what the filter does.
210 $f -> minimal_rlwrap_version("x.yy")
212 Die unless rlwrap is version x.yy or newer
213 $dir = $f -> cwd
215 return the name of command's current working directory. This uses
216 the /proc filesystem, and may only work on newer linux systems (on
217 older linux and on Solaris, it will return something like
218 "/proc/12345/cwd", useful to find the contents of command's working
219 directory, but not its name)
220 $text = $f -> cumulative_output
222 return the current cumulative output. All (untreated) output gets
223 appended to the cumulative output after the output_handler has been
224 called. The cumulative output starts with a fresh slate with every
225 OUTPUT message that directly follows an INPUT message (ignoring
226 out-of-band messages and rejected prompts)
227 When necessary (i.e. when rlwrap is in "impatient mode") the prompt
229 is removed from $filter->cumulative_output by the time the prompt
230 handler is called.
231 $tag = $f -> previous_tag
233 The tag of the last preceding in-band message. A tag is an integer
234 between 0 and 255, its name can be found with the following method:
235 $name = $f -> tag2name($tag)
237 Convert the tag (an integer) to its name (e.g. "TAG_PROMPT")
238 $name = $f -> name2tag($tag)
240 Convert a valid tag name like "TAG_PROMPT" to a tag (an integer)
241 $f -> send_output_oob($text)
243 Make rlwrap display $text. $text is sent "out-of-band" : rlwrap
244 will not see it until just after it has sent the next message to
245 the filter
246 $f -> send_ignore_oob($text)
248 Send an out-of-band TAG_IGNORE message to rlwrap. rlwrap will
249 silently discard it, but it can be useful when debugging filters
250 $f -> tweak_readline_oob($readline_function, @parameters)
252 Send a specially formatted out-of-band message in order to tweak
253 readline (i.e. to make rlwrap call a readline function or set a
254 readline variable). See the GNU Readline documentation for details.
255 At this moment, the following tweaks are recognised:
257 $filter -> tweak_readline_oob("rl_variable_bind", $rl_variable_name, $value);
259 # ... only for bindable readline variables like those in .inputrc
260 $filter -> tweak_readline_oob("rl_completer_word_break_characters", $chars);
261 $filter -> tweak_readline_oob("rl_completer_quote_characters", $chars);
262 $filter -> tweak_readline_oob("rl_filename_completion_desired", "0" or "1");
263 The parameters should not contain "::" (two consecutive colons).
265 This method can be called at any moment, even before $filter -> run
266 $f -> add_to_completion_list(@words)
268 $f -> remove_from_completion_list(@words)
269 Permanently add or remove the words in @words to/from rlwrap's
270 completion list.
271 $f -> cloak_and_dagger($question, $prompt, $timeout);
273 Send $question to command's input and read back everything that
274 comes back until $prompt is seen at "end-of-chunk", or no new
275 chunks arrive for $timeout seconds, whichever comes first. Return
276 the response (without the final $prompt). rlwrap remains
277 completely unaware of this conversation.
278 $f -> cloak_and_dagger_verbose($verbosity)
280 If $verbosity evaluates to a true value, make rlwrap print all
281 questions sent to command by the "cloak_and_dagger" method, and
282 command's responses. By default, $verbosity = 0; setting it to 1
283 will mess up the screen but greatly facilitate the (otherwise
284 rather tricky) use of "cloak_and_dagger"
285 $self -> prompt_rejected
287 A special text ("_THIS_CANNOT_BE_A_PROMPT_") to be returned by a
288 prompt handler to "reject" the prompt. This will make rlwrap skip
289 cooking the prompt. $self->previous_tag and
290 $self->cumulative_output will not be touched.
291 $text = $f -> prompts_are_never_empty($val)
293 If $val evaluates to a true value, automatically reject empty
294 prompts.
295 $f -> command_line
297 In scalar context: the rlwrapped command and its arguments as a
298 string ("command -v blah") in list context: the same as a list
299 ("command", "-v", "blah")
300 $f -> running_under_rlwrap
302 Whether the filter is run by rlwrap, or directly from the command
303 line
304 $f -> run
306 Start an event loop that reads rlwrap's messages from the input
307 pipe, calls the appropriate handlers and writes the result to the
308 output pipe. This method never returns.
309
311 rlwrap communicates with a filter through messages consisting of a tag
312 byte (TAG_OUTPUT, TAG_PROMPT etc. - to inform the filter of what is
313 being sent), an unsigned 32-bit integer containing the length of the
314 message, the message text and an extra newline. For every message sent,
315 rlwrap expects, and waits for an answer message with the same tag.
316 Sending back a different (in-band) tag is an error and instantly kills
317 rlwrap, though filters may precede their answer message with "out-of-
318 band" messages to output text (TAG_OUTPUT_OUT_OF_BAND), report errors
319 (TAG_ERROR), and to manipulate the completion word list
320 (TAG_ADD_TO_COMPLETION_LIST and TAG_REMOVE_FROM_COMPLETION_LIST) Out-
321 of-band messages are not serviced by rlwrap until right after it has
322 sent the next in-band message - the communication with the filter is
323 synchronous and driven by rlwrap.
324 Messages are received and sent via two pipes. STDIN, STDOUT and STDERR
326 are still connected to the user's terminal, and you can read and write
327 them directly, though this may mess up the screen and confuse the user
328 unless you are careful. A filter can even communicate with the
329 rlwrapped command behind rlwrap's back (cf the cloak_and_dagger()
330 method)
331 The protocol uses the following tags (tags > 128 are out-of-band)
333 TAG_INPUT 0
335 TAG_OUTPUT 1
336 TAG_HISTORY 2
337 TAG_COMPLETION 3
338 TAG_PROMPT 4
339 TAG_HOTKEY 5
340 TAG_SIGNAL 6
341 TAG_WHAT_ARE_YOUR_INTERESTS 127
343 TAG_IGNORE 251
345 TAG_ADD_TO_COMPLETION_LIST 252
346 TAG_REMOVE_FROM_COMPLETION_LIST 253
347 TAG_OUTPUT_OUT_OF_BAND 254
348 TAG_ERROR 255
349 To see how this works, you can eavesdrop on the protocol using the
351 logger filter.
352 The constants TAG_INPUT, ... are exported by the RlwrapFilter.pm
354 module.
355 TAG_WHAT_ARE_YOUR_INTERESTS is only ever used internally, to prevent
357 the exchange of messages that won't be handled by the filter anyway. It
358 will be seen by the general message handler, and therefore show up
359 (exactly once, at program start) in the output of e.g. the logger
360 filter.
361
363 As STDIN is still connected to the users teminal, one might expect the
364 filter to receive SIGINT, SIGTERM, SIGTSTP directly from the terminal
365 driver if the user presses CTRL-C, CTRL-Z etc Normally, we don't want
366 this - it would confuse rlwrap, and the user (who thinks she is talking
367 straight to the rlwapped command) probably meant those signals to be
368 sent to the command itself. For this reason the filter starts with all
369 signals blocked.
370 Filters that interact with the users terminal (e.g. to run a pager)
372 should unblock signals like SIGTERM, SIGWINCH.
373
375 The filter is started by rlwrap after command, and stays alive as long
376 as rlwrap runs. Filter methods are immediately usable. When command
377 exits, the filter stays around for a little longer in order to process
378 command's last words. As calling the cwd and cloak_and_dagger methods
379 at that time will make the filter die with an error, it may be
380 advisable to wrap those calls in eval{}
381 If a filter calls die() it will send an (out-of-band) TAG_ERROR message
383 to rlwrap before exiting. rlwrap will then report the message and exit
384 (just after its next in-band message - out-of-band messages are not
385 always processed immediately)
386 die() within an eval() sets $@ as usual.
388
390 Before calling a filter, rlwrap sets the following environment
391 variables:
392 RLWRAP_FILTERDIR directory where RlwrapFilter.pm and most filters live (set by rlwrap, can be
394 overridden by the user before calling rlwrap)
395 PATH rlwrap automatically adds $RLWRAP_FILTERDIR to the front of filter's PATH
397 RLWRAP_VERSION rlwrap version (e.g. "0.35")
399 RLWRAP_COMMAND_PID process ID of the rlwrapped command
401 RLWRAP_COMMAND_LINE command line of the rlwrapped command
403 RLWRAP_IMPATIENT whether rlwrap is in "impatient mode" (cf rlwrap (1)). In impatient mode,
405 the candidate prompt is filtered through the output handler (and displayed before
406 being overwritten by the cooked prompt).
407 RLWRAP_INPUT_PIPE_FD File descriptor of input pipe. For internal use only
409 RLWRAP_OUTPUT_PIPE_FD File descriptor of output pipe. For internal use only
411 RLWRAP_MASTER_PTY_FD File descriptor of command's pty.
413 RLWRAP_BREAK_CHARS The characters rlwrap considers word-breaking (cf. the --break-chars option in rlwrap (1))
415 RLWRAP_DEBUG The value of the --debug (-d) option given to rlwrap
417
419 While RlwrapFilter.pm makes it easy to write simple filters, debugging
420 them can be a problem. A couple of useful tricks:
421 LOGGING
423 When running a filter, the in- and outgoing messages can be logged by
424 the logger filter, using a pipeline:
425 rlwrap -z 'pipeline logger incoming : my_filter : logger outgoing' command
427 RUNNING WITHOUT rlwrap
429 When called by rlwrap, filters get their input from
430 $RLWRAP_INPUT_PIPE_FD and write their output to $RLWRAP_OUTPUT_PIPE_FD,
431 and expect and write messages consisting of a tag byte, a 32-bit length
432 and the message proper. This is not terribly useful when running a
433 filter directly from the command line (outside rlwrap), even if we set
434 the RLWRAP_*_FD ourselves.
435 Therefore, when run directly from the command line, a filter expects
437 input messages on its standard input of the form
438 TAG_PROMPT myprompt >
440 (i.a. a tag name, one space and a message followed by a newline. The
442 message will not contain the final newline) and it will respond in the
443 same way on its standard output. Of course, rlwrap can help with the
444 tedious typing of tag names:
445 rlwrap -f tagnames filter_to_be_debugged
447 Because rlwrap cannot put TABs and newlines in input lines, filters
449 will convert '\t' and '\n' into TAB and newline when run directly from
450 the command line.
451
453 rlwrap (1), readline (3)
454perl v5.32.0 2021-02-18 RlwrapFilter(3pm)