NAME
    Hook::Output::File - Redirect STDOUT/STDERR to a file

SYNOPSIS
     use Hook::Output::File;

     {
         my $hook = Hook::Output::File->redirect(
             stdout => '/tmp/1.out',
             stderr => '/tmp/2.out',
         );
     
         saved();
     
         undef $hook; # restore previous state of streams 
     
         not_saved();
     }

     sub saved {
         print STDOUT "..."; # STDOUT output is appended to file
         print STDERR "..."; # STDERR output is appended to file
     }

     sub not_saved {
         print STDOUT "..."; # STDOUT output goes to STDOUT (not to file)
         print STDERR "..."; # STDERR output goes to STDERR (not to file)
     }

DESCRIPTION
    "Hook::Output::File" redirects "STDOUT/STDERR" to a file.

METHODS
  redirect
    Installs a file-redirection hook for regular output streams (i.e.,
    "STDOUT & STDERR") with lexical scope.

    A word of caution: do not intermix the file paths for "STDOUT/STDERR"
    output or you will eventually receive unexpected results. The paths will
    be checked that they are absolute and if not, an usage help will be
    printed (because otherwise, the "open()" call might silently fail to
    satisfy expectations).

    The hook may be uninstalled either explicitly or implicitly; doing it
    explicit requires to unset the hook "variable" (more concisely, it is a
    blessed object), whereas the implicit end of the hook will automatically
    be triggered when leaving the scope the hook was defined in.

     {
         my $hook = Hook::Output::File->redirect(
             stdout => '/tmp/1.out',
             stderr => '/tmp/2.out',
         );
     
         some_sub();

         undef $hook; # explicitly remove hook

         another_sub();
     }
     ... # hook implicitly removed 

BUGS & CAVEATS
    Does not work in a forked environment, such as the case with daemons.

SEE ALSO
    perltie

AUTHOR
    Steven Schubiger <schubiger@cpan.org>

LICENSE
    This program is free software; you may redistribute it and/or modify it
    under the same terms as Perl itself.

    See <http://www.perl.com/perl/misc/Artistic.html>