Weather::Com::Finder - finder class to search for I<weather.com> location's

  #!/usr/bin/perl -w
  use Weather::Com::Finder;

  # you have to fill in your ids from weather.com here
  my $PartnerId  = 'somepartnerid';
  my $LicenseKey = 'mylicense';

  my %weatherargs = (
	'partner_id' => $PartnerId,
	'license'    => $LicenseKey,
  );

  my $finder = Weather::Com::Finder->new(%weatherargs);

  # if you want an array of locations:
  my @locations = $finder->find('Heidelberg');

  # or if you prefer an arrayref:
  my $locations = $finder->find('Heidelberg');

  foreach my $location (@locations) {
    print "Found weather for city: ", $location->name(), "\n";
    print "Current Conditions are ", 
      $location->current_conditions()->description(), "\n";
  }

package Weather::Com::Finder;

use 5.006;
use strict;
use warnings;
use Carp;
use Data::Dumper;
use Weather::Com::Cached;
use Weather::Com::Location;

our $VERSION = sprintf "%d.%03d", q$Revision: 1.8 $ =~ /(\d+)/g;

#------------------------------------------------------------------------
# Constructor
#------------------------------------------------------------------------
sub new {
	my $proto      = shift;
	my $class      = ref($proto) || $proto;
	my $self       = {};
	my %parameters = ();

	# parameters provided by new method
	if ( ref( $_[0] ) eq "HASH" ) {
		%parameters = %{ $_[0] };
	} else {
		%parameters = @_;
	}

	# god, bless the object
	$self = bless( $self, $class );

	# Weather::Com::Cached object for searching
	my %weatherargs = ();
	
	# define proxy args
	$weatherargs{proxy} = $parameters{proxy} if ( $parameters{proxy} );
	$weatherargs{proxy_user} = $parameters{proxy_user}
	  if ( $parameters{proxy_user} );
	$weatherargs{proxy_pass} = $parameters{proxy_pass}    
	  if ( $parameters{proxy_pass} );
	  
	# other weather arguments...
	$weatherargs{units}   = $parameters{units}   if ( $parameters{units} );
	$weatherargs{debug}   = $parameters{debug}   if ( $parameters{debug} );
	$weatherargs{cache}   = $parameters{cache}   if ( $parameters{cache} );
	$weatherargs{timeout} = $parameters{timeout} if ( $parameters{timeout} );
	$weatherargs{partner_id} = $parameters{partner_id}
	  if ( $parameters{partner_id} );
	$weatherargs{license} = $parameters{license} if ( $parameters{license} );
	$weatherargs{language} = $parameters{language} if ( $parameters{language} );	

	# initialize weather object
	$self->{ARGS}    = \%weatherargs;
	$self->{WEATHER} = Weather::Com::Cached->new(%weatherargs);

	return $self;
}    # end new()

#------------------------------------------------------------------------
# find weather
#------------------------------------------------------------------------
sub find {
	my $self      = shift;
	my $locString = shift;

	# search locations
	my $loc_weather = $self->{WEATHER}->search($locString);
	unless ($loc_weather) {
		$self->_debug("No location found using '$locString' for search!");
		return 0;
	}

	# create a Weather::Com::Location for each location found
	my @locations = ();
	foreach ( keys %{$loc_weather} ) {
		my %weatherargs = %{ $self->{ARGS} };
		$weatherargs{location_id} = $_;
		$weatherargs{location_name} = $loc_weather->{$_};
		
		my $location = Weather::Com::Location->new(%weatherargs);
		push( @locations, $location );
	}

	$self->_debug("Location Objects: " . Dumper(\@locations));

	# return an array if called in list context or a scalar
	# if called in void or scalar context
	
	unless(@locations) {
		return undef;
	} elsif ( wantarray() ) {
		return @locations;
	} else {
		return \@locations;
	}
}

#------------------------------------------------------------------------
# other internals
#------------------------------------------------------------------------
sub _debug {
	my $self   = shift;
	my $notice = shift;
	if ( $self->{ARGS}->{debug} ) {
		carp ref($self) . " DEBUG NOTE: $notice\n";
		return 1;
	}
	return 0;
}

1;

__END__