--- name: "IMDB::Film" section: "3pm" platform: "linux" package: "libimdb-film-perl" version: "0.53-1.1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/IMDB::Film" --- # IMDB::Film(3pm) OO Perl interface to the movies database IMDB. ## 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 => ); ``` or ``` my $imdb = new IMDB::Film(crit => ); ``` or \ my `$imdb` = new IMDB::Film(crit =\> \); 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 => , title => , year => , ..., } ], followed_by => [ { id => , title => , year => , ..., } ], references => [ { id => , title => , year => , ..., } ], referenced_in => [ { id => , title => , year => , ..., } ], featured_in => [ { id => , title => , year => , ..., } ], spoofed_by => [ { id => , title => , year => , ..., } ], } my %connections = %{ $film->connections() }; ``` - **full\_companies()** Retrieve companies for the movie as an array where each item has following stucture: ``` { production => [ { name => , url => , extra => } ], distributors => [ { name => , url => , extra => } ], special_effects => [ { name => , url => , extra => } ], other => [ { name => , url => , extra => } ], } 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 =\> \, title =\> \, season =\> \, episode =\> \, date =\> \, plot =\> \ }: ``` my @episodes = @{ $film->episodes() }; ``` - **episodeof()** Retrieve parent tv series list each element of which is hash reference for episode - { id =\> \, title =\> \, 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 =\> \, name =\> \ }: ``` my @directors = @{ $film->directors() }; ``` - **writers()** Retrieve film writers list each element of which is hash reference - { id =\> \, name =\> \ }: ``` my @writers = @{ $film->writers() }; ``` \Note: this method returns Writing credits from movie main page. It maybe not contain a full list!\ - **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 =\> \, name =\> \, role =\> \ }: ``` my @cast = @{ $film->cast() }; ``` \ Note: this method retrieves a cast list first billed only! \ - **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