=head1 NAME
IO::Mux::Pipe::Read - read from an external command
=head1 INHERITANCE
IO::Mux::Pipe::Read
is a IO::Mux::Handler::Read
is a IO::Mux::Handler
=head1 SYNOPSIS
my $mux = IO::Mux::Select->new; # or ::Poll
use IO::Mux::Open '-|';
my $pipe = $mux->open('-|', $command, @cmd_options);
my $pipe = IO::Mux::Pipe::Read->new
( command => [$command, @cmd_options] );
$mux->add($pipe);
$pipe->getline(sub {print "$_[0]\n"});
=head1 DESCRIPTION
In an event driven program, reading is harder to use than writing: the
read will very probably be stalled until data has arrived, so you will
need a callback to handle the resulting data.
=head1 METHODS
=head2 Constructors
=over 4
=item IO::Mux::Pipe::Read-E<gt>B<bare>(OPTIONS)
Creates a pipe, but does not start a process (yet). Used by
L<IO::Mux::IPC|IO::Mux::IPC>, which needs three pipes for one process. Returned
is not only a new pipe object, but also a write handle to be
connected to the other side.
All OPTIONS which are available to L<IO::Mux::Handler::Read::new()|IO::Mux::Handler::Read/"Constructors">
can be used here as well.
-Option --Default
read_size 4096
=over 2
=item read_size => INTEGER
=back
example:
my ($out, $out_rh)
= IO::Mux::Pipe::Read->bare(name => 'stdout');
=item IO::Mux::Pipe::Read-E<gt>B<new>(OPTIONS)
-Option --Defined in --Default
command <required>
fh IO::Mux::Handler <required>
name IO::Mux::Handler '$cmd|'
read_size IO::Mux::Handler::Read 4096
=over 2
=item command => COMMAND|ARRAY
The external command to be executed. Either the COMMAND needs to
parameters, or you need to pass an ARRAY of the command name and
all its parameters.
=item fh => FILEHANDLE
=item name => STRING
=item read_size => INTEGER
=back
=item IO::Mux::Pipe::Read-E<gt>B<open>(MODE, (CMD, CMDOPTS)|(CMDARRAY, OPTIONS))
Open the pipe to read. MODE is always C<< -| >>. When you need to
pass additional OPTIONS to the implied L<new()|IO::Mux::Pipe::Read/"Constructors">, then you must use
an ARRAY for command name and its optional parameters.
example:
my $mux = IO::Mux::Poll->new;
$mux->open('-|', 'who', '-H'); # no opts
$mux->open('-|', ['who', '-H'], %opts);
$mux->open('-|', 'who'); # no opts
$mux->open('-|', ['who'], %opts);
=back
=head2 Accessors
=over 4
=item $obj-E<gt>B<childPid>
The process id of the child on the other side of the pipe.
=item $obj-E<gt>B<fh>
See L<IO::Mux::Handler/"Accessors">
=item $obj-E<gt>B<fileno>
See L<IO::Mux::Handler/"Accessors">
=item $obj-E<gt>B<mode>
The bits of the open mode.
=item $obj-E<gt>B<mux>
See L<IO::Mux::Handler/"Accessors">
=item $obj-E<gt>B<name>
See L<IO::Mux::Handler/"Accessors">
=item $obj-E<gt>B<readSize>([INTEGER])
See L<IO::Mux::Handler::Read/"Accessors">
=item $obj-E<gt>B<usesSSL>
See L<IO::Mux::Handler/"Accessors">
=back
=head2 User interface
=head3 Connection
=over 4
=item $obj-E<gt>B<close>([CALLBACK])
See L<IO::Mux::Handler/"Connection">
=item $obj-E<gt>B<timeout>([TIMEOUT])
See L<IO::Mux::Handler/"Connection">
=back
=head3 Reading
=over 4
=item $obj-E<gt>B<readline>(CALLBACK)
See L<IO::Mux::Handler::Read/"Reading">
=item $obj-E<gt>B<slurp>(CALLBACK)
See L<IO::Mux::Handler::Read/"Reading">
=back
=head2 Multiplexer
=head3 Connection
=over 4
=item $obj-E<gt>B<mux_init>(MUX, [HANDLER])
See L<IO::Mux::Handler/"Connection">
=item $obj-E<gt>B<mux_remove>
See L<IO::Mux::Handler/"Connection">
=item $obj-E<gt>B<mux_timeout>
See L<IO::Mux::Handler/"Connection">
=back
=head3 Reading
=over 4
=item $obj-E<gt>B<mux_eof>(INPUT)
See L<IO::Mux::Handler::Read/"Reading">
=item $obj-E<gt>B<mux_except_flagged>(FILENO)
See L<IO::Mux::Handler/"Reading">
=item $obj-E<gt>B<mux_input>(BUFFER)
See L<IO::Mux::Handler::Read/"Reading">
=item $obj-E<gt>B<mux_read_flagged>(FILENO)
See L<IO::Mux::Handler/"Reading">
=back
=head3 Writing
=over 4
=item $obj-E<gt>B<mux_write_flagged>(FILENO)
See L<IO::Mux::Handler/"Writing">
=back
=head3 Service
=head2 Helpers
=over 4
=item $obj-E<gt>B<extractSocket>(HASH)
=item IO::Mux::Pipe::Read-E<gt>B<extractSocket>(HASH)
See L<IO::Mux::Handler/"Helpers">
=item $obj-E<gt>B<fdset>(STATE, READ, WRITE, ERROR)
See L<IO::Mux::Handler/"Helpers">
=item $obj-E<gt>B<show>
See L<IO::Mux::Handler/"Helpers">
=back
=head1 SEE ALSO
This module is part of IO-Mux distribution version 0.11,
built on January 26, 2011. Website: F<http://perl.overmeer.net/>
All modules in this suite:
L</Any::Daemon>,
L</IO::Mux>, and
L</IO::Mux::HTTP>.
Please post questions or ideas to F<perl@overmeer.net>
=head1 LICENSE
Copyrights 2011 by Mark Overmeer. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.