Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

RE: RE: Filehandle Filter

by btrott (Parson)
on Aug 12, 2000 at 22:10 UTC ( [id://27643]=note: print w/replies, xml ) Need Help??


in reply to RE: Filehandle Filter
in thread Filehandle Filter

Here's my POD documentation for this module (which is basically what the latest version looks like):
=head1 NAME Filter::Handle - Apply filters to output filehandles =head1 SYNOPSIS use Filter::Handle; my $f = Filter::Handle->new(\*STDOUT); use Filter::Handle qw/subs/; Filter \*STDOUT; ... UnFilter \*STDOUT; =head1 DESCRIPTION I<Filter::Handle> allows you to apply arbitrary filters to output filehandles. You can perform any sorts of transformations on the outgoing text: you can prepend it with some data, you can replace all instances of one word with another, etc. You can even filter all of your output to one filehandle and send it to another; for example, you can filter everything written to STDOUT and write it instead to another filehandle. To do this, you need to explicitly use the I<tie> interface (see below). =head2 Calling Interfaces There are three interfaces to filtering a handle: =over 4 =item * Functional use Filter::Handle qw/subs/; Filter \*STDOUT; print "I am filtered text"; UnFilter \*STDOUT; print "I am normal text"; The functional interface works by exporting two functions into the caller's namespace: I<Filter> and I<UnFilter>. To start filtering a filehandle, call the I<Filter> function; to stop, call I<UnFilter> on that same filehandle. Any writes between the time you start and stop filtering will be filtered. =item * Object-Oriented use Filter::Handle; { my $f = Filter::Handle->new(\*STDOUT); print "I am filtered text"; } print "I am normal text"; The object-oriented interface works by filtering the filehandle while your object is in scope. Once all references to that object have gone out of scope--typically, this is after your one reference has gone away--the filehandle will no longer be filtered. =item * Tie Interface use Filter::Handle; local *HANDLE; tie *STDOUT, 'Filter::Handle', \*HANDLE; print "I am filtered text written to HANDLE"; untie *STDOUT; The I<tie> interface will filter your filehandle until you explicitly I<untie> it. This is the only interface that allows you to filter one filehandle through another. The above example will filter all writes to STDOUT through the output filter, then write it out on HANDLE. Note that this is different behavior than that of the first two interfaces; if you want your output written to the same handle that you're filtering, you could use: tie *STDOUT, 'Filter::Handle', \*STDOUT; Which is exactly what the first two interfaces do. =back =head2 Customized Filters The default filter is relatively boring: it simply prepends any text you print with the filename and line of the invoking caller. You'll probably want to do something more interesting. To do so, pass an anonymous subroutine as a second argument to either the I<new> method, if you're using the OO interface, or to the I<Filter> function, if you're using the functional interface. Your subroutine will be passed the list originally passed to print, and it should return another list, suitable for passing to your (unfiltered) output filehandle. For example, say that we want to replace all instances of "blue" with "red". We could say: use Filter::Handle qw/subs/; Filter \*STDOUT, sub { local $_ = "@_"; s/blue/red/g; $_ }; print "My house is blue.\n"; print "So is my cat, whose nose is blue.\n"; UnFilter \*STDOUT; print "And the plane is also blue.\n"; This prints: My house is red. So is my cat, whose nose is red. And the plane is also blue. As expected. =head1 CAVEATS Note that this won't work correctly with output from XSUBs or system calls. This is due to a limitation of Perl's I<tie> mechanism when tying filehandles. =head1 AUTHOR Benjamin Trott, ben@rhumba.pair.com =head1 CREDITS Thanks to tilly, chromatic, Adam, and merlyn at PerlMonks.org for suggestions, critiques, and code samples. =cut

Replies are listed 'Best First'.
RE (tilly) 3: Filehandle Filter
by tilly (Archbishop) on Aug 12, 2000 at 22:48 UTC
    Excellent! And for those who look at the code and are totally lost, here is a useful hint on how tie works. All that tie does is allow an object in a class that defines the right methods to look like a native Perl datatype. The only thing you have to do is make sure that you are providing the OO interface that Perl is looking for.

    To find out what methods are part of the interface that Perl knows to look for type "perldoc -f tie". Note that the documentation here of tie is somewhat misleading since it documents the limitations of tie that were in Perl 5.003. For instance you probably can create a full tied interface to an array.

    It feels strange the first few times you create an implementation of a tied class, but it really is not very hard and it is an excellent example of how encapsulation can lead to good things later. :-)

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://27643]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others having a coffee break in the Monastery: (6)
As of 2024-03-19 11:22 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found