Astro::Coords::Angle - Representation of an angle

  use Astro::Coords::Angle;

  $ang = new Astro::Coords::Angle( 45.5, units => 'deg' );
  $ang = new Astro::Coords::Angle( "45:30:00", units => 'sexagesimal' );

  $rad = $ang->radians;
  $deg = $ang->degrees;
  $asec = $ang->arcsec;
  $amin = $ang->arcmin;
  $string = $ang->string;

package Astro::Coords::Angle;

use 5.006;
use strict;
use warnings;
use warnings::register;
use Carp;

use Scalar::Util qw/ looks_like_number /;
use Astro::SLA;

# Overloading
use overload 
  '""' => "stringify",
  '0+' => "numify",
  fallback => 1;

# Package Global variables
use vars qw/ $VERSION /;

$VERSION = '0.01';

sub new {
  my $proto = shift;
  my $class = ref($proto) || $proto;

  croak "Constructor for object of class $class must be called with an argument" unless @_;

  # first argument is the angle
  my $input_ang = shift;

  # optional hash, only read it if we have an even number of
  # remaining arguments
  my %args;
  if (@_) {
    if (scalar(@_) % 2 == 0) {
      %args = @_;
    } else {
      warnings::warnif("An odd number of Optional arguments were supplied to constructor");
    }
  }

  # Now need to convert this to radians (the internal representation)
  # Allow for inheritance
  my $rad = $class->_cvt_torad($input_ang, $args{units});

  croak "Unable to decode supplied angle ('$input_ang')"
    unless defined $rad;

  # Create the object
  my $ang = bless {
		   ANGLE => $rad,
		   RANGE => 'NONE',
		   NDP => undef,  # number of decimal places
		   DELIM => undef, # string delimiter
		  }, $class;

  # If a range was specified, normalise the angle
  $ang->range( $args{range} ) if exists $args{range};

  # And return the object
  return $ang;
}

sub radians {
  my $self = shift;
  return $self->{ANGLE};
}

# undocumented since we do not want a public way of changing the
# angle
sub _setRadians {
  my $self = shift;
  my $rad = shift;
  croak "Angle must be defined" unless defined $rad;
  $self->{ANGLE} = $rad;
}

sub degrees {
  my $self = shift;
  my $rad = $self->radians;
  return $rad * Astro::SLA::DR2D;
}

sub str_ndp {
  my $self = shift;
  if (@_) {
    $self->{NDP} = shift;
  }
  # A value has been requested. Do we have a local value
  # or should we return the default.
  if (defined $self->{NDP} ) {
    return $self->{NDP};
  } else {
    return $self->NDP;
  }
}

sub str_delim {
  my $self = shift;
  if (@_) {
    $self->{DELIM} = shift;
  }
  # A value has been requested. Do we have a local value
  # or should we return the default.
  if (defined $self->{DELIM} ) {
    return $self->{DELIM};
  } else {
    return $self->DELIM;
  }
}

sub components {
  my $self = shift;
  my $res = shift; # internal api

  # Get the angle in radians
  my $rad = $self->radians;

  # Convert to components using slalib. COCO uses 4 dp for high
  # resolution.
  $res = 5 unless defined $res;
  my @dmsf = $self->_r2f( $res );

  # Combine the fraction with the seconds unless no decimal places
  my $frac = pop(@dmsf);
  $dmsf[-1] .= sprintf( ".%0$res"."d",$frac) unless $res == 0;

  #use Data::Dumper;
  #print Dumper(\@dmsf);

  if (wantarray) {
    return @dmsf;
  } else {
    return \@dmsf;
  }

}

