/ 
WWW-TinySong-0.04_02
River stage zero No dependents
/ WWW::TinySong

NAME

WWW::TinySong - Get free music links from tinysong.com

SYNOPSIS

# function-oriented

use WWW::TinySong qw(tinysong);

for(tinysong("we are the champions")) {
    printf("%s", $_->{song});
    printf(" by %s", $_->{artist}) if $_->{artist};
    printf(" on %s", $_->{album}) if $_->{album};
    printf(" <%s>\n", $_->{url});
}


# object-oriented

use WWW::TinySong;

my $ts = new WWW::TinySong;

$ts->timeout(10);
$ts->env_proxy();

for($ts->tinysong("we are the champions")) {
    printf("%s", $_->{song});
    printf(" by %s", $_->{artist}) if $_->{artist};
    printf(" on %s", $_->{album}) if $_->{album};
    printf(" <%s>\n", $_->{url});
}

DESCRIPTION

tinysong.com is a web app that can be queried for a song and returns a tiny URL, allowing you to listen to the song for free online and share it with friends. WWW::TinySong is a Perl interface to this service, allowing you to programmatically search its underlying database. (Yes, for those who are curious, the module currently works by scraping.)

FUNCTIONS/METHODS

This module defines one public function/method. In the function-oriented approach, it would be called directly. Alternatively, it may be called on a WWW::TinySong object. See the next section for details.

tinysong ( QUERY_STRING [, LIMIT ] )

Searches tinysong.com for QUERY_STRING, giving up to LIMIT results. LIMIT defaults to 10 if not defined. Returns an array in list context or the top result in scalar context. Return elements are hashrefs with keys qw(album artist song url). Their values will be the empty string if not given by the website. Here's a quick script to demonstrate:

#!/usr/bin/perl

use WWW::TinySong qw(tinysong);
use Data::Dumper;
 
print Dumper tinysong("a hard day's night", 3);

...and its output on my system at the time of this writing:

$VAR1 = {
          'album' => 'A Hard Day\'s Night',
          'artist' => 'The Beatles',
          'song' => 'A Hard Day\'s Night',
          'url' => 'http://tinysong.com/21q3'
        };
$VAR2 = {
          'album' => 'A Hard Day\'s Night',
          'artist' => 'The Beatles',
          'song' => 'And I Love Her',
          'url' => 'http://tinysong.com/2i03'
        };
$VAR3 = {
          'album' => 'A Hard Day\'s Night',
          'artist' => 'The Beatles',
          'song' => 'If I Fell',
          'url' => 'http://tinysong.com/21q4'
        };

FUNCTION-ORIENTED VS. OBJECT-ORIENTED INTERFACE

The function-oriented interface should be adequate for many users. This involves just importing what you need into your namespace and calling it as any other function.

If you need to customize the underlying LWP::UserAgent used for retrievals, you would use the object-oriented interface: create a WWW::TinySong with the desired options and call the methods of the resulting object. Note that WWW::TinySong subclasses LWP::UserAgent, so new accepts the same arguments, and all LWP::UserAgent methods are supported. You could even bless an existing LWP::UserAgent as WWW::TinySong, not that I'm recommending you do that.

The "SYNOPSIS" demonstrates both ways of using this module.

SEE ALSO

http://tinysong.com/, LWP::UserAgent

BUGS

Please report them: http://rt.cpan.org/Public/Dist/Display.html?Name=WWW-TinySong

AUTHOR

Miorel-Lucian Palii, <mlpalii@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Miorel-Lucian Palii

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.