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) (<http://utopia.knoware.nl/~hlub/uck/rlwrap>) is a tiny
22 utility that sits between the user and any console command, in order to
23 bestow readline capabilities (line editing, history recall) to commands
24 that 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 RlwrapFilter makes it very simple to write rlwrap filters in perl. A
32 filter only needs to instantiate a RlwrapFilter object, change a few of
33 its default handlers and then call its 'run' method.
34
36 CONSTRUCTOR
37 $f = new RlwrapFilter
38 $f = RlwrapFilter -> new(prompt_handler => sub {"Hi! > "},
39 minimal_rlwrap_version => "0.35", ...)
40 Return a new RlwrapFilter object.
41 SETTING/GETTING HANDLERS
43 Handlers are user-defined callbacks that get called from the 'run'
44 method with a message (i.e. the un-filtered input, output, prompt) as
45 their first argument. For convenience, $_ is set to the same value.
46 They should return the re-written message text. They get called in a
47 fixed cyclic order: prompt, completion, history, input, echo, output,
48 prompt, ... etc ad infinitum. Rlwrap may always skip a handler when in
49 direct mode, on the other hand, completion and output handlers may get
50 called more than once in succession. If a handler is left undefined,
51 the result is as if the message text were returned unaltered.
52 It is important to note that the filter, and hence all its handlers,
54 are bypassed when command is in direct mode, i.e. when it asks for
55 single keystrokes (and also, for security reasons, when it doesn't
56 echo, e.g. when asking for a password). If you don't want this to
57 happen, use rlwrap -a to force rlwrap to remain in readline mode and to
58 apply the filter to all of command's in- and output. This will make
59 editors and pagers (which respond to single keystrokes) unusable,
60 unless you use rlwrap's -N option (linux only)
61 The getters/setters for the respective handlers are listed below:
63 $handler = $f -> prompt_handler, $f -> prompt_handler(\&handler)
65 The prompt handler re-writes prompts and gets called when rlwrap
66 decides it is time to "cook" the prompt, by default some 40 ms
67 after the last output has arrived. Of course, rlwrap cannot read
68 the mind of command, so what looks like a prompt to rlwrap may
69 actually be the beginning of an output line that took command a
70 little longer to formulate. If this is a problem, specify a longer
71 "cooking" time with rlwrap's -w option, use the
72 prompts_are_never_empty method or "reject" the prompt (cf. the
73 prompt_rejected method)
74 $handler = $f -> completion_handler, $f ->
76 completion_handler(\&handler)
77 The completion handler gets called with the the entire input line,
78 the prefix (partial word to complete), and rlwrap's own completion
79 list as arguments. It should return a (possibly revised) list of
80 completions. As an example, suppose the user has typed "She played
81 for A<TAB>". The handler will be called like this:
82 myhandler("She played for A", "A", "Arsenal", "Arendal", "Anderlecht")
84 it could then return a list of stronger clubs: ("Ajax", "AZ67",
86 "Arnhem")
87 $handler = $f -> history_handler, $f -> history_handler(\&handler)
89 Every input line is submitted to this handler, the return value is
90 put in rlwrap's history. Returning an empty or undefined value will
91 keep the input line out of the history.
92 $handler = $f -> input_handler, $f -> input_handler(\&handler)
94 Every input line is submitted to this handler, The handler's return
95 value is written to command's pty (pseudo-terminal).
96 $handler = $f -> echo_handler, $f -> echo_handler(\&handler)
98 The first line of output that is read back from command's pty is
99 the echo'ed input line. If your input handler alters the input
100 line, it is the altered input that will be echo'ed back. If you
101 don't want to confuse the user, use an echo handler that returns
102 your original input.
103 If you use rlwrap in --multi-line mode, additional echo lines will
105 have to be handled by the output handler
106 $handler = $f -> output_handler, $f -> output_handler(\&handler)
108 All command output after the echo line is submitted to the output
109 handler (including newlines). This handler may get called many
110 times in succession, dependent on the size of command's write()
111 calls, and the whims of your system's scheduler. Therefore your
112 handler should be prepared to rewrite your output in "chunks",
113 where you even don't have the guarantee that the chunks contain
114 entire unbroken lines.
115 If you want to handle command's entire output in one go, you can
117 specify an output handler that returns an empty string, and then
118 use $filter -> cumulative_output in your prompt handler to send the
119 re-written output "out-of-band" just before the prompt:
120 $filter -> output_handler(sub {""});
122 $filter -> prompt_handler(
124 sub{ $filter -> send_output_oob(mysub($filter -> cumulative_output));
125 "Hi there > "
126 });
127 Note that when rlwrap is run in --multi-line mode the echo handler
129 will still only handle the first echo line. The remainder will
130 generally be echoed back preceded by a continuation prompt; it is
131 up to the output handler what to do with it.
132 $handler = $f -> message_handler, $f -> message_handler(\&handler)
134 This handler gets called (as handler($message, $tag)) for every
135 incoming message, and every tag (including out-of-band tags),
136 before all other handlers. Its return value is ignored, but it may
137 be useful for logging and debugging purposes. The $tag is an
138 integer that can be converted to a tag name by the 'tag2name'
139 method
140 OTHER METHODS
142 $f -> help_text("Usage...")
143 Set the help text for this filter. It will be displayed by rlwrap
144 -z <filter>. The second line of the help text is used by "rlwrap -z
145 listing"; it should be a short description of what the filter does.
146 $f -> minimal_rlwrap_version("x.yy")
148 Die unless rlwrap is version x.yy or newer
149 $dir = $f -> cwd
151 return the name of command's current working directory. This uses
152 the /proc filesystem, and may only work on newer linux systems (on
153 older linux and on Solaris, it will return something like
154 "/proc/12345/cwd", useful to find the contents of command's working
155 directory, but not its name)
156 $text = $f -> cumulative_output
158 return the current cumulative output. All (untreated) output gets
159 appended to the cumulative output after the output_handler has been
160 called. The cumulative output starts with a fresh slate with every
161 OUTPUT message that directly follows an INPUT message (ignoring
162 out-of-band messages and rejected prompts)
163 When necessary (i.e. when rlwrap is in "impatient mode") the prompt
165 is removed from $filter->cumulative_output by the time the prompt
166 handler is called.
167 $tag = $f -> previous_tag
169 The tag of the last preceding in-band message. A tag is an integer
170 between 0 and 255, its name can be found with the following method:
171 $name = $f -> tag2name($tag)
173 Convert the tag (an integer) to its name (e.g. "TAG_PROMPT")
174 $name = $f -> name2tag($tag)
176 Convert a valid tag name like "TAG_PROMPT" to a tag (an integer)
177 $f -> send_output_oob($text)
179 Make rlwrap display $text. $text is sent "out-of-band": rlwrap will
180 not see it until just after it has sent the next message to the
181 filter
182 $f -> send_ignore_oob($text)
184 Send an out-of-band TAG_IGNORE message to rlwrap. rlwrap will
185 silently discard it, but it can be useful when debugging filters
186 $f -> add_to_completion_list(@words)
188 $f -> remove_from_completion_list(@words)
189 Permanently add or remove the words in @words to/from rlwrap's
190 completion list.
191 $f -> cloak_and_dagger($question, $prompt, $timeout);
193 Send $question to command's input and read back everything that
194 comes back until $prompt is seen at "end-of-chunk", or no new
195 chunks arrive for $timeout seconds, whichever comes first. Return
196 the response (without the final $prompt). rlwrap remains
197 completely unaware of this conversation.
198 $f -> cloak_and_dagger_verbose($verbosity)
200 If $verbosity evaluates to a true value, make rlwrap print all
201 questions sent to command by the "cloak_and_dagger" method, and
202 command's responses. By default, $verbosity = 0; setting it to 1
203 will mess up the screen but greatly facilitate the (otherwise
204 rather tricky) use of "cloak_and_dagger"
205 $self -> prompt_rejected
207 A special text ("_THIS_CANNOT_BE_A_PROMPT_") to be returned by a
208 prompt handler to "reject" the prompt. This will make rlwrap skip
209 cooking the prompt. $self->previous_tag and
210 $self->cumulative_output will not be touched.
211 $text = $f -> prompts_are_never_empty($val)
213 If $val evaluates to a true value, automatically reject empty
214 prompts.
215 $f -> command_line
217 In scalar context: the rlwrapped command and its arguments as a
218 string ("command -v blah") in list context: the same as a list
219 ("command", "-v", "blah")
220 $f -> running_under_rlwrap
222 Whether the filter is run by rlwrap, or directly from the command
223 line
224 $f -> run
226 Start an event loop that reads rlwrap's messages from the input
227 pipe, calls the appropriate handlers and writes the result to the
228 output pipe. This method never returns.
229
231 rlwrap communicates with a filter through messages consisting of a tag
232 byte (TAG_OUTPUT, TAG_PROMPT etc. - to inform the filter of what is
233 being sent), an unsigned 32-bit integer containing the length of the
234 message, the message text and an extra newline. For every message sent,
235 rlwrap expects, and waits for an answer message with the same tag.
236 Sending back a different (in-band) tag is an error and instantly kills
237 rlwrap, though filters may precede their answer message with "out-of-
238 band" messages to output text (TAG_OUTPUT_OUT_OF_BAND), report errors
239 (TAG_ERROR), and to manipulate the completion word list
240 (TAG_ADD_TO_COMPLETION_LIST and TAG_REMOVE_FROM_COMPLETION_LIST) Out-
241 of-band messages are not serviced by rlwrap until right after it has
242 sent the next in-band message - the communication with the filter is
243 synchronous and driven by rlwrap.
244 Messages are received and sent via two pipes. STDIN, STDOUT and STDERR
246 are still connected to the user's terminal, and you can read and write
247 them directly, though this may mess up the screen and confuse the user
248 unless you are careful. A filter can even communicate with the
249 rlwrapped command behind rlwrap's back (cf the cloak_and_dagger()
250 method)
251 The protocol uses the following tags (tags > 128 are out-of-band)
253 TAG_INPUT 0
255 TAG_OUTPUT 1
256 TAG_HISTORY 2
257 TAG_COMPLETION 3
258 TAG_PROMPT 4
259 TAG_IGNORE 251
261 TAG_ADD_TO_COMPLETION_LIST 252
262 TAG_REMOVE_FROM_COMPLETION_LIST 253
263 TAG_OUTPUT_OUT_OF_BAND 254
264 TAG_ERROR 255
265 To see how this works, you can eavesdrop on the protocol using the
267 'logger' filter.
268 The constants TAG_INPUT, ... are exported by the RlwrapFilter.pm
270 module.
271
273 As STDIN is still connected to the users teminal, one might expect the
274 filter to receive SIGINT, SIGTERM, SIGTSTP directly from the terminal
275 driver if the user presses CTRL-C, CTRL-Z etc Normally, we don't want
276 this - it would confuse rlwrap, and the user (who thinks she is talking
277 straight to the rlwapped command) probably meant those signals to be
278 sent to the command itself. For this reason the filter starts with all
279 signals blocked.
280 Filters that interact with the users terminal (e.g. to run a pager)
282 should unblock signals like SIGTERM, SIGWINCH.
283
285 The filter is started by rlwrap after command, and stays alive as long
286 as rlwrap runs. Filter methods are immediately usable. When command
287 exits, the filter stays around for a little longer in order to process
288 command's last words. As calling the cwd and cloak_and_dagger methods
289 at that time will make the filter die with an error, it may be
290 advisable to wrap those calls in eval{}
291 If a filter calls die() it will send an (out-of-band) TAG_ERROR message
293 to rlwrap before exiting. rlwrap will then report the message and exit
294 (just after its next in-band message - out-of-band messages are not
295 always processed immediately)
296 die() within an eval() sets $@ as usual.
298
300 Before calling a filter, rlwrap sets the following environment
301 variables:
302 RLWRAP_FILTERDIR directory where RlwrapFilter.pm and most filters live (set by B<rlwrap>, can be
304 overridden by the user before calling rlwrap)
305 PATH rlwrap automatically adds $RLWRAP_FILTERDIR to the front of filter's PATH
307 RLWRAP_VERSION rlwrap version (e.g. "0.35")
309 RLWRAP_COMMAND_PID process ID of the rlwrapped command
311 RLWRAP_COMMAND_LINE command line of the rlwrapped command
313 RLWRAP_IMPATIENT whether rlwrap is in "impatient mode" (cf B<rlwrap (1)>). In impatient mode,
315 the candidate prompt is filtered through the output handler (and displayed before
316 being overwritten by the cooked prompt).
317 RLWRAP_INPUT_PIPE_FD File descriptor of input pipe. For internal use only
319 RLWRAP_OUTPUT_PIPE_FD File descriptor of output pipe. For internal use only
321 RLWRAP_MASTER_PTY_FD File descriptor of I<command>'s pty.
323
325 While RlwrapFilter.pm makes it easy to write simple filters, debugging
326 them can be a problem. A couple of useful tricks:
327 LOGGING
329 When running a filter, the in- and outgoing messages can be logged by
330 the logger filter, using a pipeline:
331 rlwrap -z 'pipeline logger incoming : my_filter : logger outgoing' command
333 RUNNING WITHOUT rlwrap
335 When called by rlwrap, filters get their input from
336 $RLWRAP_INPUT_PIPE_FD and write their output to $RLWRAP_OUTPUT_PIPE_FD,
337 and expect and write messages consisting of a tag byte, a 32-bit length
338 and the message proper. This is not terribly useful when running a
339 filter directly from the command line (outside rlwrap), even if we set
340 the RLWRAP_*_FD ourselves.
341 Therfore, when run directly from the command line, a filter expects
343 input messages on its standard input of the form
344 TAG_PROMPT >
346 (i.a. a tag name, one space and a message) and it will respond in the
348 same way on its standard output
349
351 rlwrap (1), readline (3)
352perl v5.8.8 2010-01-08 RlwrapFilter(3pm)