package WebService::Audioscrobbler::Artist;
use warnings;
use strict;
use CLASS;
use base 'WebService::Audioscrobbler::Base';
=head1 NAME
WebService::Audioscrobbler::Artist - An object-oriented interface to the Audioscrobbler WebService API
=cut
our $VERSION = '0.07';
# postfix related accessors
CLASS->mk_classaccessor("base_resource_path" => "artist");
# similar artists related accessors
CLASS->mk_classaccessor("similar_artists_postfix" => "similar.xml");
CLASS->mk_classaccessor("similar_artists_class" => "WebService::Audioscrobbler::SimilarArtist");
# change the field used to sort stuff
CLASS->tracks_sort_field('reach');
# requiring stuff
CLASS->similar_artists_class->require or die($@);
CLASS->tracks_class->require or die($@);
CLASS->tags_class->require or die($@);
# object accessors
CLASS->mk_accessors(qw/name mbid streamable picture_url/);
=head1 SYNOPSIS
This module implements an object oriented abstraction of an artist within the
Audioscrobbler database.
use WebService::Audioscrobbler;
my $ws = WebService::Audioscrobbler->new;
# get an object for artist named 'foo'
my $artist = $ws->artist('foo');
# fetch artists similar to 'foo'
my @similar = $artist->similar_artists;
print "Artists similar to: " . $artist->name . "\n";
# prints each one of their names
for my $similar (@similar) {
print $similar->name . "\n";
}
# retrieves tracks from 'foo'
my @tracks = $artist->tracks;
# retrieves tags associated with 'foo'
my @tags = $artist->tags;
This module inherits from L<WebService::Audioscrobbler::Base>.
=head1 FIELDS
=head2 C<name>
The name of a given artist as provided when constructing the object.
=head2 C<mbid>
MusicBrainz ID as provided by the Audioscrobbler database.
=head2 C<picture_url>
URI object pointing to the location of the artist's picture, if available.
=head2 C<streamable>
Flag indicating whether the artist has streamable content available.
=cut
=head1 METHODS
=cut
=head2 C<new($artist_name, $data_fetcher)>
=head2 C<new(\%fields)>
Creates a new object using either the given C<$artist_name> or the C<\%fields>
hashref. The data fetcher object is a mandatory parameter and must
be provided either as the second parameter or inside the C<\%fields> hashref.
=cut
sub new {
my $class = shift;
my ($name_or_fields, $data_fetcher) = @_;
my $self = $class->SUPER::new(
ref $name_or_fields eq 'HASH' ?
$name_or_fields : { name => $name_or_fields, data_fetcher => $data_fetcher }
);
$self->croak("No data fetcher provided")
unless $self->data_fetcher;
unless (defined $self->name) {
if (defined $self->{content}) {
$self->name($self->{content});
}
else {
$class->croak("Can't create artist without a name");
}
}
return $self;
}
=head2 C<similar_artists([$filter])>
=head2 C<related_artists([$filter])>
=head2 C<artists([$filter])>
Retrieves similar artists from the Audioscrobbler database. $filter can be used
to limit artist with a low similarity index (ie. artists which have a similarity
index lower than $filter won't be returned).
Returns either a list of artists or a reference to an array of artists when called
in list context or scalar context, respectively. The artists are returned as
L<WebService::Audioscrobbler::SimilarArtist> objects by default.
=cut
*related_artists = *artists = \&similar_artists;
sub similar_artists {
my $self = shift;
my $filter = shift || 1;
my $data = $self->fetch_data($self->similar_artists_postfix);
$self->load_fields($data);
my @artists;
# check if we've got any similar artists
if (ref $data->{artist} eq 'ARRAY') {
shift @{$data->{artist}};
@artists = map {
my $artist = $_;
$self->similar_artists_class->new({
picture_url => URI->new($_->{image}),
related_to => $self,
data_fetcher => $self->data_fetcher,
map {$_ => $artist->{$_}} qw/name streamable mbid match/
})
} grep { $_->{match} >= $filter } @{$data->{artist}};
}
return wantarray ? @artists : \@artists;
}
=head2 C<tracks>
Retrieves the artist's top tracks as available on Audioscrobbler's database.
Returns either a list of tracks or a reference to an array of tracks when called
in list context or scalar context, respectively. The tracks are returned as
L<WebService::Audioscrobbler::Track> objects by default.
=cut
=head2 C<tags>
Retrieves the artist's top tags as available on Audioscrobbler's database.
Returns either a list of tags or a reference to an array of tags when called
in list context or scalar context, respectively. The tags are returned as
L<WebService::Audioscrobbler::Tag> objects by default.
=cut
=head2 C<load_fields(\%data)>
Loads artist fields from the hashref C<\%data>.
=cut
sub load_fields {
my $self = shift;
my $data = shift;
$self->streamable($data->{streamable});
$self->picture_url(URI->new($data->{picture}))
unless $self->picture_url;
$self->mbid($data->{mbid})
unless $self->mbid;
}
=head2 C<resource_path>
Returns the URL from which other URLs used for fetching artist info will be
derived from.
=cut
sub resource_path {
my $self = shift;
$self->uri_builder( $self->name );
}
=head1 AUTHOR
Nilson Santos Figueiredo Júnior, C<< <nilsonsfj at cpan.org> >>
=head1 COPYRIGHT & LICENSE
Copyright 2006-2007 Nilson Santos Figueiredo Júnior, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
=cut
1; # End of WebService::Audioscrobbler::Artist