sub string {
  my $self = shift;

  # Get the components
  my $ndp = $self->str_ndp;
  my @dms = $self->components( $ndp );

  # Play it safe, and split the fractional part into two strings.
  # if ndp > 0
  if ( $ndp > 0 ) {
    my ($sec, $frac) = split(/\./,$dms[-1]);
    $dms[-1] = $sec;
    push(@dms, $frac);
  }

  # Now build the string.

  # Clear the + sign, setting it to empty string if the angle can never
  # go negative.
  my $sign = shift(@dms);
  if ($sign eq '+') {
    if ($self->range eq '2PI') {
      $sign = '';
    } else {
      $sign = ' ';
    }
  }

  # Get the delimiter
  my $delim = $self->str_delim;

  # Build the format

  # fractional part will not require a decimal place
  # if ndp is 0. If ndp>0 the fraction is formatted
  my $fracfmt = ( $ndp == 0 ? '' : '.%s' );

  # starting with the numeric part. Gal longitude will want %03d and no sign.
  # RA will want no sign and %02d. Dec wants sign with %02d.

  my @fmts = ( '%02d', '%02d', '%02d'.$fracfmt);
  my $fmt;
  if (length($delim) == 1) {
    $fmt = join($delim, @fmts );
  } else {
    my @chars = split (//, $delim );
    for my $f (@fmts) {
      $fmt .= $f . shift(@chars);
    }
  }

  return $sign . sprintf( $fmt, @dms);

}

sub arcsec {
  my $self = shift;
  my $rad = $self->radians;
  return $rad * Astro::SLA::DR2AS;
}

sub arcmin {
  my $self = shift;
  my $asec = $self->arcsec;
  return $asec / 60.0;
}

sub range {
  my $self = shift;
  if (@_) {
    my $rng = shift;
    if (defined $rng) {
      # upper case
      $rng = uc($rng);

      # get the current value for the angle
      my $rad = $self->radians;

      # Now check validity of string and normalise
      if ($rng eq 'NONE') {
	# do nothing apart from store it
      } elsif ($rng eq '2PI') {
	$self->_setRadians( Astro::SLA::slaDranrm( $rad ));
      } elsif ($rng eq 'PI') {
	$self->_setRadians( Astro::SLA::slaDrange( $rad ));
      } else {
	warnings::warnif("Supplied range '$rng' not recognized");
	return;
      }
      # store it
      $self->{RANGE} = $rng;
    } else {
      warnings::warnif("Supplied range was not defined");
    }
  }
  return $self->{RANGE};
}

sub in_format {
  my $self = shift;
  my $format = shift;

  # No format (including empty string), return the object
  return $self unless $format;
  $format = lc($format);

  if ($format =~ /^d/) {
    return $self->degrees;
  } elsif ($format =~ /^s/) {
    return $self->string();
  } elsif ($format =~ /^r/) {
    return $self->radians();
  } elsif ($format =~ /^arcm/ || $format eq 'am') {
    return $self->arcmin;
  } elsif ($format =~ /^arcs/ || $format eq 'as') {
    return $self->arcsec;
  } elsif ($format =~ /^a/) {
    return $self->components( 2 );
  } else {
    warnings::warnif("Unsupported format '$format'. Returning radians.");
    return $self->radians;
  }
}

sub clone {
  my $self = shift;
  return bless { %$self }, ref $self;
}

sub negate {
  my $self = shift;
  croak "Angle can not be negated since its range is 0 to 2PI"
    if $self->range eq '2PI';
  my $rad = $self->radians;
  return $self->new( $rad, units => 'radians', range => $self->range );
}

sub stringify {
  my $self = shift;
  return $self->string();
}

sub numify {
  my $self = shift;
  return $self->radians();
}

{
  my $DEFAULT_NDP = 2;
  my $NDP = $DEFAULT_NDP;
  sub NDP {
    my $class = shift;
    if (@_) { 
      my $arg = shift;
      if (defined $arg) {
	$NDP = $arg;
      } else {
	$NDP = $DEFAULT_NDP;
      }
    }
    return $NDP;
  }
}

{
  my $DEFAULT_DELIM = ":";
  my $DELIM = $DEFAULT_DELIM;
  sub DELIM {
    my $class = shift;
    if (@_) { 
      my $arg = shift;
      if (defined $arg) {
	$DELIM = $arg;
      } else {
	$DELIM = $DEFAULT_DELIM;
      }
    }
    return $DELIM;
  }
}

sub to_radians {
  my $class = shift;
  # simply delegate to the internal routine. Could use it directly but it feels
  # better to leave options open for the moment
  $class->_cvt_torad( @_ );
}

sub _cvt_torad {
  my $self = shift;
  my $input = shift;
  my $units = shift;

  return undef unless defined $input;

  # do we have an object?
  # and can it implement the radians() method?
  if (UNIVERSAL::can( $input, 'radians')) {
    return $input->radians;
  }

  # Clean up the string
  $input =~ s/^\s+//g;
  $input =~ s/\s+$//g;

  # guess the units
  unless (defined $units) {
    $units = $self->_guess_units( $input );
    croak "No units supplied, and unable to guess any units either"
      unless defined $units;
  }

  # Now process the input - starting with strings
  my $output = 0;
  if ($units =~ /^s/) {

    # Since we can support aritrary delimiters on write,
    # we should be flexible on read. Slalib is very flexible
    # once the numbers are space separated, so remove all
    # non-numeric characters except + and - and replace with space
    # For now, remove all alphabetic characters and colon only

    # Need to clean up the string for slalib
    $input =~ s/[:[:alpha:]]/ /g;

    my $nstrt = 1;
    Astro::SLA::slaDafin( $input, $nstrt, $output, my $j);
    $output = undef unless $j == 0;

    if ($j == -1) {
      warnings::warnif "In coordinate '$input' the degrees do not look right";
    } elsif ($j == -2) {
      warnings::warnif "In coordinate '$input' the minutes field is out of range";
    } elsif ($j == -3) {
      warnings::warnif "In coordinate '$input' the seconds field is out of range (0-59.9)";
    } elsif ($j == 1) {
      warnings::warnif "Unable to find plausible coordinate in string '$input'";
    }

  } elsif ($units =~ /^d/) {
    # Degrees decimal
    $output = $input * Astro::SLA::DD2R;

  } elsif ($units =~ /^arcs/ || $units eq 'as') {
    # Arcsec
    $output = $input * Astro::SLA::DAS2R;

  } elsif ($units =~ /^arcm/ || $units eq 'am') {
    # Arcmin
    $output = $input * Astro::SLA::DAS2R * 60 ;

  } else {
    # Already in radians
    $output = $input;
  }

  return $output;
}

sub _guess_units {
  my $self = shift;
  my $input = shift;
  return undef if !defined $input;

  # Now if we have a space, colon or alphabetic character
  # then we have a real string and assume sexagesimal.
  # Use pre-defined character classes
  my $units;
  # if it does not look like a number choose sexagesimal
  if (!looks_like_number($input)) {
    $units = "sexagesimal";
  } elsif ($input > Astro::SLA::D2PI) {
    $units = "degrees";
  } else {
    $units = "radians";
  }

  return $units;
}

sub _r2f {
  my $self = shift;
  my $res = shift;
  my @dmsf;
  Astro::SLA::slaDr2af($res, $self->radians, my $sign, @dmsf);
  return ($sign, @dmsf);
}

1;