view release on metacpan or  search on metacpan

CL.pm  view on Meta::CPAN

list_available_commands - List all the currently available commands.

=item *

package_is_available($package) - Slightly different from package_exists(), as it is less rigorous. It purely checks whether the package should exist, not whether it is actually defined.

=item *

command_is_available($command) - Similar to package_is_available() but for commands.

=back

=head2 Setting/Reading IRAF variables

These are similar in style to shell environment variables and last for the full length of the IRAF CL session. I have effectively overloaded a couple of the functions and added the exists() command.

=over 4

=item *

set(key1 => $value1, key2 => $value2, key3 => $value3) - set any number of variables to their associated values.

=item *

show($key) - returns the value of the variable.

=item *

exists($key) - checks for the existence of the variable, returns 1 or 0.

=back

=head2 Executing commands

There are two ways in which to execute IRAF CL commands, the full featured way provides error handling and time out capabilities, as seen below:

  $iraf->exec(command => 'print "hello world"',
         timeout => 10,
         timeout_handler => \&timeout_sub,
         death_handler => \&death_sub,
         error_handler => \&error_sub);

The second method I have named B<"direct invocation">, this is a much simpler method of calling an IRAF command, for example:

  $iraf->print('"hello world"')

Note here that strings where double-quotes are needed in IRAF should be protected from Perl with single-quotes. There are various ways to ensure the continued existence of quotes, see the perl documentation for examples.

The direct invocation method does not provide any system for defining exception handlers this may change in the future. There is, however, something to be said for keeping this simple method and the complex exec method for more explicitly defining co...

Note that some IRAF commands are overloaded in this module, for example, set() and show(). This allows the commands to be extended or made more Perl like, in general overloading commands may be a bad idea but for simple things like variable control i...

=head2 Error/Exception handling

As can be seen from the exec() example above references to subroutines can be passed in to deal with any problems that are encountered on execution of the command. A maximum run time (timeout) can be specified and a handler to deal with the timeout, ...

=over 4

=item *

B<Timeout handling>

By default a script will die upon timeout, this can be modified in anyway you like to keep the script going and handle the exception cleanly, an example of a handler is:

  my $timed_out = 0;
  $iraf->exec(command => 'print "hello"',
              timeout => 2,
              timeout_handler => sub {print $command . " timed out\n"; $timed_out = 1});

The script can then see from the $timed_out variable that the timeout has occured and can clean up accordingly and move on. Here i have used an anonymous subroutine instead of a reference to a subroutine as it is fairly small.

=item *

B<EOF/Death handling>

This is the situation when the whole CL interpreter has died, this is a not uncommon occurence with IRAF as some packages are not quite as robust as they should and the CL is quite fragile in certain situations. If have a large number of jobs to do y...

  $iraf->cd($workdir);
  $iraf->exec(command => 'print "hello"',
              death_handler => sub {$iraf->restart(); $iraf->cd($workdir)});

=item *

B<CL error handling>

A CL error is encountered when the command executed returns with the ERROR code and a message as to what happened. This is dealt with in the same way as the timeout handler above:

  my $error = 0;
  $iraf->exec(command => 'print "hello"',
              error_handler => sub {print "error occurred\n"; $error = 1});

=item *

B<CL warning handling>

There is currently no way to handle CL warnings, it is my intention to implement this feature at some point in the future.

=back

=head2 Ending and restarting

The CL object will automatically unload all packages and cleanly shut down the IRAF CL interpreter when your script ends or the object goes out of scope. You can force it to end by calling the end() function, i've never found this to be necessary tho...

=head2 Loading Tasks

  load_task(name => $name,         # Required
            task => $task,         # Not required
            file => $filename,     # Required
            parfile => $yes_or_no) # Defaults to no (zero)

If the task parameter is defined it is considered to contain the full text of the task and if the filename is also specified then the task is written into that file. If the task parameter is not specified the task is considered to be already containe...

  $iraf->load_task(name => 'hello_world',
                   task => 'print "hello world"',
                   file => 'hello_world.cl');

  $iraf->hello_world();

If you call the load_task command more than once with the same name then it will correctly redefine the task.

=head2 Logging the session