view release on metacpan or  search on metacpan

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

package App::Framework::Feature::Run ;

=head1 NAME

App::Framework::Feature::Run - Execute external commands

=head1 SYNOPSIS

  use App::Framework '+Run' ;

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


=head1 DESCRIPTION

Provides for external command running from within an application.

An external conmmand may be run using this feature, and the output from the command may be returned for additional processing. The feature
also provides timed execution (aborting after a certain time), exit code status, and callbacks that can be defined to be called during execution
and/or after program completion.

=head2 Arguments

The access method for this feature (called as B<$app-E<gt>run()>) allows the complete run settings to be specified as a HASH. The call sets 
the object L</FIELDS> from the values in this HASH, for example:

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

which specifies the command to run along with the L</progress> field (a callback).

A simpler alternative is allowed:

  $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