view release on metacpan or  search on metacpan

lib/App/Info/Handler/Print.pm  view on Meta::CPAN

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<App::Info::Handler::Prompt|App::Info::Handler::Prompt> 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<STDOUT>.

=item stderr

Prints event messages to C<STDERR>.

=back

See the C<new()> 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<fh>, 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<STDERR>.