=for comment POD_DERIVED_INDEX_GENERATED
The following documentation is automatically generated.  Please do not edit
this file, but rather the original, inline with IO::AsyncX::System
at lib/IO/AsyncX/System.pm
(on the system that originally ran this).
If you do edit this file, and don't want your changes to be removed, make
sure you change the first line.

=cut

=head1 NAME

IO::AsyncX::System - fork+exec, capturing STDOUT/STDERR

=head1 VERSION

version 0.003

=head1 SYNOPSIS

 use feature qw(say);
 use IO::Async::Loop;
 use IO::AsyncX::System;
 my $loop = IO::Async::Loop->new;
 $loop->add(
  my $system = IO::AsyncX::System->new
 );
 my ($code, $stdout, $stderr) = $system->run([qw(ls)])->get;
 say for @$stdout;

=head1 DESCRIPTION

Intended as a replacement for L</system> in L<IO::Async>-using code.
Provides a single L</run> method which will fork+exec (via L<IO::Async::Process>),
capturing STDOUT/STDERR, and returning a L<Future> holding the exit code and output.

=head1 METHODS

=head2 run

Takes a single parameter defining the command to run:

 $system->run(['ls']);

plus optional named parameters:

=over 4

=item * utf8 - interprets all input/output as UTF-8, so STDOUT/STDERR will be returned as arrayrefs containing Perl strings rather than raw bytes

=item * binary - the reverse of utf8 (and the default)

=item * stdin - an arrayref of data to pass as STDIN

=item * timeout - kill the process if it doesn't complete within this many seconds

=back

Returns a L<Future> which resolves to the exit code, STDOUT and STDERR arrayrefs:

 $system->run([...]) ==> ($exitcode, $stdout_arrayref, $stderr_arrayref)

STDIN/STDOUT/STDERR are arrayrefs split by line. In binary mode, they will hold a single element each.

=head1 SEE ALSO

=over 4

=item * L<IO::Async::Process>

=item * L<system>

=item * L<Capture::Tiny>

=item * L<IPC::Run>

=back

=head1 INHERITED METHODS

=over 4

=item L<IO::Async::Notifier>

L<add_child|IO::Async::Notifier/add_child>, L<adopt_future|IO::Async::Notifier/adopt_future>, L<can_event|IO::Async::Notifier/can_event>, L<children|IO::Async::Notifier/children>, L<configure|IO::Async::Notifier/configure>, L<configure_unknown|IO::Async::Notifier/configure_unknown>, L<debug_printf|IO::Async::Notifier/debug_printf>, L<get_loop|IO::Async::Notifier/get_loop>, L<invoke_error|IO::Async::Notifier/invoke_error>, L<invoke_event|IO::Async::Notifier/invoke_event>, L<loop|IO::Async::Notifier/loop>, L<make_event_cb|IO::Async::Notifier/make_event_cb>, L<maybe_invoke_event|IO::Async::Notifier/maybe_invoke_event>, L<maybe_make_event_cb|IO::Async::Notifier/maybe_make_event_cb>, L<new|IO::Async::Notifier/new>, L<notifier_name|IO::Async::Notifier/notifier_name>, L<parent|IO::Async::Notifier/parent>, L<remove_child|IO::Async::Notifier/remove_child>, L<remove_from_parent|IO::Async::Notifier/remove_from_parent>

=back

=head1 AUTHOR

Tom Molesworth <cpan@perlsite.co.uk>

=head1 LICENSE

Copyright Tom Molesworth 2015. Licensed under the same terms as Perl itself.
