1 package Filter::Simple;
3 use vars qw{ $VERSION };
7 use Filter::Util::Call;
11 if (@_>1) { shift; goto &FILTER }
12 else { *{caller()."::FILTER"} = \&FILTER }
17 my ($filter, $terminator) = @_;
18 *{"${caller}::import"} = gen_filter_import($caller,$filter,$terminator);
19 *{"${caller}::unimport"} = \*filter_unimport;
22 sub gen_filter_import {
23 my ($class, $filter, $terminator) = @_;
25 my ($imported_class, @args) = @_;
26 $terminator = qr/^\s*no\s+$imported_class\s*;\s*$/
27 unless defined $terminator;
33 while ($status = filter_read()) {
34 return $status if $status < 0;
35 if ($terminator && m/$terminator/) {
44 $filter->(@args) unless $status < 0;
45 $_ .= "no $imported_class;\n" if $off;
62 Filter::Simple - Simplified source filtering
77 # use Filter::Simple sub { ... };
83 # this code is filtered
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.
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.
104 To use the module it is necessary to do the following:
110 Download, build, and install the Filter::Util::Call module.
111 (If you have Perl 5.7.1 or later, this is already done for you.)
115 Set up a module that does a C<use Filter::Util::Call>.
119 Within that module, create an C<import> subroutine.
123 Within the C<import> subroutine do a call to C<filter_add>, passing
124 it either a subroutine reference.
128 Within the subroutine reference, call C<filter_read> or C<filter_read_exact>
129 to "prime" $_ with source code data from the source file that will
130 C<use> your module. Check the status value returned to see if any
131 source code was actually read in.
135 Process the contents of $_ to change the source code in the desired manner.
139 Return the status value.
143 If the act of unimporting your module (via a C<no>) should cause source
144 code filtering to cease, create an C<unimport> subroutine, and have it call
145 C<filter_del>. Make sure that the call to C<filter_read> or
146 C<filter_read_exact> in step 5 will not accidentally read past the
147 C<no>. Effectively this limits source code filters to line-by-line
148 operation, unless the C<import> subroutine does some fancy
149 pre-pre-parsing of the source code it's filtering.
153 For example, here is a minimal source code filter in a module named
154 BANG.pm. It simply converts every occurrence of the sequence C<BANG\s+BANG>
155 to the sequence C<die 'BANG' if $BANG> in any piece of code following a
156 C<use BANG;> statement (until the next C<no BANG;> statement, if any):
160 use Filter::Util::Call ;
165 my ($status, $no_seen, $data);
166 while ($status = filter_read()) {
167 if (/^\s*no\s+$caller\s*;\s*?$/) {
175 s/BANG\s+BANG/die 'BANG' if \$BANG/g
177 $_ .= "no $class;\n" if $no_seen;
188 This level of sophistication puts filtering out of the reach of
194 The Filter::Simple module provides a simplified interface to
195 Filter::Util::Call; one that is sufficient for most common cases.
197 Instead of the above process, with Filter::Simple the task of setting up
198 a source code filter is reduced to:
204 Download and install the Filter::Simple module.
205 (If you have Perl 5.7.1 or later, this is already done for you.)
209 Set up a module that does a C<use Filter::Simple> and then
210 calls C<FILTER { ... }>.
214 Within the anonymous subroutine or block that is passed to
215 C<FILTER>, process the contents of $_ to change the source code in
220 In other words, the previous example, would become:
226 s/BANG\s+BANG/die 'BANG' if \$BANG/g;
232 =head2 Disabling or changing <no> behaviour
234 By default, the installed filter only filters to a line of the form:
238 but this can be altered by passing a second argument to C<use Filter::Simple>.
240 That second argument may be either a C<qr>'d regular expression (which is then
241 used to match the terminator line), or a defined false value (which indicates
242 that no terminator line should be looked for).
244 For example, to cause the previous filter to filter only up to a line of the
255 s/BANG\s+BANG/die 'BANG' if \$BANG/g;
257 => qr/^\s*GNAB\s+esu\s*;\s*?$/;
259 and to prevent the filter's being turned off in any way:
265 s/BANG\s+BANG/die 'BANG' if \$BANG/g;
271 =head2 All-in-one interface
273 Separating the loading of Filter::Simple:
277 from the setting up of the filtering:
281 is useful because it allows other code (typically parser support code
282 or caching variables) to be defined before the filter is invoked.
283 However, there is often no need for such a separation.
285 In those cases, it is easier to just append the filtering subroutine and
286 any terminator specification directly to the C<use> statement that loads
287 Filter::Simple, like so:
289 use Filter::Simple sub {
290 s/BANG\s+BANG/die 'BANG' if \$BANG/g;
293 This is exactly the same as:
297 Filter::Simple::FILTER {
298 s/BANG\s+BANG/die 'BANG' if \$BANG/g;
302 except that the C<FILTER> subroutine is not exported by Filter::Simple.
304 =head2 Using Filter::Simple and Exporter together
306 You can't directly use Exporter when Filter::Simple.
308 Filter::Simple generates an C<import> subroutine for your module
309 (which hides the one inherited from Exporter).
311 The C<FILTER> code you specify will, however, receive the C<import>'s argument
312 list, so you can use that filter block as your C<import> subroutine.
314 You'll need to call C<Exporter::export_to_level> from your C<FILTER> code
315 to make it work correctly.
323 @EXPORT_OK = qw(bar);
325 sub foo { print "foo\n" }
326 sub bar { print "bar\n" }
329 # Your filtering code here
330 __PACKAGE__->export_to_level(2,undef,@_);
336 The Filter::Simple module exports into the package that calls C<FILTER>
337 (or C<use>s it directly) -- such as package "BANG" in the above example --
338 two automagically constructed
339 subroutines -- C<import> and C<unimport> -- which take care of all the
342 In addition, the generated C<import> subroutine passes its own argument
343 list to the filtering subroutine, so the BANG.pm filter could easily
351 my ($die_msg, $var_name) = @_;
352 s/BANG\s+BANG/die '$die_msg' if \${$var_name}/g;
355 # and in some user code:
357 use BANG "BOOM", "BAM"; # "BANG BANG" becomes: die 'BOOM' if $BAM
360 The specified filtering subroutine is called every time a C<use BANG> is
361 encountered, and passed all the source code following that call, up to
362 either the next C<no BANG;> (or whatever terminator you've set) or the
363 end of the source file, whichever occurs first. By default, any C<no
364 BANG;> call must appear by itself on a separate line, or it is ignored.
369 Damian Conway (damian@conway.org)
373 Copyright (c) 2000-2001, Damian Conway. All Rights Reserved.
374 This module is free software. It may be used, redistributed
375 and/or modified under the same terms as Perl itself.