WebService::Audioscrobbler::Base - An object-oriented interface to the Audioscrobbler WebService API

    package WebService::Audioscrobbler::Subclass;
    use base 'WebService::Audioscrobbler::Base';

    ...

    my $self = WebService::Audioscrobbler::Subclass->new;

    # retrieves tracks
    my @tracks = $self->tracks;

    # retrieves tags
    my @tags = $self->tags;

    # retrieves arbitrary XML data as a hashref, using XML::Simple
    my $data = $self->fetch_data('resource.xml');

package WebService::Audioscrobbler::Base;
use warnings FATAL => 'all';
use strict;
use CLASS;

use base 'Class::Data::Accessor';
use base 'Class::Accessor::Fast';

require URI;
require URI::Escape;

use WebService::Audioscrobbler;

our $VERSION = '0.07';

# artists related
CLASS->mk_classaccessor("artists_postfix"    => "topartists.xml");
CLASS->mk_classaccessor("artists_class"      => WebService::Audioscrobbler->artist_class );
CLASS->mk_classaccessor("artists_sort_field" => "count");

# tracks related
CLASS->mk_classaccessor("tracks_postfix"    => "toptracks.xml");
CLASS->mk_classaccessor("tracks_class"      => WebService::Audioscrobbler->track_class );
CLASS->mk_classaccessor("tracks_sort_field" => "count");

# tags related
CLASS->mk_classaccessor("tags_postfix"    => "toptags.xml");
CLASS->mk_classaccessor("tags_class"      => WebService::Audioscrobbler->tag_class );
CLASS->mk_classaccessor("tags_sort_field" => "count");

# object accessors
CLASS->mk_accessors(qw/data_fetcher/);

sub tracks {
    my $self = shift;

    my $data = $self->fetch_data($self->tracks_postfix);

    my @tracks;

    if (ref $data->{track} eq 'HASH') {
        my $tracks = $data->{track};
        my $sort_field = $self->tracks_sort_field;

        @tracks = map {
            my $title = $_;

            my $info = $tracks->{$title};
            $info->{name}   = $title;
            
            if (defined $info->{artist}) {
                $info->{artist}->{data_fetcher} = $self->data_fetcher;
                $info->{artist} = $self->artists_class->new($info->{artist});
            }
            elsif ($self->isa($self->artists_class)) {
                $info->{artist} = $self;
            }
            else {
                $self->croak("Couldn't determine artist for track");
            }

            $info->{data_fetcher} = $self->data_fetcher;

            $self->tracks_class->new($info);

        } sort {$tracks->{$b}->{$sort_field} <=> $tracks->{$a}->{$sort_field}} keys %$tracks;
    }

    return wantarray ? @tracks : \@tracks;

}

sub tags {
    my $self = shift;

    my $data = $self->fetch_data($self->tags_postfix);

    my @tags;

    if (ref $data->{tag} eq 'HASH') {
        my $tags = $data->{tag};

        if (exists $tags->{name} && !ref $tags->{name}) {
            @tags = $self->_process_tag( $tags );
        }
        else {
            my $sort_field = $self->tags_sort_field;
            @tags = map {
                $self->_process_tag( $tags->{ $_ }, $_ );
            } sort {$tags->{$b}->{$sort_field} <=> $tags->{$a}->{$sort_field}} keys %$tags;
        }
    }

    return wantarray ? @tags : \@tags;

}

sub _process_tag {
    my ($self, $info, $name) = @_;
    
    $info->{name} = $name if defined $name;

    die "no tag name" unless defined $info->{name};

    $info->{data_fetcher} = $self->data_fetcher;

    $self->tags_class->new($info);

}

sub artists {
    my $self = shift;

    my $data = $self->fetch_data($self->artists_postfix);

    my @artists;

    if (ref $data->{artist} eq 'HASH') {
        my $artists = $data->{artist};
        my $sort_field = $self->artists_sort_field;
        @artists = map {
            my $name = $_;

            my $info = $artists->{$name};
            $info->{name} = $name;
            $info->{data_fetcher} = $self->data_fetcher;

            $self->artists_class->new($info);

        } sort {$artists->{$b}->{$sort_field} <=> $artists->{$a}->{$sort_field}} keys %$artists;
    }

    return wantarray ? @artists : \@artists;

}

sub fetch_data {
    my ($self, $postfix) = @_;

    my $uri = $self->resource_path->clone;
    $uri->path_segments($uri->path_segments, $postfix);

    # warn "\nFetching resource '$uri'\n";
    
    return $self->data_fetcher->fetch($uri);
}

sub resource_path {
    my $class = ref shift;
    croak("$class must override the 'resource_path' method");
}

sub uri_builder {
    my ($self, @bits) = @_;
    URI->new( join '/', $self->base_resource_path, map {URI::Escape::uri_escape($_)} @bits );
}

sub croak {
    shift if $_[0]->isa(CLASS);
    require Carp;
    Carp::croak(@_);
}

1; # End of WebService::Audioscrobbler::Base