Module Tie::Handle::Intercepted

Discussion in 'Perl Misc' started by John, May 6, 2004.

  1. John

    John Guest

    What do y'all think of this module? Do we need it on CPAN? Is it apty
    named? Other comments? Documentation included below.

    =head1 NAME

    Tie::Handle::Intercepted - Intercept, Filter, Reroute, and Fork File
    Handles.

    =head1 SYNOPSIS

    ###Intercept
    intercept \*STDOUT, sub {
    print STDERR "Luppy!\n"; #If we print to STDOUT, we will cause an
    infinite loop!
    }
    print "Hello, World!"; #Outputs "Luppy!" to STDERR

    ###Filter
    filter \*STDOUT, sub {uc(shift)}; #Make all output uppercase.
    print "Hello, World!\n"; #Outputs "HELLO, WORLD!"

    ###Reroute to a file
    reroute \*STDERR, ">error.log";
    warn "Arghh!"; #Prints "Arghh!" to error.log

    ###Fork
    fork_handle \*STDERR, ">>error.log";
    warn "Arghh!": #Prints the warning to STDERR *and* to error.log

    ###Capture to a scalar, array, or file
    my $myscalar;
    my $filter = reroute \*STDOUT, \$myscalar;
    print "Hello, World!";
    release_all_handlers \*STDOUT;
    print "Scalar is: $scalar\n"; #Outputs "Scalar is: Hello, World!"


    =head1 DESCRIPTION

    This module provides a convenient way to intercept, filter, reroute, and
    fork filehandles, without using the Perl tie interface.

    C<intercept> causes all output to the given handle to be intercepted and
    passed to the supplied handler subroutine.

    C<filter>, C<reroute>, and C<fork_handle> are implemented via C<intercept>.
    Look at the definition of these methods for a good example of how to use
    C<intercept>.

    This module has some cool features:

    - Multiple handlers can be chained.
    - Handlers can uninstall themselves.
    - Handler subroutines can access the handle they intercepted.

    =head2 Uninstalling a Handler

    If you install a hander with C<lexically_scoped> => 1 , then an object will
    be returned that will release the handler when it goes out of scope. You
    can also call C<release> on this object to acheive the same result.

    {
    my $filter = filter \*STDERR, sub { uc($_[0]) }, lexically_scoped => 1;
    print "foo"; #Prints "FOO"
    } #The handler uninstalls itself now that it's going out of scope.

    print "foo"; #Prints "foo"

    =head2 Chaining Handlers

    If you install a handler on a handle that already has a handler installed,
    the new handle will be installed "in front" of the original handler. For
    example:

    my $scalar;
    reroute \*STDOUT, \$scalar;
    filter \*STDOUT, sub { uc{$_[0]} };
    print "Hello, World!";

    #Result:
    $scalar eq "Hello, World!" or die "It didn't work!";


    =head2 Accessing the Original Filehandle

    The package variable C<$Tie::Handle::Intercepted::eek:riginal_handle> gives you
    a reference to the original handle. Examine the definition of the C<filter>
    below to see how this can be useful.

    sub filter {
    my($handle, $sub, %args) = @_;

    my $thing = intercept $handle, sub {
    my $return_value = &$sub(@_);
    print $original_handle $return_value;
    }, %args, keep_original => 1;
    }

    Don't worry, $original_handle uses the magic of Perl C<local> variables to
    ensure that it always contains the correct reference, even when chaining
    handlers.

    =cut
     
    John, May 6, 2004
    #1
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Carlo Filippini

    Tie a file handle to a variable

    Carlo Filippini, Sep 29, 2003, in forum: Perl
    Replies:
    1
    Views:
    455
  2. Guest

    Virus intercepted

    Guest, Sep 27, 2004, in forum: Python
    Replies:
    0
    Views:
    295
    Guest
    Sep 27, 2004
  3. Brian Candler

    RubyGarden wiki URLs being intercepted

    Brian Candler, Jul 20, 2005, in forum: Ruby
    Replies:
    1
    Views:
    138
    James Britt
    Jul 20, 2005
  4. botfood

    tie() with DB_File not tie()ing ?

    botfood, Apr 24, 2006, in forum: Perl Misc
    Replies:
    23
    Views:
    481
    botfood
    Apr 26, 2006
  5. Fazal
    Replies:
    1
    Views:
    102
    Stephen Chalmers
    Nov 11, 2005
Loading...

Share This Page