IMDB::Film (3pm)

        use IMDB::Film;

        #
        # Retrieve a movie information by its IMDB code
        #
        my $imdbObj = new IMDB::Film(crit => 227445);

        or

        #
        # Retrieve a movie information by its title
        #
        my $imdbObj = new IMDB::Film(crit => 'Troy');

        or

        #
        # Parse already stored HTML page from IMDB
        #
        my $imdbObj = new IMDB::Film(crit => 'troy.html');

        if($imdbObj->status) {
                print "Title: ".$imdbObj->title()."\n";
                print "Year: ".$imdbObj->year()."\n";
                print "Plot Symmary: ".$imdbObj->plot()."\n";
        } else {
                print "Something wrong: ".$imdbObj->error;
        }

Overview

IMDB::Film is an object-oriented interface to the \s-1IMDB\s0. You can use that module to retrieve information about film: title, year, plot etc.

Constructor

new()

Object's constructor. You should pass as parameter movie title or \s-1IMDB\s0 code. my $imdb = new IMDB::Film(crit => <some code>); or my $imdb = new IMDB::Film(crit => <some title>); or my $imdb = new IMDB::Film(crit => <\s-1HTML\s0 file>); For more infomation about base methods refer to IMDB::BaseClass.

_init()

Initialize object.

Options

year

Define a movie's year. It's useful to use it to get the proper movie by its title: my $imdbObj = new IMDB::Film(crit => 'Jack', year => 2003); print "Got #" . $imdbObj->code . " " . $imdbObj->title . "\n"; #0379836

proxy

defines proxy server name and port: proxy => 'http://proxy.myhost.com:80' By default object tries to get proxy from environment

debug

switches on debug mode to display useful debug messages. Can be 0 or 1 (0 by default)

cache

indicates use cache or not to store retrieved page content. Can be 0 or 1 (0 by default)

cache_root

specifies a directory to store cache data. By default it use /tmp/FileCache for *NIX \s-1OS\s0

cache_exp

specifies an expiration time for cache. By default, it's 1 hour

clear_cache

indicates clear cached data before get request to \s-1IMDB\s0.com or not

timeout

specifies a timeout for \s-1HTTP\s0 connection in seconds (10 sec by default)

user_agent

specifies an user agent for request ('Mozilla/5.0' by default)

full_plot_url

specifies a full plot url for specified movie

host

specifies a host name for \s-1IMDB\s0 site. By default it's www.imdb.com

query

specifies a query string to get specified movie by its \s-1ID\s0. By defualt it's 'title/tt'

search

specifies query string to make a search movie by its title. By default it's 'find?tt=on;mx=20;q=' Example: my $imdb = new IMDB::Film( crit => 'Troy', user_agent => 'Opera/8.x', timeout => 2, debug => 1, cache => 1, cache_root => '/tmp/imdb_cache', cache_exp => '1 d', ); It'll create an object with critery 'Troy', user agent 'Opera', timeout 2 seconds, debug mode on, using cache with directory '/tmp/imdb_cache' and expiration time in 1 day.

Object Private Methods

_search_film()

Implemets functionality to search film by name.

Object Public Methods

status()

Indicates a status of \s-1IMDB\s0 object: 0 - empty object; 1 - loaded from file; 2 - loaded from internet request; 3 - loaded from cache.

status_descr()

Return a description for \s-1IMDB\s0 object status. Can be 'Empty', 'Filed', 'Fresh' and 'Cached': if($film->status) { print "This is a " . $film->status_descr . " object!"; } else { die "Cannot retrieve IMDB object!"; }

title()

Retrieve film title from film page. If was got search page instead of film page this method calls method _search_film to get list matched films and continue to process first one: my $title = $film->title();

kind()

Get kind of movie: my $kind = $film->kind();

Possible values are: 'movie', 'tv series', 'tv mini series', 'video game', 'video movie', 'tv movie', 'episode'.

year()

Get film year: my $year = $film->year();

connections()

Retrieve connections for the movie as an arrays of hashes with folloeing structure { follows => [ { id => <id>, title => <name>, year => <year>, ..., } ], followed_by => [ { id => <id>, title => <name>, year => <year>, ..., } ], references => [ { id => <id>, title => <name>, year => <year>, ..., } ], referenced_in => [ { id => <id>, title => <name>, year => <year>, ..., } ], featured_in => [ { id => <id>, title => <name>, year => <year>, ..., } ], spoofed_by => [ { id => <id>, title => <name>, year => <year>, ..., } ], }

my %connections = %{ $film->connections() };

full_companies()

Retrieve companies for the movie as an array where each item has following stucture: { production => [ { name => <company name>, url => <imdb url>, extra => <specific task> } ], distributors => [ { name => <company name>, url => <imdb url>, extra => <specific task> } ], special_effects => [ { name => <company name>, url => <imdb url>, extra => <specific task> } ], other => [ { name => <company name>, url => <imdb url>, extra => <specific task> } ], }

my %full_companies = %{ $film->full_companies() };

company()

Returns a list of companies given for a specified movie: my $company = $film->company(); or my @companies = $film->company();

episodes()

Retrieve episodes info list each element of which is hash reference for tv series - { id => <\s-1ID\s0>, title => <Title>, season => <Season>, episode => <Episode>, date => <Date>, plot => <Plot> }: my @episodes = @{ $film->episodes() };

