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