/ 
IMDB-Film-0.41
River stage one • 1 direct dependent • 1 total dependent
/ IMDB::Film

NAME

IMDB::Film - OO Perl interface to the movies database IMDB.

SYNOPSIS

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;
}

DESCRIPTION

Overview

IMDB::Film is an object-oriented interface to the IMDB. 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 IMDB 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 => <HTML 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 OS

cache_exp

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

clear_cache

indicates clear cached data before get request to IMDB.com or not

timeout

specifies a timeout for HTTP 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 IMDB site. By default it's www.imdb.com

query

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

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 IMDB object:

0 - empty object; 1 - loaded from file; 2 - loaded from internet request; 3 - loaded from cache.

status_descr()

Return a description for IMDB 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 an company given for a specified movie:

my $company = $film->company();
episodes()

Retrieve episodes info list each element of which is hash reference for tv series - { id => <ID>, 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 => <ID>, 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 ID in IMDB 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 => <ID>, name => <Name> }:

my @directors = @{ $film->directors() };
writers()

Retrieve film writers list each element of which is hash reference - { id => <ID>, 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()

Retrieve film plot summary:

my $plot = $film->plot();
rating()

In scalar context returns film user rating, in array context returns film rating, number of votes and info about place in TOP 250 or some other TOP:

my $rating = $film->rating();

or

my($rating, $vnum, $top_info) = $film->rating();
print "RATING: $rating ($vnum votes )";
cast()

Retrieve film cast list each element of which is hash reference - { id => <ID>, 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 AKA 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 MPAA 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 - URL => Site Title:

my $sites = $film->official_sites();
for(@$sites) {
	my($url, $title) = each %$_;
	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) {
	my($country, $date, $info) = each %$_;
	print "Country - $country; release date - $date; info - $info\n";
}

Option info contains additional information about release - DVD premiere, re-release, restored version etc

Class Variables

%FIELDS

Contains list all object's properties. See description of pragma fields.

@FILM_CERT

Matches USA film certification notation and age.

EXPORTS

Nothing

HOWTO CACTH EXCEPTIONS

If it's needed to get information from IMDB 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;
    	}
	}

BUGS

Please, send me any found bugs by email: stepanov.michael@gmail.com or create a bug report: http://rt.cpan.org/NoAuth/Bugs.html?Dist=IMDB-Film

SEE ALSO

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

http://videoguide.sf.net

AUTHOR

Michael Stepanov AKA nite_man (stepanov.michael@gmail.com)

COPYRIGHT

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.