episodeof()

Retrieve parent tv series list each element of which is hash reference for episode - { id => <\s-1ID\s0>, title => <Title>, year => <Year> }: my @tvseries = @{ $film->episodeof() };

cover()

Retrieve url of film cover: my $cover = $film->cover();

recommendation_movies()

Return a list of recommended movies for specified one as a hash where each key is a movie \s-1ID\s0 in \s-1IMDB\s0 and value - movie's title: $recommendation_movies = $film->recommendation_movies(); For example, the list of recommended movies for Troy will be similar to that: _\|_DATA_\|_ $VAR1 = { '0416449' => '300', '0167260' => 'The Lord of the Rings: The Return of the King', '0442933' => 'Beowulf', '0320661' => 'Kingdom of Heaven', '0172495' => 'Gladiator' };

directors()

Retrieve film directors list each element of which is hash reference - { id => <\s-1ID\s0>, name => <Name> }: my @directors = @{ $film->directors() };

writers()

Retrieve film writers list each element of which is hash reference - { id => <\s-1ID\s0>, name => <Name> }: my @writers = @{ $film->writers() }; <I>Note: this method returns Writing credits from movie main page. It maybe not contain a full list!</I>

genres()

Retrieve film genres list: my @genres = @{ $film->genres() };

tagline()

Retrieve film tagline: my $tagline = $film->tagline();

plot()

Returns a movie plot: my $plot = $film->plot;

storyline()

Retrieve film plot summary: my $storyline = $film->storyline();

rating()

In scalar context returns film user rating, in array context returns film rating, number of votes and info about place in \s-1TOP\s0 250 or some other \s-1TOP\s0 and avards: my $rating = $film->rating();

or

my($rating, $vnum, $avards) = $film->rating(); print "RATING: $rating ($vnum votes)"; Note, that $avards is array reference where the first elemen is a \s-1TOP\s0 info if so, and the next element is other avards - Oscar, nominations and etc

cast()

Retrieve film cast list each element of which is hash reference - { id => <\s-1ID\s0>, name => <Full Name>, role => <Role> }: my @cast = @{ $film->cast() }; <I> Note: this method retrieves a cast list first billed only! </I>

duration()

In the scalar context it retrieves a film duration in minutes (the first record): my $duration = $film->duration(); In array context it retrieves all movie's durations: my @durations = $film->duration();

country()

Retrieve film produced countries list: my $countries = $film->country();

language()

Retrieve film languages list: my $languages = $film->language();

also_known_as()

Retrieve \s-1AKA\s0 information as array, each element of which is string: my $aka = $film->also_known_as();

print map { "$_\n" } @$aka;

trivia()

Retrieve a movie trivia: my $trivia = $film->trivia();

goofs()

Retrieve a movie goofs: my $goofs = $film->goofs();

awards()

Retrieve a general information about movie awards like 1 win & 1 nomination: my $awards = $film->awards();

mpaa_info()

Return a \s-1MPAA\s0 for the specified move: my mpaa = $film->mpaa_info();

aspect_ratio()

Returns an aspect ratio of specified movie: my $aspect_ratio = $film->aspect_ratio();

summary()

Retrieve film user summary: my $descr = $film->summary();

certifications()

Retrieve list of film certifications each element of which is hash reference - { country => certificate }: my @cert = $film->certifications();

full_plot

Return full movie plot. my $full_plot = $film->full_plot();

official_sites()

Returns a list of official sites of specified movie as array reference which contains hashes with site information - \s-1URL\s0 => Site Title: my $sites = $film->official_sites(); for(@$sites) { print "Site name - $_->{title}; url - $_->{url}\n"; }

release_dates()

Returns a list of release dates of specified movie as array reference: my $sites = $film->release_dates(); for(@$sites) { print "Country - $_->{country}; release date - $_->{date}; info - $_->{info}\n"; } Option info contains additional information about release - \s-1DVD\s0 premiere, re-release, restored version etc

Retrieve a list of plot keywords as an array reference: my $plot_keywords = $film->plot_keywords(); for my $keyword (@$plot_keywords) { print "keyword: $keyword\n"; }

Class Variables

Contains list all object's properties. See description of pragma \*(C`fields\*(C'. Matches \s-1USA\s0 film certification notation and age.

Nothing

If it's needed to get information from \s-1IMDB\s0 for a list of movies in some case it can be returned critical error:

[CRITICAL] Cannot retrieve page: 500 Can't read entity body ...

To catch an exception can be used eval:

for my $search_crit ("search_crit1", "search_crit2", ..., "search_critN") { my $ret; eval { $ret = new IMDB::Film(crit => "$search_crit") || print "UNKNOWN ERROR\n"; };

if($@) { # Opsssss! We got an exception! print "EXCEPTION: $@!"; next; } }

Please, send me any found bugs by email: [email protected] or create a bug report: http://rt.cpan.org/NoAuth/Bugs.html?Dist=IMDB-Film

IMDB::Persons IMDB::BaseClass WWW::Yahoo::Movies IMDB::Movie HTML::TokeParser

http://videoguide.sf.net

Michael Stepanov \s-1AKA\s0 nite_man ([email protected])

Copyright (c) 2004 - 2007, Michael Stepanov. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.