NAME

Lyrics::Fetcher - Perl extension to manage fetchers of song lyrics.

SYNOPSIS

  use Lyrics::Fetcher;

  # using a specific fetcher:
  print Lyrics::Fetcher->fetch('Pink Floyd','Echoes','LyricWiki');
  
  # if you omit the fetcher, automatically tries all available fetchers:
  print Lyrics::Fetcher->fetch('Oasis', 'Cast No Shadow');
  
  # or you can pass an arrayref of fetchers you want used:
  print Lyrics::Fetcher->fetch('Oasis', 'Whatever', [qw(LyricWiki Google)]);

  # To find out which fetchers are available:
  my @fetchers = Lyrics::Fetcher->available_fetchers;

DESCRIPTION

This module is a fetcher manager. It searches for modules in the Lyrics::Fetcher::* name space and registers them as available fetchers.

The fetcher modules are called by Lyrics::Fetcher and they return song's lyrics in plain text form.

This module calls the respective Fetcher->fetch($$) method and returns the result.

In case of module error the Fetchers must return undef with the error description in $@.

In case of problems with lyrics' fetching, the error will be returned in the $Lyrics::Fetcher::Error string. If all goes well, it will have 'OK' in it.

The fetcher selection is made by the "method" parameter passed to the fetch() of this module. You can also omit this parameter, in which case all available fetchers will be tried, or you can supply an arrayref of fetchers you'd like to try (in order of preference).

The value of the "method" parameter must be a * part of the Lyrics::Fetcher::* fetcher package name.

INTERFACE

available_fetchers

Returns a list of available fetcher modules.

say "Fetchers available: " . join ',', Lyrics::Fetcher->available_fetchers;

fetch($artist, $title [, $fetcher])

Attempt to fetch the lyrics for the given artist and title.

If you want to control which fetcher(s) will be used, you can supply a scalar containing the name of the fetcher you want to use, or an arrayref of fetchers you want to try (in the order you want them tried). By default, each fetcher module which is installed will be tried.

if (my $lyrics = Lyrics::Fetcher->fetch('Oasis', 'Whatever')) {
    say $lyrics;
} else {
    warn "Failed to fetch lyrics - error was: " . $Lyrics::Fetcher::ERROR;
}

ADDING FETCHERS

If there's a lyrics site you'd like to see supported, raise a request as a wishlist item on http://rt.cpan.org/NoAuth/Bugs.html?Dist=Lyrics-Fetcher or mail me direct: davidp@preshweb.co.uk and, if I have time, I'll whip up a fetcher. Or, feel free to code it up yourself and send it to me (or upload it to CPAN yourself) if you want to be really helpful ;)

CONTACT AND COPYRIGHT

Copyright 2007-2010 David Precious <davidp@preshweb.co.uk> (CPAN Id: BIGPRESH)

All comments / suggestions / bug reports gratefully received (ideally use the RT installation at http://rt.cpan.org/ but mail me direct if you prefer)

Developed on Github at http://github.com/bigpresh/Lyrics-Fetcher

Previously: Copyright 2003 Sir Reflog <reflog@mail15.com>. Copyright 2003 Zachary P. Landau <kapheine@hypa.net>

LICENSE

All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.