=pod

=for vim
   vim: tw=72 ts=3 sts=3 sw=3 et ai :

=encoding utf8

=head1 NAME

Command::Template::Runner


=head1 SYNOPSIS

   use Command::Template::Instance;
   use Command::Template::Runner;

   my @command = qw{ ls [options=-l] <dir> };
   my $instance = Command::Template::Instance->new(@command);
   my $runner   = Command::Template::Runner->new($instance);

   # run command qw< ls -l / >, returns a Command::Template::RunRecord
   my $r = $runner->run(dir => '/');
   my $run_successful  = $r->success;
   my $exit_code       = $r->exit_code; # 0 is OK as usual in UNIX
   my $received_signal = $r->signal;    # e.g. if killed, ...
   my $stdout          = $r->stdout;
   my $stderr          = $r->stderr;
   my $merged          = $r->merged; # stderr then stdout, no newlines


=head1 DESCRIPTION

This class allows running commands generated by a
L<Command::Template::Instance> object, by means of L<IPC::Run>.

=head1 INTERFACE

=head2 B<< instance >>

   my $instance = $obj->instance;

Returns a reference to the L<Command::Template::Instance> object used to
generate the commands that are then executed.

=head2 B<< last_run >>

   my $run = $obj->last_run;

Returns the L<Command::Template::Runner::Record> object of the last run
(i.e. the same returned by the last call to the L</run> method).

=head2 B<< new >>

   my $runner = Command::Template::Runner->new($instance);

Constructor. Accepts a single parameter, that is supposed to support the
interface provided by L<Command::Template::Instance> (in particular, to
support its L<Command::Template::Instance/generate> method).

=head2 B<< options >>

   my $href = $obj->options;
   $obj->options({ ... });

Get/set the options for running. Options are represented by a hash
reference with the following keys:

=over

=item C<stdin>

a string holding the standard input to provide to the command;

=item C<timeout>

a timeout for running the command.

=back

=head2 B<< run >>

   my $record = $obj->run(%bindings_or_options);

Run a command using L<IPC::Run>:

The input hash C<%bindings_or_options> is first divided into I<bindings>
and I<options>; the latter are set with a leading C<-> character (e.g.
C<-stdin> is used to the standard input, while C<-timeout> to set the
timeout; also see L</options>).

The I<bindings> are used to generate the actual command using the
L<Command::Template::Instance> object held by L</instance>; this command
is then executed with the provided options (defaulting to those set via
L</options>), leveraging L<IPC::Run>.

The outcome of the call is wrapped into a
L<Command::Template::Runner::Record> object and returned. It is also
later available via method L</last_run>.


=head1 ANYTHING ELSE (INCLUDING AUTHOR, COPYRIGHT AND LICENSE)

See documentation for Command::Template.


=cut
