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