Geo::GeoNames::Record - Perl module for handling GeoNames.org records

    $rec->geonameid;

    $rec->geonameid = 123456;

package Geo::GeoNames::Record;

use 5.008007;
use strict;
use warnings;

require Exporter;

our @ISA = qw(Exporter);

our %EXPORT_TAGS = ( 'all' => [ qw() ] );

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );

our @EXPORT = qw( );

our $VERSION = '0.11';

use Carp ();
use Data::Dumper ();
use File::Basename ();
use Storable ();

## overloadings ##

use overload 
  q("") => \&as_string,
  q(eq) => \&op_eq,
  q(==) => \&op_eq,
  ;

## public static variables ##

our @fields = qw( geonameid name asciiname alternatenames latitude
		  longitude feature_class feature_code country_code cc2
		  admin1_code admin2_code admin3_code admin4_code
		  population elevation gtopo30 timezone modification_date
	       );

our $n_fields = @fields;

## public variables and corresponding member functions ##

my @_PUBLIC_VARIABLES = @fields;

foreach (@_PUBLIC_VARIABLES)
{
  eval "sub $_ : lvalue { shift->{$_}; }";
}

my %_PUBLIC_VARIABLE_ALIASES = ( id => 'geonameid' );

foreach (keys %_PUBLIC_VARIABLE_ALIASES)
{
  eval "sub $_ : lvalue { shift->{$_PUBLIC_VARIABLE_ALIASES{$_}}; }";
}

sub coordinates : lvalue
{
  my $self = shift;
  ($self->{latitude}, $self->{longitude});
}

## private static variables ##

my $_admins_loaded;
my $_admin_code_to_record;

sub new
{
  my $class = shift;

  my $self = bless {}, $class;

  @{$self}{@fields} = ();

  if ( @_ )
  {
    $self->parse( @_ );
  }

  return $self;
}

sub parse
{
  my ( $self, $str ) = @_;

  chomp($str);

  my @data = split /\t/, $str;

  if ( @data == $n_fields )
  {
    for ( my $i = 0; $i < $n_fields; $i++ )
    {
      $self->{$fields[$i]} = $data[$i];
    }
  }
  else
  {
    Carp::croak "Wrong number of GeoNames fields";
  }

  return $self;
}

sub names
{
  my $self = shift;

  my %saw;
  @saw{ ( $self->{name}, $self->{asciiname}, split(/,/, $self->{alternatenames}) ) } = ();

  return keys %saw;
}

sub has_name
{
  my ($self, $name) = @_;
  return ( grep { $_ eq $name; } $self->names() ) ? 1 : 0;
}

sub country
{
  _load_admins() unless $_admins_loaded;

  my $self = shift;
    
  if ( $self->{country_code} && exists( $_admin_code_to_record->{$self->{country_code}} ) )
  {
    return $_admin_code_to_record->{$self->{country_code}};
  }
    
  return;
}

sub admin1
{
  _load_admins() unless $_admins_loaded;

  my $self = shift;
    
  if ( $self->{admin1_code} )
  {
    my $admin1_key = $self->{country_code} . "." . $self->{admin1_code};

    if ( exists( $_admin_code_to_record->{$admin1_key} ) )
    {
      return $_admin_code_to_record->{$admin1_key};
    }
  }

  return;
}

sub admin2
{
  _load_admins() unless $_admins_loaded;

  my $self = shift;

  if ( $self->{admin2_code} )
  {
    my $admin2_key = $self->{country_code} . "." . $self->{admin1_code} . "." . $self->{admin2_code};

    if ( exists( $_admin_code_to_record->{$admin2_key} ) )
    {
      return $_admin_code_to_record->{$admin2_key};
    }
  }

  return;
}

sub as_string
{
  my $self = shift;

  return join( "\t", @{$self}{@fields} );
}

sub op_eq
{
  return ($_[0]->id eq $_[1]->id);
}

sub is_country
{
  my $self = shift;
  return ( $self->{feature_class} eq 'A' ) && ( $self->{feature_code} =~ /^P/ );
}

sub is_admin1
{
  my $self = shift;
  return ( $self->{feature_class} eq 'A' ) && ( $self->{feature_code} eq 'ADM1' );
}

sub is_admin2
{
  my $self = shift;
  return ( $self->{feature_class} eq 'A' ) && ( $self->{feature_code} eq 'ADM2' );
}

## private functions ##

# load data files for decoding country_code, admin1_code and admin2_code

sub _load_admins
{
  use File::HomeDir;
  use File::Spec;
  
  my $admins_filename = File::Spec->catfile( File::HomeDir->my_home(), 
					     ".Geo-GeoNames-Record", 
					     "admin_code_to_record.hash" );
  
  if( -e $admins_filename )
  {
    $_admin_code_to_record = Storable::retrieve( $admins_filename );
    $_admins_loaded = 1;
  }
  else
  {
    Carp::croak( "$admins_filename doesn't exist. Please run gn_update_admins first." );
  }
}

1;
__END__