NAME
WWW::Comic::Plugin - Plugin superclass for WWW::Comic
DESCRIPTION
This is a plugin superclass for WWW::Comic from which all plugin modules are subclassed.
METHODS
Each plugin module should subclass WWW::Comic::Plugin, and support the following methods explicitly or through inheritance:
new *MANDATORY*
This method is mandatory. Your plugin must allow instantiation through this method.
comics
This method should return a list of comics which your plugin will support.
The default superclassed comics() method will try to determine what comics your plugin supports by loogking for $self-{comics}>, which can be an array of hash of comic names. If it cannot find a suitable list of comics there, it will look for @WWW::Comic::Plugin::YourPlugin::COMICS or %WWW::Comic::Plugin::YourPlugin::COMICS.
strip_url *MANDATORY*
This method is mandatory. This method must return a valid comic strip image URL. A predefined LWP::UserAgent object can be obtained in order to perform this functionality by calling the superclassed _new_agent() method.
This method should return an undef value upon failure.
get_strip
The default superclassed get_strip() method will try and download a URL in to a scalar, and if it contains a valid GIF, JPEG or PNG image, it will return. The URL of the comic strip image can be passed as a paramater. If it is not passed, it will ask the strip_url() method for a comic strip URL.
If you overload the default method, you should return undef on failure, or return the binary image data as a scalar if successful. You method should validate the binary image data as a valid GIF, JPEG or PNG image file by using the superclassed _image_format() method.
mirror_strip
The default superclassed method will use the get_strip() method to download a comic image URL and then write it to disk. If no filename paramater is passed, it will assume a sensible default filename to write to disk based upon the comic strip URL that it is retrieving. It will return the name of the file that it wrote to disk.
If you overload the default method, you should return undef on failure, or return the name of the file that was written to disk if successful.
PRIVATE METHODS
The following private methods existing withing the WWW::Comic::Plugin module as utility methods. These are not intended to be part of the publically exposed and documented part of your plugin API.
_new_agent
This method returns an LWP::UserAgent object, preconfigured with sensible default paramaters.
_image_format
This method accepts a single scalar argument which should contain binary image data. It will return a scalar value of gif, jpg or png to match the format of the image.
It will return an undef value if it is not a valid GIF, JPEG or PNG image.
EXAMPLES
See inside WWW::Comic::Plugin::UFS, WWW::Comic::Plugin::uComics, WWW::Comic::Plugin::Dilbert, WWW::Comic::Plugin::VenusEnvy, WWW::Comic::Plugin::UserFriendly, WWW::Comic::Plugin::Goats and WWW::Comic::Plugin::MrWiggles.
A good boiler plate example is WWW::Comic::Plugin::MrWiggles.
VERSION
$Id: Plugin.pm,v 1.7 2006/01/10 15:49:32 nicolaw Exp $
AUTHOR
Nicola Worthington <nicolaw@cpan.org>
COPYRIGHT
Copyright 2006 Nicola Worthington.
This software is licensed under The Apache Software License, Version 2.0.