view release on metacpan or  search on metacpan

lib/App/Framework/Feature/Run.pm  view on Meta::CPAN

  $app->run("perl t/test/runtest.pl", "some args") ;

or:

  $app->run("perl t/test/runtest.pl some args") ;

The command arguments can be specified either as part of the L</cmd> field definition, or separately in the L</args> field. One benefit of using
the L</args> field is that the command need only be specified once - subsequent calls will use the same setting, for example:

  $app->run('cmd' => "perl t/test/runtest.pl"); 
  $app->run('progress' => \&progress);
  $app->run('progress' => \&progress);

=head2 Return code

When the external command completes, it's return code can be accessed by reading the L</status> field:

  $app->run()->status ;
  
This value is set in the feature object to the result of the last run (i.e. you must save status values between runs if you want to
keep track of the values).

The status value is entirely defined by the external command and the operating system.

Also, if you want your script to automatically abort on error (rather than write your own program error handler) then you can set the 
B<on_error> field to 'fatal'.

=head2 Required Programs Check

It's a good idea to start your script with a check for all the external programs you're about to use. You can do this by specifying them
in a HASH ref using the L</required> method. This does the checking for you, returning the path of all the executables. You can also
tell the object to abort the script if some programs are not found, for example:

  $app->run->set(
      'on_error'   => 'fatal',
      'required'   => {
          'lsvob'      => 1,
          'ffmpeg'     => 1,
          'transcode'  => 1,
          'vlc'        => 1,	
      },
  ) ;

NOTE: The values you specify along with the program names are not important when you set the required list - these values get updated
with the actual executable path.

=head2 Command output

All output (both STDOUT and STDERR) is captured from the external command and can be accessed by reading the L</results> field. This returns
an ARRAY reference, where the ARRAY contains the lines of text output (one array entry per line).

NOTE: the lines have the original trailing newline B<removed>.

  my $results_aref = $app->run()->results ;
  foreach my $line (@$results_aref)
  {
      print "$line\n";
  }

=head2 Timeout

If you specify a L</timeout> then the command is executed as normal but will be aborted if it runs for longer than the specified time.

This can be useful, for example, for running commands that don't normally terminate (or run on much longer than is necessary). 
 

=head2 Callbacks

There are 2 optional callback routines that may be specified:

=over 4 

=item B<progress> 

This subroutine is called for every line of output from the external command. This can be used in an application for monitoring 
progress, checking for errors etc.

=item B<check_results> 

This subroutine is called at the end of external command completion. It allows the application to process the results to determine whether
the command passed or failed some additional criteria. The L</status> field is then set to the results of this subroutine.

=back


=head2 Examples

Run a command:

    $app->run(
        'cmd'         => "perl t/test/runtest.pl", 
    ) ;

Run a command and get a callback for each line of output:
    
    $app->run(
        'cmd'         => "perl t/test/runtest.pl", 
        'progress'    => \&progress,
    ) ;

Ping a machine for 10 seconds and use a callback routine to check the replies:

    my $run_for = 10 ;
    my $host = '192.168.0.1' ;
    my $run = $app->run() ;
    $run->run_cmd("ping", 
        'progress' => \&progress,
        'args'     => "$host",
        'timeout'  => $run_for,
    ) ;

Note the above example uses the B<run> feature object to access it's methods directly.

=cut

use strict ;
use Carp ;

use File::Which ;