/ 
WWW-Search-Mininova-0.05
/ WWW::Search::Mininova

NAME

WWW::Search::Mininova - Interface to www.mininova.org Torrent site

SYNOPSIS

use WWW::Search::Mininova;
my $mini = WWW::Search::Mininova->new;
$mini->search('foo')->{results}[0]{download_uri};

use WWW::Search::Mininova;
my $mini = WWW::Search::Mininova->new(
    category => 'Music',
    sort     => 'Seeds',
);

$mini->search('foo');

if ( defined $mini->did_you_mean ) {
    print "Did you mean to search for "
        . $mini->did_you_mean . "?\n";
}

print "Found " . $mini->results_found . " results\n";
foreach my $result ( @{ $mini->results } ) {
    if ( $result->{is_private} ) {
        print "Private tracker\n";
    }
    print <<"END_RESULT_DATA";
    Torrent name: $result->{name}
    Number of seeds: $result->{seeds}
    Number of leechers: $result->{leechers}
    Torrent page: $result->{uri}
    Download URI: $result->{download_uri}
    Torrent size: $result->{size}
    Category: $result->{category}
    Sub category: $result->{subcategory}
    Was added on: $result->{added_date}

END_RESULT_DATA
}

DESCRIPTION

Module provides interface to Mininova.org website. Facilitates search and torrent URI grabber as well as statistics information. Now available in POE flavor. See POE::Component::WWW::Search::Mininova

METHODS

new

my $mini = WWW::Search::Mininova->new;

my $mini = WWW::Search::Mininova->new(
    category  => 'Music',
    sort      => 'Seeds',
    timeout   => 10,
);

Creates and returns WWW::Search::Mininova object. The following optional arguments may be specified:

category

{ category => 'TV Shows' }

Specifies which torrent category to search. If not specified defaults to 'All'. May also be set with ->category method. Accepts the following values (case insenitive):

All
Anime
Books
Games
Movies
Music
Pictures
Software
TV Shows
Other

sort

{ sort => 'Seeds' }

Specifies which column to sort by. If not specified defaults to 'Added'. May also be set with ->sort method. Accepts the following values (case insensitive):

Category
Added
Name
Size
Seeds
Leechers

Note that sorting by 'Category' in any but 'All' category searches doesn't make much sense ;)

timeout

{ timeout => 10 }

The number of seconds to wait for the search results. Defaults to 60. The value goes directly into LWP::UserAgent object, might want to read the docs of it for more details.

ua

{ ua => 'Torrent UserAgent' }

The user agent string to send when requesting search results. Defaults to FireFox's on Ubuntu UA string. In particular:

Mozilla/5.0 (X11; U; Linux i686 en-US; rv:1.8.1.11 Gecko/20071204 Ubuntu/7.10 (gutsy) Firefox/2.0.0.11

However, it may change in future releases. The value goes directly into LWP::UserAgent object, you might want to read the docs of it for more details.

debug

{ debug => 1 }

When set to a true value causes some debug messages to appear on STDERR, whether they are useful or not is another story :). Defaults to 0 for obvious reasons.

$mini->search('foos');

my $results_ref = $mini->search('foos');

my $results_data_ref = $mini->search('foos')->{results};

Performs search on a given argument which must be a scalar. If an error occures (as well if timeout timeouts (see ->timeout method)) returns undef and the reason for error can be fetched with ->error method. Returns a hashref containing the following keys (each of which can be fetched with separate methods, thus storing the return value is not particularly necessary):

found

The number of results that was found. Ranges from 0 to 500. Note: the actual number of results will NOT be 500, but it will be however many results www.mininova.org displays per page.

results

An arrayref containing search results (items are hashref, see RESULTS section for explanation of their keys).

did_you_mean

If your search triggered the "Did you mean?" annoyance this key will be present and the value will be the suggested correction. Othewise the key won't be present (thus is can be checked with exists)

results

my $results_ref = $mini->results;

Note the plural form. Returns a possibly empty arrayref containing search results (items are hashref, see RESULTS section for explanation of their keys). Must be called after the call to ->search method.

result

my $result = $mini->result(10);

