NAME

SYNOPSIS

  # basic use

  use WWW::TinySong qw(search);

  for(search("we are the champions")) {
      printf("%s", $_->{songName});
      printf(" by %s", $_->{artistName});
      printf(" on %s", $_->{albumName}) if $_->{albumName};
      printf(" <%s>\n", $_->{tinysongLink});
  }

  # customize the user agent

  use LWP::UserAgent;

  my $ua = new LWP::UserAgent;
  $ua->timeout(10);
  $ua->env_proxy;

  WWW::TinySong->ua($ua);

  # customize the service

  WWW::TinySong->service('http://tinysong.com/');

  # tolerate some server errors

  WWW::TinySong->retries(5);

DESCRIPTION

FUNCTIONS

link( $SEARCH_TERMS )

WWW::TinySong->link( $SEARCH_TERMS )

WWW::TinySong->a( $SEARCH_TERMS )

Returns the short URL corresponding to the top result of searching with the specified song and artist name terms or "undef" if no song was found.

search( $SEARCH_TERMS [, $LIMIT ] )

WWW::TinySong->search( $SEARCH_TERMS [, $LIMIT ] )

WWW::TinySong->s( $SEARCH_TERMS [, $LIMIT ] )

Searches for the specified song and artist name terms, 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(tinysongLink songID songName artistID artistName albumID albumName groovesharkLink)" as given by "parse". Here's a quick script to demonstrate:

  #!/usr/bin/perl

  use WWW::TinySong qw(search);
  use Data::Dumper;

  print Dumper search("three little birds", 3);
    

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

  $VAR1 = {
            'artistName' => 'Bob Marley',
            'albumName' => 'Legend',
            'songName' => 'Three Little Birds',
            'artistID' => '139',
            'tinysongLink' => 'http://tinysong.com/eg9',
            'songID' => '1302',
            'albumID' => '97291',
            'groovesharkLink' => 'http://listen.grooveshark.com/song/Three_Little_Birds/1302'
          };
  $VAR2 = {
            'artistName' => 'Bob Marley',
            'albumName' => 'One Love: The Very Best Of Bob Marley & The Wailers',
            'songName' => 'Three Little Birds',
            'artistID' => '139',
            'tinysongLink' => 'http://tinysong.com/lf2',
            'songID' => '3928811',
            'albumID' => '221021',
            'groovesharkLink' => 'http://listen.grooveshark.com/song/Three_Little_Birds/3928811'
          };
  $VAR3 = {
            'artistName' => 'Bob Marley & The Wailers',
            'albumName' => 'Exodus',
            'songName' => 'Three Little Birds',
            'artistID' => '848',
            'tinysongLink' => 'http://tinysong.com/egc',
            'songID' => '3700',
            'albumID' => '2397306',
            'groovesharkLink' => 'http://listen.grooveshark.com/song/Three_Little_Birds/3700'
          };
    

WWW::TinySong->b( $SEARCH_TERMS )

Searches for the specified song and artist name terms, giving the top result. I'm not really sure why this is part of the API because the same result can be obtained by limiting a "search" to one result, but it's included here for completeness.

WWW::TinySong->call( $METHOD , $SEARCH_TERMS [, \%EXTRA_PARAMS ] )

Calls API "method" $METHOD using the specified $SEARCH_TERMS and optional hashref of extra parameters. Whitespace sequences in $SEARCH_TERMS will be converted to pluses. Returns the entire response as a string. Unless you're just grabbing a link, you will probably want to pass the result through "parse".

WWW::TinySong->parse( [ @RESULTS ] )

Parses all the lines in the given list of results according to the specs, building and returning a (possibly empty) list of hashrefs with the keys "qw(tinysongLink songID songName artistID artistName albumID albumName groovesharkLink)", whose meanings are hopefully self-explanatory.

WWW::TinySong->scrape( $QUERY_STRING [, $LIMIT ] )

Searches for $QUERY_STRING by scraping, 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(albumName artistName songName tinysongLink)". Their values will be the empty string if not given by the website. As an example, executing:

  #!/usr/bin/perl
  
  use WWW::TinySong;
  use Data::Dumper;
  
  print Dumper(WWW::TinySong->scrape("we can work it out", 3));
    

...prints something like:

  $VAR1 = {
            'artistName' => 'The Beatles',
            'tinysongLink' => 'http://tinysong.com/5Ym',
            'songName' => 'We Can Work It Out',
            'albumName' => 'The Beatles 1'
          };
  $VAR2 = {
            'artistName' => 'The Beatles',
            'tinysongLink' => 'http://tinysong.com/uLd',
            'songName' => 'We Can Work It Out',
            'albumName' => 'We Can Work It Out / Day Tripper'
          };
  $VAR3 = {
            'artistName' => 'The Beatles',
            'tinysongLink' => 'http://tinysong.com/2EaX',
            'songName' => 'We Can Work It Out',
            'albumName' => 'The Beatles 1967-70'
          };
    

This function is how the primary functionality of the module was implemented in the 0.0x series. It remains here as a tribute to the past, but should be avoided because scraping depends on the details of the response HTML, which may change at any time (and in fact did at some point between versions 0.05 and 0.06). Interestingly, this function does currently have one advantage over the robust alternative: whereas "search" is limited to a maximum of 32 results by the web service, scraping doesn't seem to be subjected to this requirement.

WWW::TinySong->ua( [ $USER_AGENT ] )

Returns the user agent object used by this module for web retrievals, first setting it to $USER_AGENT if it's specified. Defaults to a "new" LWP::UserAgent. If you explicitly set this, you don't have to use a LWP::UserAgent, it may be anything that can "get" a URL and return a response object.

WWW::TinySong->service( [ $URL ] )

Returns the web address of the service used by this module, first setting it to $URL if it's specified. Defaults to <http://tinysong.com/>.

WWW::TinySong->retries( [ $COUNT ] )

Returns the number of consecutive internal server errors the module will ignore before failing, first setting it to $COUNT if it's specified. Defaults to 0 (croak, do not retry in case of internal server error). This was created because read timeouts seem to be a common problem with the web service. The module now provides the option of doing something more useful than immediately failing.

BE NICE TO THE SERVERS

  use WWW::TinySong qw(search link);
  use LWP::RobotUA;

  my $ua = LWP::RobotUA->new('my-nice-robot/0.1', 'me@example.org');

  WWW::TinySong->ua($ua);

  # search() and link() should now be well-behaved

SEE ALSO

BUGS

AUTHOR

VERSION

The latest version is hosted on Google Code as part of <http://elementsofpuzzle.googlecode.com/>. Significant changes are also contributed to CPAN: <http://search.cpan.org/dist/WWW-TinySong/>.

COPYRIGHT AND LICENSE

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.