Provided by: libimdb-film-perl_0.53-1.1_all bug

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'

       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 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 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 => <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()
           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 TOP 250 or some other TOP 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 TOP 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 => <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) {
                           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 - DVD 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
       %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.

POD ERRORS

       Hey! The above document had some coding errors, which are explained below:

       Around line 1522:
           Expected text after =item, not a bullet