File Coverage

lib/App/Info/Handler/Print.pm

Criterion	Covered	Total	%
statement	20	20	100.0
branch	6	6	100.0
condition	3	3	100.0
subroutine	5	5	100.0
pod	2	2	100.0
total	36	36	100.0

package App::Info::Handler::Print;

=head1 NAME

App::Info::Handler::Print - Print App::Info event messages

=head1 SYNOPSIS

  use App::Info::Category::FooApp;
  use App::Info::Handler::Print;

  my $stdout = App::Info::Handler::Print->new( fh => 'stdout' );
  my $app = App::Info::Category::FooApp->new( on_info => $stdout );

  # Or...
  my $app = App::Info::Category::FooApp->new( on_error => 'stderr' );

=head1 DESCRIPTION

App::Info::Handler::Print objects handle App::Info events by printing their
messages to a filehandle. This means that if you want event messages to print
to a file or to a system filehandle, you can easily do it with this class.
You'll find, however, that App::Info::Handler::Print is most effective for
info and error events; unknown and prompt events are better handled by event
handlers that know how to prompt users for data. See
L for an example of
that functionality.

Upon loading, App::Info::Handler::Print registers itself with
App::Info::Handler, setting up a couple of strings that can be passed to an
App::Info concrete subclass constructor. These strings are shortcuts that
tell App::Info how to create the proper App::Info::Handler::Print object
for handling events. The registered strings are:

=over 4

=item stdout

Prints event messages to C.

=item stderr

Prints event messages to C.

=back

See the C constructor below for how to have App::Info::Handler::Print
print event messages to different filehandle.

=cut

use strict;
use App::Info::Handler;
use vars qw($VERSION @ISA);
$VERSION = '0.57';
@ISA = qw(App::Info::Handler);

# Register ourselves.
for my $c (qw(stderr stdout)) {
    App::Info::Handler->register_handler
      ($c => sub { __PACKAGE__->new( fh => $c ) } );
}

=head1 INTERFACE

=head2 Constructor

=head3 new

  my $stderr_handler = App::Info::Handler::Print->new;
  $stderr_handler = App::Info::Handler::Print->new( fh => 'stderr' );
  my $stdout_handler = App::Info::Handler::Print->new( fh => 'stdout' );
  my $fh = FileHandle->new($file);
  my $fh_handler = App::Info::Handler::Print->new( fh => $fh );

Constructs a new App::Info::Handler::Print and returns it. It can take a
single parameterized argument, C, which can be any one of the following
values:

=over 4

=item stderr

Constructs a App::Info::Handler::Print object that prints App::Info event
messages to C.

=item stdout

Constructs a App::Info::Handler::Print object that prints App::Info event
messages to C.

=item FileHandle

=item GLOB

Pass in a reference and App::Info::Handler::Print will assume that it's a
filehandle reference that it can print to. Note that passing in something that
can't be printed to will trigger an exception when App::Info::Handler::Print
tries to print to it.

=back

If the C parameter is not passed, C will default to creating an
App::Info::Handler::Print object that prints App::Info event messages to
C.

=cut

sub new {
    my $pkg = shift;
    my $self = $pkg->SUPER::new(@_);
    if (!defined $self->{fh} || $self->{fh} eq 'stderr') {
        # Create a reference to STDERR.
        $self->{fh} = \*STDERR;
    } elsif ($self->{fh} eq 'stdout') {
        # Create a reference to STDOUT.
        $self->{fh} = \*STDOUT;
    } elsif (!ref $self->{fh}) {
        # Assume a reference to a filehandle or else it's invalid.
        Carp::croak("Invalid argument to new(): '$self->{fh}'");
    }
    # We're done!
    return $self;
}

##############################################################################

=head3 handler

This method is called by App::Info to print out the message from events.

=cut

sub handler {
    my ($self, $req) = @_;
    print {$self->{fh}} $req->message, "\n";
    # Return true to indicate that we've handled the request.
    return 1;
}

1;
__END__