Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Filter::Simple.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Filter::Simple 3pm"
61 .TH Filter::Simple 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Filter::Simple \- Simplified source filtering
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& # in MyFilter.pm:
72 \&
73 \& package MyFilter;
74 \&
75 \& use Filter::Simple;
76 \&
77 \& FILTER { ... };
78 \&
79 \& # or just:
80 \& #
81 \& # use Filter::Simple sub { ... };
82 \&
83 \& # in user\*(Aqs code:
84 \&
85 \& use MyFilter;
86 \&
87 \& # this code is filtered
88 \&
89 \& no MyFilter;
90 \&
91 \& # this code is not
92 .Ve
93 .SH DESCRIPTION
94 .IX Header "DESCRIPTION"
95 .SS "The Problem"
96 .IX Subsection "The Problem"
97 Source filtering is an immensely powerful feature of recent versions of Perl.
98 It allows one to extend the language itself (e.g. the Switch module), to
99 simplify the language (e.g. Language::Pythonesque), or to completely recast the
100 language (e.g. Lingua::Romana::Perligata). Effectively, it allows one to use
101 the full power of Perl as its own, recursively applied, macro language.
102 .PP
103 The excellent Filter::Util::Call module (by Paul Marquess) provides a
104 usable Perl interface to source filtering, but it is often too powerful
105 and not nearly as simple as it could be.
106 .PP
107 To use the module it is necessary to do the following:
108 .IP 1. 4
109 Download, build, and install the Filter::Util::Call module.
110 (If you have Perl 5.7.1 or later, this is already done for you.)
111 .IP 2. 4
112 Set up a module that does a \f(CW\*(C`use Filter::Util::Call\*(C'\fR.
113 .IP 3. 4
114 Within that module, create an \f(CW\*(C`import\*(C'\fR subroutine.
115 .IP 4. 4
116 Within the \f(CW\*(C`import\*(C'\fR subroutine do a call to \f(CW\*(C`filter_add\*(C'\fR, passing
117 it either a subroutine reference.
118 .IP 5. 4
119 Within the subroutine reference, call \f(CW\*(C`filter_read\*(C'\fR or \f(CW\*(C`filter_read_exact\*(C'\fR
120 to "prime" \f(CW$_\fR with source code data from the source file that will
121 \&\f(CW\*(C`use\*(C'\fR your module. Check the status value returned to see if any
122 source code was actually read in.
123 .IP 6. 4
124 Process the contents of \f(CW$_\fR to change the source code in the desired manner.
125 .IP 7. 4
126 Return the status value.
127 .IP 8. 4
128 If the act of unimporting your module (via a \f(CW\*(C`no\*(C'\fR) should cause source
129 code filtering to cease, create an \f(CW\*(C`unimport\*(C'\fR subroutine, and have it call
130 \&\f(CW\*(C`filter_del\*(C'\fR. Make sure that the call to \f(CW\*(C`filter_read\*(C'\fR or
131 \&\f(CW\*(C`filter_read_exact\*(C'\fR in step 5 will not accidentally read past the
132 \&\f(CW\*(C`no\*(C'\fR. Effectively this limits source code filters to line\-by\-line
133 operation, unless the \f(CW\*(C`import\*(C'\fR subroutine does some fancy
134 pre\-pre\-parsing of the source code it\*(Aqs filtering.
135 .PP
136 For example, here is a minimal source code filter in a module named
137 BANG.pm. It simply converts every occurrence of the sequence \f(CW\*(C`BANG\es+BANG\*(C'\fR
138 to the sequence \f(CW\*(C`die \*(AqBANG\*(Aq if $BANG\*(C'\fR in any piece of code following a
139 \&\f(CW\*(C`use BANG;\*(C'\fR statement (until the next \f(CW\*(C`no BANG;\*(C'\fR statement, if any):
140 .PP
141 .Vb 1
142 \& package BANG;
143 \&
144 \& use Filter::Util::Call ;
145 \&
146 \& sub import {
147 \& filter_add( sub {
148 \& my $caller = caller;
149 \& my ($status, $no_seen, $data);
150 \& while ($status = filter_read()) {
151 \& if (/^\es*no\es+$caller\es*;\es*?$/) {
152 \& $no_seen=1;
153 \& last;
154 \& }
155 \& $data .= $_;
156 \& $_ = "";
157 \& }
158 \& $_ = $data;
159 \& s/BANG\es+BANG/die \*(AqBANG\*(Aq if \e$BANG/g
160 \& unless $status < 0;
161 \& $_ .= "no $class;\en" if $no_seen;
162 \& return 1;
163 \& })
164 \& }
165 \&
166 \& sub unimport {
167 \& filter_del();
168 \& }
169 \&
170 \& 1 ;
171 .Ve
172 .PP
173 This level of sophistication puts filtering out of the reach of
174 many programmers.
175 .SS "A Solution"
176 .IX Subsection "A Solution"
177 The Filter::Simple module provides a simplified interface to
178 Filter::Util::Call; one that is sufficient for most common cases.
179 .PP
180 Instead of the above process, with Filter::Simple the task of setting up
181 a source code filter is reduced to:
182 .IP 1. 4
183 Download and install the Filter::Simple module.
184 (If you have Perl 5.7.1 or later, this is already done for you.)
185 .IP 2. 4
186 Set up a module that does a \f(CW\*(C`use Filter::Simple\*(C'\fR and then
187 calls \f(CW\*(C`FILTER { ... }\*(C'\fR.
188 .IP 3. 4
189 Within the anonymous subroutine or block that is passed to
190 \&\f(CW\*(C`FILTER\*(C'\fR, process the contents of \f(CW$_\fR to change the source code in
191 the desired manner.
192 .PP
193 In other words, the previous example, would become:
194 .PP
195 .Vb 2
196 \& package BANG;
197 \& use Filter::Simple;
198 \&
199 \& FILTER {
200 \& s/BANG\es+BANG/die \*(AqBANG\*(Aq if \e$BANG/g;
201 \& };
202 \&
203 \& 1 ;
204 .Ve
205 .PP
206 Note that the source code is passed as a single string, so any regex that
207 uses \f(CW\*(C`^\*(C'\fR or \f(CW\*(C`$\*(C'\fR to detect line boundaries will need the \f(CW\*(C`/m\*(C'\fR flag.
208 .SS "Disabling or changing <no> behaviour"
209 .IX Subsection "Disabling or changing <no> behaviour"
210 By default, the installed filter only filters up to a line consisting of one of
211 the three standard source "terminators":
212 .PP
213 .Vb 1
214 \& no ModuleName; # optional comment
215 .Ve
216 .PP
217 or:
218 .PP
219 .Vb 1
220 \& _\|_END_\|_
221 .Ve
222 .PP
223 or:
224 .PP
225 .Vb 1
226 \& _\|_DATA_\|_
227 .Ve
228 .PP
229 but this can be altered by passing a second argument to \f(CW\*(C`use Filter::Simple\*(C'\fR
230 or \f(CW\*(C`FILTER\*(C'\fR (just remember: there\*(Aqs \fIno\fR comma after the initial block when
231 you use \f(CW\*(C`FILTER\*(C'\fR).
232 .PP
233 That second argument may be either a \f(CW\*(C`qr\*(C'\fR\*(Aqd regular expression (which is then
234 used to match the terminator line), or a defined false value (which indicates
235 that no terminator line should be looked for), or a reference to a hash
236 (in which case the terminator is the value associated with the key
237 \&\f(CW\*(Aqterminator\*(Aq\fR.
238 .PP
239 For example, to cause the previous filter to filter only up to a line of the
240 form:
241 .PP
242 .Vb 1
243 \& GNAB esu;
244 .Ve
245 .PP
246 you would write:
247 .PP
248 .Vb 2
249 \& package BANG;
250 \& use Filter::Simple;
251 \&
252 \& FILTER {
253 \& s/BANG\es+BANG/die \*(AqBANG\*(Aq if \e$BANG/g;
254 \& }
255 \& qr/^\es*GNAB\es+esu\es*;\es*?$/;
256 .Ve
257 .PP
258 or:
259 .PP
260 .Vb 4
261 \& FILTER {
262 \& s/BANG\es+BANG/die \*(AqBANG\*(Aq if \e$BANG/g;
263 \& }
264 \& { terminator => qr/^\es*GNAB\es+esu\es*;\es*?$/ };
265 .Ve
266 .PP
267 and to prevent the filter\*(Aqs being turned off in any way:
268 .PP
269 .Vb 2
270 \& package BANG;
271 \& use Filter::Simple;
272 \&
273 \& FILTER {
274 \& s/BANG\es+BANG/die \*(AqBANG\*(Aq if \e$BANG/g;
275 \& }
276 \& ""; # or: 0
277 .Ve
278 .PP
279 or:
280 .PP
281 .Vb 4
282 \& FILTER {
283 \& s/BANG\es+BANG/die \*(AqBANG\*(Aq if \e$BANG/g;
284 \& }
285 \& { terminator => "" };
286 .Ve
287 .PP
288 \&\fBNote that, no matter what you set the terminator pattern to,
289 the actual terminator itself \fR\f(BImust\fR\fB be contained on a single source line.\fR
290 .SS "All\-in\-one interface"
291 .IX Subsection "All-in-one interface"
292 Separating the loading of Filter::Simple:
293 .PP
294 .Vb 1
295 \& use Filter::Simple;
296 .Ve
297 .PP
298 from the setting up of the filtering:
299 .PP
300 .Vb 1
301 \& FILTER { ... };
302 .Ve
303 .PP
304 is useful because it allows other code (typically parser support code
305 or caching variables) to be defined before the filter is invoked.
306 However, there is often no need for such a separation.
307 .PP
308 In those cases, it is easier to just append the filtering subroutine and
309 any terminator specification directly to the \f(CW\*(C`use\*(C'\fR statement that loads
310 Filter::Simple, like so:
311 .PP
312 .Vb 3
313 \& use Filter::Simple sub {
314 \& s/BANG\es+BANG/die \*(AqBANG\*(Aq if \e$BANG/g;
315 \& };
316 .Ve
317 .PP
318 This is exactly the same as:
319 .PP
320 .Vb 6
321 \& use Filter::Simple;
322 \& BEGIN {
323 \& Filter::Simple::FILTER {
324 \& s/BANG\es+BANG/die \*(AqBANG\*(Aq if \e$BANG/g;
325 \& };
326 \& }
327 .Ve
328 .PP
329 except that the \f(CW\*(C`FILTER\*(C'\fR subroutine is not exported by Filter::Simple.
330 .SS "Filtering only specific components of source code"
331 .IX Subsection "Filtering only specific components of source code"
332 One of the problems with a filter like:
333 .PP
334 .Vb 1
335 \& use Filter::Simple;
336 \&
337 \& FILTER { s/BANG\es+BANG/die \*(AqBANG\*(Aq if \e$BANG/g };
338 .Ve
339 .PP
340 is that it indiscriminately applies the specified transformation to
341 the entire text of your source program. So something like:
342 .PP
343 .Vb 2
344 \& warn \*(AqBANG BANG, YOU\*(AqRE DEAD\*(Aq;
345 \& BANG BANG;
346 .Ve
347 .PP
348 will become:
349 .PP
350 .Vb 2
351 \& warn \*(Aqdie \*(AqBANG\*(Aq if $BANG, YOU\*(AqRE DEAD\*(Aq;
352 \& die \*(AqBANG\*(Aq if $BANG;
353 .Ve
354 .PP
355 It is very common when filtering source to only want to apply the filter
356 to the non\-character\-string parts of the code, or alternatively to \fIonly\fR
357 the character strings.
358 .PP
359 Filter::Simple supports this type of filtering by automatically
360 exporting the \f(CW\*(C`FILTER_ONLY\*(C'\fR subroutine.
361 .PP
362 \&\f(CW\*(C`FILTER_ONLY\*(C'\fR takes a sequence of specifiers that install separate
363 (and possibly multiple) filters that act on only parts of the source code.
364 For example:
365 .PP
366 .Vb 1
367 \& use Filter::Simple;
368 \&
369 \& FILTER_ONLY
370 \& code => sub { s/BANG\es+BANG/die \*(AqBANG\*(Aq if \e$BANG/g },
371 \& quotelike => sub { s/BANG\es+BANG/CHITTY CHITTY/g };
372 .Ve
373 .PP
374 The \f(CW"code"\fR subroutine will only be used to filter parts of the source
375 code that are not quotelikes, POD, or \f(CW\*(C`_\|_DATA_\|_\*(C'\fR. The \f(CW\*(C`quotelike\*(C'\fR
376 subroutine only filters Perl quotelikes (including here documents).
377 .PP
378 The full list of alternatives is:
379 .ie n .IP """code""" 4
380 .el .IP "\f(CW""code""\fR" 4
381 .IX Item """code"""
382 Filters only those sections of the source code that are not quotelikes, POD, or
383 \&\f(CW\*(C`_\|_DATA_\|_\*(C'\fR.
384 .ie n .IP """code_no_comments""" 4
385 .el .IP "\f(CW""code_no_comments""\fR" 4
386 .IX Item """code_no_comments"""
387 Filters only those sections of the source code that are not quotelikes, POD,
388 comments, or \f(CW\*(C`_\|_DATA_\|_\*(C'\fR.
389 .ie n .IP """executable""" 4
390 .el .IP "\f(CW""executable""\fR" 4
391 .IX Item """executable"""
392 Filters only those sections of the source code that are not POD or \f(CW\*(C`_\|_DATA_\|_\*(C'\fR.
393 .ie n .IP """executable_no_comments""" 4
394 .el .IP "\f(CW""executable_no_comments""\fR" 4
395 .IX Item """executable_no_comments"""
396 Filters only those sections of the source code that are not POD, comments, or \f(CW\*(C`_\|_DATA_\|_\*(C'\fR.
397 .ie n .IP """quotelike""" 4
398 .el .IP "\f(CW""quotelike""\fR" 4
399 .IX Item """quotelike"""
400 Filters only Perl quotelikes (as interpreted by
401 \&\f(CW&Text::Balanced::extract_quotelike\fR).
402 .ie n .IP """string""" 4
403 .el .IP "\f(CW""string""\fR" 4
404 .IX Item """string"""
405 Filters only the string literal parts of a Perl quotelike (i.e. the
406 contents of a string literal, either half of a \f(CW\*(C`tr///\*(C'\fR, the second
407 half of an \f(CW\*(C`s///\*(C'\fR).
408 .ie n .IP """regex""" 4
409 .el .IP "\f(CW""regex""\fR" 4
410 .IX Item """regex"""
411 Filters only the pattern literal parts of a Perl quotelike (i.e. the
412 contents of a \f(CW\*(C`qr//\*(C'\fR or an \f(CW\*(C`m//\*(C'\fR, the first half of an \f(CW\*(C`s///\*(C'\fR).
413 .ie n .IP """all""" 4
414 .el .IP "\f(CW""all""\fR" 4
415 .IX Item """all"""
416 Filters everything. Identical in effect to \f(CW\*(C`FILTER\*(C'\fR.
417 .PP
418 Except for \f(CW\*(C`FILTER_ONLY code => sub {...}\*(C'\fR, each of
419 the component filters is called repeatedly, once for each component
420 found in the source code.
421 .PP
422 Note that you can also apply two or more of the same type of filter in
423 a single \f(CW\*(C`FILTER_ONLY\*(C'\fR. For example, here\*(Aqs a simple
424 macro\-preprocessor that is only applied within regexes,
425 with a final debugging pass that prints the resulting source code:
426 .PP
427 .Vb 6
428 \& use Regexp::Common;
429 \& FILTER_ONLY
430 \& regex => sub { s/!\e[/[^/g },
431 \& regex => sub { s/%d/$RE{num}{int}/g },
432 \& regex => sub { s/%f/$RE{num}{real}/g },
433 \& all => sub { print if $::DEBUG };
434 .Ve
435 .SS "Filtering only the code parts of source code"
436 .IX Subsection "Filtering only the code parts of source code"
437 Most source code ceases to be grammatically correct when it is broken up
438 into the pieces between string literals and regexes. So the \f(CW\*(Aqcode\*(Aq\fR
439 and \f(CW\*(Aqcode_no_comments\*(Aq\fR component filter behave slightly differently
440 from the other partial filters described in the previous section.
441 .PP
442 Rather than calling the specified processor on each individual piece of
443 code (i.e. on the bits between quotelikes), the \f(CW\*(Aqcode...\*(Aq\fR partial
444 filters operate on the entire source code, but with the quotelike bits
445 (and, in the case of \f(CW\*(Aqcode_no_comments\*(Aq\fR, the comments) "blanked out".
446 .PP
447 That is, a \f(CW\*(Aqcode...\*(Aq\fR filter \fIreplaces\fR each quoted string, quotelike,
448 regex, POD, and _\|_DATA_\|_ section with a placeholder. The
449 delimiters of this placeholder are the contents of the \f(CW$;\fR variable
450 at the time the filter is applied (normally \f(CW"\e034"\fR). The remaining
451 four bytes are a unique identifier for the component being replaced.
452 .PP
453 This approach makes it comparatively easy to write code preprocessors
454 without worrying about the form or contents of strings, regexes, etc.
455 .PP
456 For convenience, during a \f(CW\*(Aqcode...\*(Aq\fR filtering operation, Filter::Simple
457 provides a package variable (\f(CW$Filter::Simple::placeholder\fR) that
458 contains a pre\-compiled regex that matches any placeholder...and
459 captures the identifier within the placeholder. Placeholders can be
460 moved and re\-ordered within the source code as needed.
461 .PP
462 In addition, a second package variable (\f(CW@Filter::Simple::components\fR)
463 contains a list of the various pieces of \f(CW$_\fR, as they were originally split
464 up to allow placeholders to be inserted.
465 .PP
466 Once the filtering has been applied, the original strings, regexes, POD,
467 etc. are re\-inserted into the code, by replacing each placeholder with
468 the corresponding original component (from \f(CW@components\fR). Note that
469 this means that the \f(CW@components\fR variable must be treated with extreme
470 care within the filter. The \f(CW@components\fR array stores the "back\-
471 translations" of each placeholder inserted into \f(CW$_\fR, as well as the
472 interstitial source code between placeholders. If the placeholder
473 backtranslations are altered in \f(CW@components\fR, they will be similarly
474 changed when the placeholders are removed from \f(CW$_\fR after the filter
475 is complete.
476 .PP
477 For example, the following filter detects concatenated pairs of
478 strings/quotelikes and reverses the order in which they are
479 concatenated:
480 .PP
481 .Vb 2
482 \& package DemoRevCat;
483 \& use Filter::Simple;
484 \&
485 \& FILTER_ONLY code => sub {
486 \& my $ph = $Filter::Simple::placeholder;
487 \& s{ ($ph) \es* [.] \es* ($ph) }{ $2.$1 }gx
488 \& };
489 .Ve
490 .PP
491 Thus, the following code:
492 .PP
493 .Vb 1
494 \& use DemoRevCat;
495 \&
496 \& my $str = "abc" . q(def);
497 \&
498 \& print "$str\en";
499 .Ve
500 .PP
501 would become:
502 .PP
503 .Vb 1
504 \& my $str = q(def)."abc";
505 \&
506 \& print "$str\en";
507 .Ve
508 .PP
509 and hence print:
510 .PP
511 .Vb 1
512 \& defabc
513 .Ve
514 .ie n .SS "Using Filter::Simple with an explicit ""import"" subroutine"
515 .el .SS "Using Filter::Simple with an explicit \f(CWimport\fP subroutine"
516 .IX Subsection "Using Filter::Simple with an explicit import subroutine"
517 Filter::Simple generates a special \f(CW\*(C`import\*(C'\fR subroutine for
518 your module (see "How it works") which would normally replace any
519 \&\f(CW\*(C`import\*(C'\fR subroutine you might have explicitly declared.
520 .PP
521 However, Filter::Simple is smart enough to notice your existing
522 \&\f(CW\*(C`import\*(C'\fR and Do The Right Thing with it.
523 That is, if you explicitly define an \f(CW\*(C`import\*(C'\fR subroutine in a package
524 that\*(Aqs using Filter::Simple, that \f(CW\*(C`import\*(C'\fR subroutine will still
525 be invoked immediately after any filter you install.
526 .PP
527 The only thing you have to remember is that the \f(CW\*(C`import\*(C'\fR subroutine
528 \&\fImust\fR be declared \fIbefore\fR the filter is installed. If you use \f(CW\*(C`FILTER\*(C'\fR
529 to install the filter:
530 .PP
531 .Vb 1
532 \& package Filter::TurnItUpTo11;
533 \&
534 \& use Filter::Simple;
535 \&
536 \& FILTER { s/(\ew+)/\eU$1/ };
537 .Ve
538 .PP
539 that will almost never be a problem, but if you install a filtering
540 subroutine by passing it directly to the \f(CW\*(C`use Filter::Simple\*(C'\fR
541 statement:
542 .PP
543 .Vb 1
544 \& package Filter::TurnItUpTo11;
545 \&
546 \& use Filter::Simple sub{ s/(\ew+)/\eU$1/ };
547 .Ve
548 .PP
549 then you must make sure that your \f(CW\*(C`import\*(C'\fR subroutine appears before
550 that \f(CW\*(C`use\*(C'\fR statement.
551 .SS "Using Filter::Simple and Exporter together"
552 .IX Subsection "Using Filter::Simple and Exporter together"
553 Likewise, Filter::Simple is also smart enough
554 to Do The Right Thing if you use Exporter:
555 .PP
556 .Vb 3
557 \& package Switch;
558 \& use base Exporter;
559 \& use Filter::Simple;
560 \&
561 \& @EXPORT = qw(switch case);
562 \& @EXPORT_OK = qw(given when);
563 \&
564 \& FILTER { $_ = magic_Perl_filter($_) }
565 .Ve
566 .PP
567 Immediately after the filter has been applied to the source,
568 Filter::Simple will pass control to Exporter, so it can do its magic too.
569 .PP
570 Of course, here too, Filter::Simple has to know you\*(Aqre using Exporter
571 before it applies the filter. That\*(Aqs almost never a problem, but if you\*(Aqre
572 nervous about it, you can guarantee that things will work correctly by
573 ensuring that your \f(CW\*(C`use base Exporter\*(C'\fR always precedes your
574 \&\f(CW\*(C`use Filter::Simple\*(C'\fR.
575 .SS "How it works"
576 .IX Subsection "How it works"
577 The Filter::Simple module exports into the package that calls \f(CW\*(C`FILTER\*(C'\fR
578 (or \f(CW\*(C`use\*(C'\fRs it directly) \-\- such as package "BANG" in the above example \-\-
579 two automagically constructed
580 subroutines \-\- \f(CW\*(C`import\*(C'\fR and \f(CW\*(C`unimport\*(C'\fR \-\- which take care of all the
581 nasty details.
582 .PP
583 In addition, the generated \f(CW\*(C`import\*(C'\fR subroutine passes its own argument
584 list to the filtering subroutine, so the BANG.pm filter could easily
585 be made parametric:
586 .PP
587 .Vb 1
588 \& package BANG;
589 \&
590 \& use Filter::Simple;
591 \&
592 \& FILTER {
593 \& my ($die_msg, $var_name) = @_;
594 \& s/BANG\es+BANG/die \*(Aq$die_msg\*(Aq if \e${$var_name}/g;
595 \& };
596 \&
597 \& # and in some user code:
598 \&
599 \& use BANG "BOOM", "BAM"; # "BANG BANG" becomes: die \*(AqBOOM\*(Aq if $BAM
600 .Ve
601 .PP
602 The specified filtering subroutine is called every time a \f(CW\*(C`use BANG\*(C'\fR is
603 encountered, and passed all the source code following that call, up to
604 either the next \f(CW\*(C`no BANG;\*(C'\fR (or whatever terminator you\*(Aqve set) or the
605 end of the source file, whichever occurs first. By default, any \f(CW\*(C`no
606 BANG;\*(C'\fR call must appear by itself on a separate line, or it is ignored.
607 .SH AUTHOR
608 .IX Header "AUTHOR"
609 Damian Conway
610 .SH CONTACT
611 .IX Header "CONTACT"
612 Filter::Simple is now maintained by the Perl5\-Porters.
613 Please submit bug via the \f(CW\*(C`perlbug\*(C'\fR tool that comes with your perl.
614 For usage instructions, read \f(CW\*(C`perldoc perlbug\*(C'\fR or possibly \f(CW\*(C`man perlbug\*(C'\fR.
615 For mostly anything else, please contact <perl5\[email protected]>.
616 .PP
617 Maintainer of the CPAN release is Steffen Mueller <[email protected]>.
618 Contact him with technical difficulties with respect to the packaging of the
619 CPAN module.
620 .PP
621 Praise of the module, flowers, and presents still go to the author,
622 Damian Conway <[email protected]>.
623 .SH "COPYRIGHT AND LICENSE"
624 .IX Header "COPYRIGHT AND LICENSE"
625 .Vb 3
626 \& Copyright (c) 2000\-2014, Damian Conway. All Rights Reserved.
627 \& This module is free software. It may be used, redistributed
628 \& and/or modified under the same terms as Perl itself.
629 .Ve