There are two different kind of plugins in this directory:
grabbers and getters.

Grabbers
========

The job of the Grabbers is to determine the download URL of the
actual media file we want to get (in case of flash video sites
that means to find out the URL which contains the actual flash
video file, in contrast to the URL of the page where the flash
plugin is embedded in).

All Grabbers inherit from GrabberBase, which defines some methods
shared by all Grabbers.

In order to be loaded, a Grabber module must be named *Grabber.pm
(i.e., the file name of the module must end with Grabber.pm).


Methods
-------

get(line):
This method is called for each of the installed grabbers, in turn
(there is no guaranteed order for this) for each line received by
irssi in any channel you are connected to.

If the Grabber determines that a URL it can handle is mentioned in
this line it is supposed to determine the metadata hash (more of this
later) and return it. If the Grabber does not think the line interesting
it returns undef, and the line is passed to the next Grabber.

Note:
Usually, you do _not_ need to overload this method in your Grabber.
The default method looks for a property called 'PATTERNS' in your
Grabber and treats this as an array reference, containing regex patterns
matching the URLs the Grabber is interested in. If one of these patterns
matches line, the method _parse is called like this:
return $self->_parse(line, pattern);

If you define your own Grabber, overload _parse instead, unless you
want a totaly different approach.


Properties
----------

NAME:
A name for your Grabber. Has to be unique among all Grabbers and Getters
installed.

PATTERNS:
See the description for get() under Methods.


Getters
=======

The job of a Getter is to actually download a media file, the metadata of
which has been determined by a Grabber.

All Getters inherit from GetterBase, which defines some methods shared by all
Getters.

In order to be loaded, a Getter module must be named *Getter.pm
(i.e., the file name of the module must end with Getter.pm).


Methods
-------

get(metadata):
This method is called with a metadata hash containing the data of a file that
is to be downloaded. See below for a description of the content of the hash.

The implementation of the actual download method is entirely left to the
Getter. The Getter should return 1 on success, and 0 on failure.


Properties
----------

NAME:
A name for your Getter. Has to be unique among all Getters and Grabbers
installed.


The Metadata
============

The Metadata is a hash describing various properties of a media file to be
downloaded. A Grabber produces a Metadata hash if it has found an URL of
interest and was able to determine all data necessary to download the media
file. The Metadata is then passed to a Getter, which uses the data to
download the file and give it a recognizable name. The Metadata should
(at least) contain the following fields:

TITLE:
A short, textual description of the file, usually taken from the site the
file was taken from.

ID:
A number or string describing the file in the context of the site the file is
from. This is usually unique for a single site, but does not have to be across
different sites (or, in other words, the tuple [ID, SOURCE] should be unique)

SOURCE:
A short string describing the site the file is from. Should be a single word,
like 'youtube' or '4chan'.

URL:
The URL of the site the media file was embedded in (this is usually the URL
that was accepted and parsed by the Grabber).

DLURL:
The URL of the actual media file. This is the file that should be downloaded
by the Getter.

TYPE:
A short string describing the nature of the media file. Should be a single
word, like 'video' or 'image'.



Parameters
==========

If you want your Grabber or Getter to have user settable parameters, which are
saved across different runs of the plugin you can use the built-in parameter
handling, which will take care of automagically saving and loading your
parameters.

In order to use it three steps are necessary:

a) in your constructor, define a property called '_PARAMS'. This is a
reference to a hash of array references, tke key being the name of your
parameter, and the array containing the default value of the parameter as the
first field, and a textual description string as the second field.

For example, a parameter called FOO, having a default value of 42 and a
description of 'This is the FOO parameter, twiddle it to do stuff' would be
declared as follows:

sub new {
    my $class = shift;
    my $self = $class->SUPER::new(
        _PARAMS => {'FOO' => [42, 'This is the FOO parameter, twiddle it to do stuff']},
        @_,
    );
    return bless($self, $class);
}

b) to access one of the parameters, call the _getval() method, giving the name
of the parameter as first argument. This will return the current value of that
parameter (either the default value or the user defined value).