Note the singular form. Returns a hashref containing information for result number provided as an argument. (Note: count starts at zero, like all normal counts. Thus to get the first result you'd call ->result(0)). Returns undef if no such result exists (or if called before the call to ->search method).

results_found

my $total_results = $mini->results_found;

Returns the total number of results for the term you searched for. Note: this will NOT be the total number of items you'd get in ->results arrayref. The highest number will be however many results www.mininova.org displays per page.

did_you_mean

if ( defined( my $correction =  $mini->did_you_mean ) ) {
    print "Did you mean: $correction?\n";
}

If search triggered the "Did you mean?" annoyance returns the suggested correction, otherwise returns undef.

make_uri

my $results_uri = $mini->make_uri('foos');

Returns a URI object -- link to the page with the search results on www.mininova.org. Respects the category and sort settings (see ->category and ->sort methods). Will croak if argument is not defined.

error

Returns an error message if an error occured, or search timed out. See ->timeout and ->search methods.

ACCESSORS MUTATORS

category

my $current_category = $mini->category;
$mini->category('Music');

When called without an optional argument returns the current category the search will be performed on. Note that you must call ->search method in order for changes to take effect. The argument can be one of the following (case insensitive):

All
Anime
Books
Games
Movies
Music
Pictures
Software
TV Shows
Other
Featured

sort

$current_sort = $mini->sort;
$mini->sort('Size');

When called without an optional argument returns current search sorting column. With an argument -- sets sorting column. Note that you must call ->search method in order for sorting to take effect. The argument can be any of the following case insensitive values:

Category
Added
Name
Size
Seeds
Leechers

Note that sorting by 'Category' in any but 'All' category searches doesn't make much sense.

timeout

my $current_timeout = $mini->timeout;
$mini->timeout( 120 );

When called without an optional argument returns current value for timeout on ->search method. When called with an argument sets timeout for LWP::UserAgent object which WWW::Search::Mininova uses to get search results. Default is 60. Note that timeout does not necessarily mean the maximum time the request will last. See documentation for LWP::UserAgent for more information.

ua

my $current_ua = $mini->ua;
$mini->ua('Torrent Searcher');

The user agent string to send when requesting search results. Defaults to FireFox's on Ubuntu UA string. In particular:

Mozilla/5.0 (X11; U; Linux i686 en-US; rv:1.8.1.11 Gecko/20071204 Ubuntu/7.10 (gutsy) Firefox/2.0.0.11

However, it may change in future releases. The value goes directly into LWP::UserAgent object, you might want to read the docs of it for more details.

debug

my $is_debug = $mini->debug;
$mini->debug( 1 );

When called without an argument returns the current setting. An argument can be either a true or false value. When argument is true, causes debugging messages to be printed to STDERR.

RESULTS

$VAR1 = {
    'is_private' => 0,
    'name' => 'Foos',
    'size' => '112.1 MB',
    'seeds' => '25',
    'leechers' => '5',
    'added_date' => '18 Jul 07',
    'category' => 'Music'
    'subcategory' => 'Rock',
    'uri' => bless( do{\(my $o = 'http://www.mininova.org/tor/444444')}, 'URI::http' ),
    'download_uri' => bless( do{\(my $o = 'http://www.mininova.org/get/444444')}, 'URI::http' ),
}

Each item in an arrayref from either ->results method or the key results from the ->search method, as well as the return of ->result is a hashref. It contains information about a certain torrent from the search results. The hashref contains the following keys:

is_private

When true indicates that torrent is hosted on a private tracker. When false indicates public tracker.

name

The name of the torrent

size

The size of the torrent in whatever units it is presented on the page. Usually it will be something along the lines of '300 MB', or '3 GB'.

seeds

The number of seeds for the torrent. May be a string 'N/A', which indicates that there is no data available.

leechers

The number of leechers for the torrent. May be a string 'N/A', which indicates that there is no data available.

added_date

The date when the torrent was added. So far it should be in the '31 Dec 07', but it's only a string gotten directly from the page.

category

Torrent's category. Technically the value can be used in the ->category method (not tested).

subcategory

Torrent's subcategory.

uri

A URI object -- link to the torrent page (with its long description, comments, etc.).

download_uri

A URI object -- link to the torrent itself. Content-type is application/x-bittorrent and if you are doing anything low-level with it you might want to regard the Content-Disposition header which will contain an actual torrent filename.

PREREQUISITES

This module requires URI, LWP::UserAgent, HTML::TokeParser::Simple and HTML::Entities modules.

SEE ALSO

URI, LWP::UserAgent

AUTHOR

Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)

BUGS

Please report any bugs or feature requests to bug-www-search-mininova at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Search-Mininova. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc WWW::Search::Mininova

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008 Zoffix Znet, all rights reserved.

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