view release on metacpan or  search on metacpan

lib/Astro/PAL.pm  view on Meta::CPAN

=head1 Routines

There are 3 distinct groups of routines that can be imported into
the namespace via tags:

=over 4

=item pal - import just the PAL routines

=item constants - import the PAL constants

=item funcs - import the extra routines

=back

Each group will be discussed in turn.

=head2 PAL

The PAL routines directly match the C API with the caveat that returned
values are returned on the perl argument stack rather than being modified
directly in the call arguments. Arguments are never modified. This differs
from the Astro::SLA wrapper around the SLALIB library.

For example,

  ($xi, $eta, $j) = palDst2p( $ra, $dec, $raz, $decz );
  @pv = palDmoon( $date );
  ($nstrt, $fd, $j) = palDafin( $time, $nstrt );


If a routine returns an array as well as a status the status value
is returned first:

 ($j, @iymsf) = palDjcal( $ndp, $djm );

If a routine returns multiple arrays they are returned as references:

 ($dvb, $dpb, $dvh, $dph) = palEvp( $date, $deqx );
 @dvbarr = @$dvb;

Routines that take vectors or matrices should be given references
to arrays:

 @rmatn = palNut( $djtt );
 @mposr = palDmxv( \@rmatn, \@mpos );

See the PAL or SLALIB documentation for details of the functions
themselves.

=head3 Anomalies

=over 4

=item palObs

palObs is special in that it returns an empty list if the return
status is bad. Additionally, palObs is called with a single
argument and the behaviour depends on whether the argument looks
like an integer or a string.

 ($ident, $name, $w, $p, $h) = palObs( 27 );
 ($ident, $name, $w, $p, $h) = palObs( "JCMT" );

=cut

# We need a local version of palObs that converts the single
# argument to the right form for the internal XS implementation

sub palObs {
  my $arg = shift;
  return () unless defined $arg;

  my $n = 0;
  my $c = "";

  if ( $arg =~ /^\d+$/) {
    $n = $arg;
  } else {
    $c = $arg;
  }

  return _palObs( $n, $c );
}

=item palAopqk

palAopqk can be called either with a reference to an
array or a list

  @results = palAopqk( $rap, $dap, @aoprms );
  @results = palAopqk( $rap, $dap, \@aoprms );

=cut

# Sanity check argument counting before passing to XS layer

sub palAopqk {
  my $rap = shift;
  my $dap = shift;

  my @aoprms;
  if (@_ > 1) {
    @aoprms = @_;
  } else {
    @aoprms = @{$_[0]};
  }
  croak "palAopqk: Need 14 elements in star-independent apparent to observed array"
    unless @aoprms == 14;

  return pal_Aopqk( $rap, $dap, \@aoprms );
}

=item palAoppat

For the C API the calling convention is to modify the AOPRMS array in
place, for the perl API we accept the AOPRMS array but return the
updated version.