| 1 | package WebService::Audioscrobbler; | ||||||||||
| 2 | 2 | ▶ | use warnings; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 3 | 2 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 4 | 2 | ▶ | use CLASS; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 5 | |||||||||||
| 6 | 2 | ▶ | use base 'Class::Data::Accessor'; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 7 | 2 | ▶ | use base 'Class::Accessor::Fast'; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 8 | |||||||||||
| 9 | 2 | ▶ | use NEXT; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 10 | 2 | ▶ | use UNIVERSAL::require; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 11 | |||||||||||
| 12 | 2 | ▶ | use URI; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 13 | |||||||||||
| 14 | =head1 NAME | ||||||||||
| 15 | |||||||||||
| 16 | WebService::Audioscrobbler - An object-oriented interface to the Audioscrobbler WebService API | ||||||||||
| 17 | |||||||||||
| 18 | =cut | ||||||||||
| 19 | |||||||||||
| 20 | 2 | our $VERSION = '0.07'; | |||||||||
| 21 | |||||||||||
| 22 | 2 | CLASS->mk_classaccessor("base_url" => URI->new("http://ws.audioscrobbler.com/1.0/")); | |||||||||
| 23 | |||||||||||
| 24 | # defining default classes | ||||||||||
| 25 | 2 | CLASS->mk_classaccessor("artist_class" => CLASS . '::Artist'); | |||||||||
| 26 | 2 | CLASS->mk_classaccessor("track_class" => CLASS . '::Track'); | |||||||||
| 27 | 2 | CLASS->mk_classaccessor("tag_class" => CLASS . '::Tag'); | |||||||||
| 28 | 2 | CLASS->mk_classaccessor("user_class" => CLASS . '::User'); | |||||||||
| 29 | 2 | CLASS->mk_classaccessor("data_fetcher_class" => CLASS . '::DataFetcher'); | |||||||||
| 30 | |||||||||||
| 31 | # requiring stuff | ||||||||||
| 32 | 2 | ▶ | CLASS->artist_class->require or die $@; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 33 | 2 | ▶ | CLASS->track_class->require or die $@; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 34 | 2 | ▶ | CLASS->tag_class->require or die $@; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 35 | 2 | ▶ | CLASS->user_class->require or die $@; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 36 | 2 | ▶ | CLASS->data_fetcher_class->require or die $@; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 37 | |||||||||||
| 38 | # object accessors | ||||||||||
| 39 | 2 | CLASS->mk_accessors(qw/data_fetcher/); | |||||||||
| 40 | |||||||||||
| 41 | =head1 SYNOPSIS | ||||||||||
| 42 | |||||||||||
| 43 | This module aims to be a full implementation of a an object-oriented interface | ||||||||||
| 44 | to the Audioscrobbler WebService API (as available on | ||||||||||
| 45 | L<http://www.audioscrobbler.net/data/webservices/>). Since version 0.04, the | ||||||||||
| 46 | module fully supports data caching and, thus, complies to the service's | ||||||||||
| 47 | recommended usage guides. | ||||||||||
| 48 | |||||||||||
| 49 | use WebService::Audioscrobbler; | ||||||||||
| 50 | |||||||||||
| 51 | my $ws = WebService::Audioscrobbler->new; | ||||||||||
| 52 | |||||||||||
| 53 | # get an object for artist named 'foo' | ||||||||||
| 54 | my $artist = $ws->artist('foo'); | ||||||||||
| 55 | |||||||||||
| 56 | # retrieves tracks from 'foo' | ||||||||||
| 57 | my @tracks = $artist->tracks; | ||||||||||
| 58 | |||||||||||
| 59 | # retrieves tags associated with 'foo' | ||||||||||
| 60 | my @tags = $artist->tags; | ||||||||||
| 61 | |||||||||||
| 62 | # fetch artists similar to 'foo' | ||||||||||
| 63 | my @similar = $artist->similar_artists; | ||||||||||
| 64 | |||||||||||
| 65 | # prints each one of their names | ||||||||||
| 66 | for my $similar (@similar) { | ||||||||||
| 67 | print $similar->name . "\n"; | ||||||||||
| 68 | } | ||||||||||
| 69 | |||||||||||
| 70 | ... | ||||||||||
| 71 | |||||||||||
| 72 | # get an object for tag 'bar' | ||||||||||
| 73 | my $tag = $ws->tag('bar'); | ||||||||||
| 74 | |||||||||||
| 75 | # fetch tracks tagged with 'bar' | ||||||||||
| 76 | my @bar_tracks = $tag->tracks; | ||||||||||
| 77 | |||||||||||
| 78 | ... | ||||||||||
| 79 | |||||||||||
| 80 | my $user = $ws->user('baz'); | ||||||||||
| 81 | |||||||||||
| 82 | my @baz_neighbours = $user->neighbours; | ||||||||||
| 83 | |||||||||||
| 84 | Audioscrobbler is a great service for tracking musical data of various sorts, | ||||||||||
| 85 | and its integration with the LastFM service (L<http://www.last.fm>) makes it | ||||||||||
| 86 | work even better. Audioscrobbler provides data regarding similarity between | ||||||||||
| 87 | artists, artists discography, tracks by musical genre (actually, by tags), | ||||||||||
| 88 | top artists / tracks / albums / tags and how all of that related to your own | ||||||||||
| 89 | musical taste. | ||||||||||
| 90 | |||||||||||
| 91 | Currently, only of subset of these data feeds are implemented, which can be | ||||||||||
| 92 | viewed as the core part of the service: artists, tags, tracks and users. Since | ||||||||||
| 93 | this module was developed as part of a automatic playlist building application | ||||||||||
| 94 | (still in development) these functions were more than enough for its initial | ||||||||||
| 95 | purposes but a (nearly) full WebServices API is planned. | ||||||||||
| 96 | |||||||||||
| 97 | In any case, code or documentation patches are welcome. | ||||||||||
| 98 | |||||||||||
| 99 | =head1 METHODS | ||||||||||
| 100 | |||||||||||
| 101 | =cut | ||||||||||
| 102 | |||||||||||
| 103 | =head2 C<new([$cache_root]> | ||||||||||
| 104 | |||||||||||
| 105 | Creates a new C<WebService::Audioscrobbler> object. This object can then be | ||||||||||
| 106 | used to retrieve various bits of information from the Audioscrobbler database. | ||||||||||
| 107 | If C<$cache_root> is specified, Audioscrobbler data will be cached under this | ||||||||||
| 108 | directory, otherwise it will use L<Cache::FileCache> defaults. | ||||||||||
| 109 | |||||||||||
| 110 | =cut | ||||||||||
| 111 | |||||||||||
| 112 | sub new { | ||||||||||
| 113 | 0 | ▶ | my $class = shift; | ||||||||
|
Subroutine
new: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 114 | 0 | my ($cache_root) = @_; | |||||||||
| 115 | |||||||||||
| 116 | 0 | my $self = bless {}, $class; | |||||||||
| 117 | |||||||||||
| 118 | # creates the data fetcher object which will be extensively used | ||||||||||
| 119 | 0 | $self->data_fetcher( | |||||||||
| 120 | $self->data_fetcher_class->new( { | ||||||||||
| 121 | base_url => $self->base_url, | ||||||||||
| 122 | cache_root => $cache_root | ||||||||||
| 123 | } ) | ||||||||||
| 124 | ); | ||||||||||
| 125 | |||||||||||
| 126 | 0 | $self; | |||||||||
| 127 | } | ||||||||||
| 128 | |||||||||||
| 129 | =head2 C<artist($name)> | ||||||||||
| 130 | |||||||||||
| 131 | Returns an L<WebService::Audioscrobbler::Artist> object constructed using the | ||||||||||
| 132 | given C<$name>. Note that this call doesn't actually check if the artist exists | ||||||||||
| 133 | since no remote calls are dispatched - the object is only constructed. | ||||||||||
| 134 | |||||||||||
| 135 | =cut | ||||||||||
| 136 | |||||||||||
| 137 | sub artist { | ||||||||||
| 138 | 0 | ▶ | my ($self, $artist) = @_; | ||||||||
|
Subroutine
artist: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 139 | 0 | return $self->artist_class->new($artist, $self->data_fetcher); | |||||||||
| 140 | } | ||||||||||
| 141 | |||||||||||
| 142 | =head2 C<track($artist, $title)> | ||||||||||
| 143 | |||||||||||
| 144 | Returns an L<WebService::Audioscrobbler::Track> object constructed used the | ||||||||||
| 145 | given C<$artist> and C<$title>. The C<$artist> parameter can either be a | ||||||||||
| 146 | L<WebService::Audioscrobbler::Artist> object or a string (in this case, a | ||||||||||
| 147 | L<WebService::Audioscrobbler::Artist> will be created behind the scenes). Note | ||||||||||
| 148 | that this call doesn't actually check if the track exists since no remote calls | ||||||||||
| 149 | are dispatched - the object is only constructed. | ||||||||||
| 150 | |||||||||||
| 151 | =cut | ||||||||||
| 152 | |||||||||||
| 153 | sub track { | ||||||||||
| 154 | 0 | ▶ | my ($self, $artist, $title) = @_; | ||||||||
|
Subroutine
track: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 155 | |||||||||||
| 156 | 0 | ▶ | $artist = $self->artist($artist) | ||||||||
|
Branch: 1 branch
| |||||||||||
| 157 | unless ref $artist; # assume the user knows what he's doing | ||||||||||
| 158 | |||||||||||
| 159 | 0 | return $self->track_class->new($artist, $title, $self->data_fetcher); | |||||||||
| 160 | } | ||||||||||
| 161 | |||||||||||
| 162 | =head2 C<tag($name)> | ||||||||||
| 163 | |||||||||||
| 164 | Returns an L<WebService::Audioscrobbler::Tag> object constructed using the given | ||||||||||
| 165 | C<$name>. Note that this call doesn't actually check if the tag exists since no | ||||||||||
| 166 | remote calls are dispatched - the object is only constructed. | ||||||||||
| 167 | |||||||||||
| 168 | =cut | ||||||||||
| 169 | |||||||||||
| 170 | sub tag { | ||||||||||
| 171 | 0 | ▶ | my ($self, $tag) = @_; | ||||||||
|
Subroutine
tag: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 172 | 0 | return $self->tag_class->new($tag, $self->data_fetcher); | |||||||||
| 173 | } | ||||||||||
| 174 | |||||||||||
| 175 | =head2 C<user($name)> | ||||||||||
| 176 | |||||||||||
| 177 | Returns an L<WebService::Audioscrobbler::User> object constructed using the given | ||||||||||
| 178 | C<$name>. Note that this call doesn't actually check if the user exists since no | ||||||||||
| 179 | remote calls are dispatched - the object is only constructed. | ||||||||||
| 180 | |||||||||||
| 181 | =cut | ||||||||||
| 182 | |||||||||||
| 183 | sub user { | ||||||||||
| 184 | 0 | ▶ | my ($self, $user) = @_; | ||||||||
|
Subroutine
user: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 185 | 0 | return $self->user_class->new($user, $self->data_fetcher); | |||||||||
| 186 | } | ||||||||||
| 187 | |||||||||||
| 188 | =head1 AUTHOR | ||||||||||
| 189 | |||||||||||
| 190 | Nilson Santos Figueiredo Júnior, C<< <nilsonsfj at cpan.org> >> | ||||||||||
| 191 | |||||||||||
| 192 | =head1 BUGS | ||||||||||
| 193 | |||||||||||
| 194 | Please report any bugs or feature requests to | ||||||||||
| 195 | C<bug-webservice-audioscrobbler at rt.cpan.org>, or through the web interface at | ||||||||||
| 196 | L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WebService-Audioscrobbler>. | ||||||||||
| 197 | I will be notified, and then you'll automatically be notified of progress on | ||||||||||
| 198 | your bug as I make changes. | ||||||||||
| 199 | |||||||||||
| 200 | =head1 SUPPORT | ||||||||||
| 201 | |||||||||||
| 202 | You can find documentation for this module with the perldoc command. | ||||||||||
| 203 | |||||||||||
| 204 | perldoc WebService::Audioscrobbler | ||||||||||
| 205 | |||||||||||
| 206 | You can also look for information at: | ||||||||||
| 207 | |||||||||||
| 208 | =over 4 | ||||||||||
| 209 | |||||||||||
| 210 | =item * AnnoCPAN: Annotated CPAN documentation | ||||||||||
| 211 | |||||||||||
| 212 | L<http://annocpan.org/dist/WebService-Audioscrobbler> | ||||||||||
| 213 | |||||||||||
| 214 | =item * CPAN Ratings | ||||||||||
| 215 | |||||||||||
| 216 | L<http://cpanratings.perl.org/d/WebService-Audioscrobbler> | ||||||||||
| 217 | |||||||||||
| 218 | =item * RT: CPAN's request tracker | ||||||||||
| 219 | |||||||||||
| 220 | L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=WebService-Audioscrobbler> | ||||||||||
| 221 | |||||||||||
| 222 | =item * Search CPAN | ||||||||||
| 223 | |||||||||||
| 224 | L<http://search.cpan.org/dist/WebService-Audioscrobbler> | ||||||||||
| 225 | |||||||||||
| 226 | =back | ||||||||||
| 227 | |||||||||||
| 228 | =head1 COPYRIGHT & LICENSE | ||||||||||
| 229 | |||||||||||
| 230 | Copyright 2006-2007 Nilson Santos Figueiredo Júnior, all rights reserved. | ||||||||||
| 231 | |||||||||||
| 232 | This program is free software; you can redistribute it and/or modify it | ||||||||||
| 233 | under the same terms as Perl itself. | ||||||||||
| 234 | |||||||||||
| 235 | B<NOTE>: The datafeed from audioscrobbler.net is for | ||||||||||
| 236 | I<non-commercial use only>. Please see | ||||||||||
| 237 | L<http://www.audioscrobbler.net/data/webservices/> for | ||||||||||
| 238 | more licensing information. | ||||||||||
| 239 | |||||||||||
| 240 | =head1 SEE ALSO | ||||||||||
| 241 | |||||||||||
| 242 | =over 4 | ||||||||||
| 243 | |||||||||||
| 244 | =item * L<http://www.audioscrobbler.net/data/webservices/> and L<http://www.last.fm/> | ||||||||||
| 245 | |||||||||||
| 246 | =item * L<WebService::LastFM::SimilarArtists>, L<WebServices::LastFM>, L<Audio::Scrobbler> | ||||||||||
| 247 | |||||||||||
| 248 | =item * L<LWP::Simple>, L<XML::Simple>, L<Cache::FileCache>, L<URI> | ||||||||||
| 249 | |||||||||||
| 250 | =back | ||||||||||
| 251 | |||||||||||
| 252 | =cut | ||||||||||
| 253 | |||||||||||
| 254 | 2 | 1; # End of WebService::Audioscrobbler | |||||||||