1RlwrapFilter(3pm)     User Contributed Perl Documentation    RlwrapFilter(3pm)
2
3
4

NAME

6       RlwrapFilter - Perl class for rlwrap filters
7

SYNOPSIS

9         use lib $ENV{RLWRAP_FILTERDIR};
10         use RlwrapFilter;
11
12         $filter = new RlwrapFilter;
13
14         $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
18         $filter -> run;
19

DESCRIPTION

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
26       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
31       Filters can be combined in a pipeline using the special pipeline
32       filter.
33
34       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
38       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

PUBLIC METHODS

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
49   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
57   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
64       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
69       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
77       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
86       The getters/setters for the respective handlers are listed below:
87
88       $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
99       $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
107                myhandler("She played for A", "A", "Arsenal", "Arendal", "Anderlecht")
108
109           it could then return a list of stronger clubs: ("Ajax", "AZ67",
110           "Arnhem")
111
112       $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
117       $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
127           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
132               my_handler("\0x10", "pea", " soup", "tomato soup\nasparagus..", 12) # 16 = CTRL-P
133
134           If you prefer peanut soup, the handler should return
135
136               ("Mmmm!", "peanut", " soup", "asparagus..", 11)
137
138           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
142           If the returned input line ends with a newline rlwrap will
143           immediately accept the result.
144
145       $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
151       $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
158           If you use rlwrap in --multi-line mode, additional echo lines will
159           have to be handled by the output handler
160
161       $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
170           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
175               $filter -> output_handler(sub {""});
176
177               $filter -> prompt_handler(
178                             sub{ $filter -> send_output_oob(mysub($filter -> cumulative_output));
179                                  "Hi there > "
180                                });
181
182           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
187       $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
197       $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
205   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
211       $f -> minimal_rlwrap_version("x.yy")
212           Die unless rlwrap is version x.yy or newer
213
214       $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
221       $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
228           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
232       $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
236       $name = $f -> tag2name($tag)
237           Convert the tag (an integer) to its name (e.g. "TAG_PROMPT")
238
239       $name = $f -> name2tag($tag)
240           Convert a valid tag name like "TAG_PROMPT" to a tag (an integer)
241
242       $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
247       $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
251       $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
256           At this moment, the following tweaks are recognised:
257
258               $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
264           The parameters should not contain "::" (two consecutive colons).
265           This method can be called at any moment, even before $filter -> run
266
267       $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
272       $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
279       $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
286       $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
292       $text = $f -> prompts_are_never_empty($val)
293           If $val evaluates to a true value, automatically reject empty
294           prompts.
295
296       $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
301       $f -> running_under_rlwrap
302           Whether the filter is run by rlwrap, or directly from the command
303           line
304
305       $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

LOW LEVEL PROTOCOL

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
325       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
332       The protocol uses the following tags (tags > 128 are out-of-band)
333
334        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
342        TAG_WHAT_ARE_YOUR_INTERESTS     127
343
344        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
350       To see how this works, you can eavesdrop on the protocol using the
351       logger filter.
352
353       The constants TAG_INPUT, ... are exported by the RlwrapFilter.pm
354       module.
355
356       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

SIGNALS

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
371       Filters that interact with the users terminal (e.g. to run a pager)
372       should unblock signals like SIGTERM, SIGWINCH.
373

FILTER LIFETIME

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
382       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
387       die() within an eval() sets $@ as usual.
388

ENVIRONMENT

390       Before calling a filter, rlwrap sets the following environment
391       variables:
392
393           RLWRAP_FILTERDIR      directory where RlwrapFilter.pm and most filters live (set by rlwrap, can be
394                                 overridden by the user before calling rlwrap)
395
396           PATH                  rlwrap automatically adds $RLWRAP_FILTERDIR to the front of filter's PATH
397
398           RLWRAP_VERSION        rlwrap version (e.g. "0.35")
399
400           RLWRAP_COMMAND_PID    process ID of the rlwrapped command
401
402           RLWRAP_COMMAND_LINE   command line of the rlwrapped command
403
404           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
408           RLWRAP_INPUT_PIPE_FD  File descriptor of input pipe. For internal use only
409
410           RLWRAP_OUTPUT_PIPE_FD File descriptor of output pipe. For internal use only
411
412           RLWRAP_MASTER_PTY_FD  File descriptor of command's pty.
413
414           RLWRAP_BREAK_CHARS    The characters rlwrap considers word-breaking (cf. the --break-chars option in rlwrap (1))
415
416           RLWRAP_DEBUG          The value of the --debug (-d) option given to rlwrap
417

DEBUGGING FILTERS

419       While RlwrapFilter.pm makes it easy to write simple filters, debugging
420       them can be a problem. A couple of useful tricks:
421
422   LOGGING
423       When running a filter, the in- and outgoing messages can be logged by
424       the logger filter, using a pipeline:
425
426         rlwrap -z 'pipeline logger incoming : my_filter : logger outgoing' command
427
428   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
436       Therefore, when run directly from the command line, a filter expects
437       input messages on its standard input of the form
438
439         TAG_PROMPT myprompt >
440
441       (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
446         rlwrap -f tagnames filter_to_be_debugged
447
448       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

SEE ALSO

453       rlwrap (1), readline (3)
454
455
456
457perl v5.32.0                      2021-02-18                 RlwrapFilter(3pm)
Impressum