.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IMDB::Film 3pm"
.TH IMDB::Film 3pm "2013-01-02" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
IMDB::Film \- OO Perl interface to the movies database IMDB.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        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 => \*(AqTroy\*(Aq);
\&
\&        or
\&
\&        #
\&        # Parse already stored HTML page from IMDB
\&        #
\&        my $imdbObj = new IMDB::Film(crit => \*(Aqtroy.html\*(Aq);
\&
\&        if($imdbObj\->status) {
\&                print "Title: ".$imdbObj\->title()."\en";
\&                print "Year: ".$imdbObj\->year()."\en";
\&                print "Plot Symmary: ".$imdbObj\->plot()."\en";
\&        } else {
\&                print "Something wrong: ".$imdbObj\->error;
\&        }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "Overview"
.IX Subsection "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.
.SS "Constructor"
.IX Subsection "Constructor"
.IP "\fInew()\fR" 4
.IX Item "new()"
Object's constructor. You should pass as parameter movie title or \s-1IMDB\s0 code.
.Sp
.Vb 1
\&        my $imdb = new IMDB::Film(crit => <some code>);
.Ve
.Sp
or
.Sp
.Vb 1
\&        my $imdb = new IMDB::Film(crit => <some title>);
.Ve
.Sp
or 
	my \f(CW$imdb\fR = new IMDB::Film(crit => <\s-1HTML\s0 file>);
.Sp
For more infomation about base methods refer to IMDB::BaseClass.
.IP "\fI_init()\fR" 4
.IX Item "_init()"
Initialize object.
.SS "Options"
.IX Subsection "Options"
.IP "year" 4
.IX Item "year"
Define a movie's year. It's useful to use it to get the proper movie by its title:
.Sp
.Vb 2
\&        my $imdbObj = new IMDB::Film(crit => \*(AqJack\*(Aq, year => 2003);
\&        print "Got #" . $imdbObj\->code . " " . $imdbObj\->title . "\en"; #0379836
.Ve
.IP "proxy" 4
.IX Item "proxy"
defines proxy server name and port:
.Sp
.Vb 1
\&        proxy => \*(Aqhttp://proxy.myhost.com:80\*(Aq
.Ve
.Sp
By default object tries to get proxy from environment
.IP "debug" 4
.IX Item "debug"
switches on debug mode to display useful debug messages. Can be 0 or 1 (0 by default)
.IP "cache" 4
.IX Item "cache"
indicates use cache or not to store retrieved page content. Can be 0 or 1 (0 by default)
.IP "cache_root" 4
.IX Item "cache_root"
specifies a directory to store cache data. By default it use /tmp/FileCache for *NIX \s-1OS\s0
.IP "cache_exp" 4
.IX Item "cache_exp"
specifies an expiration time for cache. By default, it's 1 hour
.IP "clear_cache" 4
.IX Item "clear_cache"
indicates clear cached data before get request to \s-1IMDB\s0.com or not
.IP "timeout" 4
.IX Item "timeout"
specifies a timeout for \s-1HTTP\s0 connection in seconds (10 sec by default)
.IP "user_agent" 4
.IX Item "user_agent"
specifies an user agent for request ('Mozilla/5.0' by default)
.IP "full_plot_url" 4
.IX Item "full_plot_url"
specifies a full plot url for specified movie
.IP "host" 4
.IX Item "host"
specifies a host name for \s-1IMDB\s0 site. By default it's www.imdb.com
.IP "query" 4
.IX Item "query"
specifies a query string to get specified movie by its \s-1ID\s0. By defualt it's 'title/tt'
.IP "search" 4
.IX Item "search"
specifies query string to make a search movie by its title. By default it's  'find?tt=on;mx=20;q='
.Sp
Example:
.Sp
.Vb 8
\&        my $imdb = new IMDB::Film(      crit            => \*(AqTroy\*(Aq,
\&                                                                user_agent      => \*(AqOpera/8.x\*(Aq,
\&                                                                timeout         => 2,
\&                                                                debug           => 1,
\&                                                                cache           => 1,
\&                                                                cache_root      => \*(Aq/tmp/imdb_cache\*(Aq,
\&                                                                cache_exp       => \*(Aq1 d\*(Aq,
\&                                                        );
.Ve
.Sp
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.
.SS "Object Private Methods"
.IX Subsection "Object Private Methods"
.IP "\fI_search_film()\fR" 4
.IX Item "_search_film()"
Implemets functionality to search film by name.
.SS "Object Public Methods"
.IX Subsection "Object Public Methods"
.IP "\fIstatus()\fR" 4
.IX Item "status()"
Indicates a status of \s-1IMDB\s0 object:
.Sp
0 \- empty object;
1 \- loaded from file;
2 \- loaded from internet request;
3 \- loaded from cache.
.IP "\fIstatus_descr()\fR" 4
.IX Item "status_descr()"
Return a description for \s-1IMDB\s0 object status. Can be 'Empty', 'Filed', 'Fresh' and 'Cached':
.Sp
.Vb 5
\&        if($film\->status) {
\&                print "This is a " . $film\->status_descr . " object!";
\&        } else {
\&                die "Cannot retrieve IMDB object!";
\&        }
.Ve
.IP "\fItitle()\fR" 4
.IX Item "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:
.Sp
.Vb 1
\&        my $title = $film\->title();
.Ve
.IP "\fIkind()\fR" 4
.IX Item "kind()"
Get kind of movie:
.Sp
.Vb 1
\&        my $kind = $film\->kind();
\&
\&        Possible values are: \*(Aqmovie\*(Aq, \*(Aqtv series\*(Aq, \*(Aqtv mini series\*(Aq, \*(Aqvideo game\*(Aq, \*(Aqvideo movie\*(Aq, \*(Aqtv movie\*(Aq, \*(Aqepisode\*(Aq.
.Ve
.IP "\fIyear()\fR" 4
.IX Item "year()"
Get film year:
.Sp
.Vb 1
\&        my $year = $film\->year();
.Ve
.IP "\fIconnections()\fR" 4
.IX Item "connections()"
Retrieve connections for the movie as an arrays of hashes with folloeing structure
.Sp
.Vb 8
\&        { 
\&                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() };
.Ve
.IP "\fIfull_companies()\fR" 4
.IX Item "full_companies()"
Retrieve companies for the movie as an array where each item has following stucture:
.Sp
.Vb 6
\&        { 
\&                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() };
.Ve
.IP "\fIcompany()\fR" 4
.IX Item "company()"
Returns a list of companies given for a specified movie:
.Sp
.Vb 1
\&  my $company = $film\->company();
.Ve
.Sp
or
.Sp
.Vb 1
\& my @companies = $film\->company();
.Ve
.IP "\fIepisodes()\fR" 4
.IX Item "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> }:
.Sp
.Vb 1
\&        my @episodes = @{ $film\->episodes() };
.Ve
.IP "\fIepisodeof()\fR" 4
.IX Item "episodeof()"
Retrieve parent tv series list each element of which is hash reference for episode \-
{ id => <\s-1ID\s0>, title => <Title>, year => <Year> }:
.Sp
.Vb 1
\&        my @tvseries = @{ $film\->episodeof() };
.Ve
.IP "\fIcover()\fR" 4
.IX Item "cover()"
Retrieve url of film cover:
.Sp
.Vb 1
\&        my $cover = $film\->cover();
.Ve
.IP "\fIrecommendation_movies()\fR" 4
.IX Item "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:
.Sp
.Vb 1
\&        $recommendation_movies = $film\->recommendation_movies();
.Ve
.Sp
For example, the list of recommended movies for Troy will be similar to that:
.Sp
.Vb 8
\&        _\|_DATA_\|_
\&        $VAR1 = {                                                                                                                                 
\&          \*(Aq0416449\*(Aq => \*(Aq300\*(Aq,                                                                                                             
\&          \*(Aq0167260\*(Aq => \*(AqThe Lord of the Rings: The Return of the King\*(Aq,                                                                   
\&          \*(Aq0442933\*(Aq => \*(AqBeowulf\*(Aq,                                                                                                         
\&          \*(Aq0320661\*(Aq => \*(AqKingdom of Heaven\*(Aq,                                                                                               
\&          \*(Aq0172495\*(Aq => \*(AqGladiator\*(Aq                                                                                                        
\&        };
.Ve
.IP "\fIdirectors()\fR" 4
.IX Item "directors()"
Retrieve film directors list each element of which is hash reference \-
{ id => <\s-1ID\s0>, name => <Name> }:
.Sp
.Vb 1
\&        my @directors = @{ $film\->directors() };
.Ve
.IP "\fIwriters()\fR" 4
.IX Item "writers()"
Retrieve film writers list each element of which is hash reference \-
{ id => <\s-1ID\s0>, name => <Name> }:
.Sp
.Vb 1
\&        my @writers = @{ $film\->writers() };
.Ve
.Sp
<I>Note: this method returns Writing credits from movie main page. It maybe not 
contain a full list!</I>
.IP "\fIgenres()\fR" 4
.IX Item "genres()"
Retrieve film genres list:
.Sp
.Vb 1
\&        my @genres = @{ $film\->genres() };
.Ve
.IP "\fItagline()\fR" 4
.IX Item "tagline()"
Retrieve film tagline:
.Sp
.Vb 1
\&        my $tagline = $film\->tagline();
.Ve
.IP "\fIplot()\fR" 4
.IX Item "plot()"
Returns a movie plot:
.Sp
.Vb 1
\&        my $plot = $film\->plot;
.Ve
.IP "\fIstoryline()\fR" 4
.IX Item "storyline()"
Retrieve film plot summary:
.Sp
.Vb 1
\&        my $storyline = $film\->storyline();
.Ve
.IP "\fIrating()\fR" 4
.IX Item "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:
.Sp
.Vb 1
\&        my $rating = $film\->rating();
\&
\&        or
\&
\&        my($rating, $vnum, $avards) = $film\->rating();
\&        print "RATING: $rating ($vnum votes)";
.Ve
.Sp
Note, that \f(CW$avards\fR 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
.IP "\fIcast()\fR" 4
.IX Item "cast()"
Retrieve film cast list each element of which is hash reference \-
{ id => <\s-1ID\s0>, name => <Full Name>, role => <Role> }:
.Sp
.Vb 1
\&        my @cast = @{ $film\->cast() };
.Ve
.Sp
<I>
Note: this method retrieves a cast list first billed only!
</I>
.IP "\fIduration()\fR" 4
.IX Item "duration()"
In the scalar context it retrieves a film duration in minutes (the first record):
.Sp
.Vb 1
\&        my $duration = $film\->duration();
.Ve
.Sp
In array context it retrieves all movie's durations:
.Sp
.Vb 1
\&        my @durations = $film\->duration();
.Ve
.IP "\fIcountry()\fR" 4
.IX Item "country()"
Retrieve film produced countries list:
.Sp
.Vb 1
\&        my $countries = $film\->country();
.Ve
.IP "\fIlanguage()\fR" 4
.IX Item "language()"
Retrieve film languages list:
.Sp
.Vb 1
\&        my $languages = $film\->language();
.Ve
.IP "\fIalso_known_as()\fR" 4
.IX Item "also_known_as()"
Retrieve \s-1AKA\s0 information as array, each element of which is string:
.Sp
.Vb 1
\&        my $aka = $film\->also_known_as();
\&
\&        print map { "$_\en" } @$aka;
.Ve
.IP "\fItrivia()\fR" 4
.IX Item "trivia()"
Retrieve a movie trivia:
.Sp
.Vb 1
\&        my $trivia = $film\->trivia();
.Ve
.IP "\fIgoofs()\fR" 4
.IX Item "goofs()"
Retrieve a movie goofs:
.Sp
.Vb 1
\&        my $goofs = $film\->goofs();
.Ve
.IP "\fIawards()\fR" 4
.IX Item "awards()"
Retrieve a general information about movie awards like 1 win & 1 nomination:
.Sp
.Vb 1
\&        my $awards = $film\->awards();
.Ve
.IP "\fImpaa_info()\fR" 4
.IX Item "mpaa_info()"
Return a \s-1MPAA\s0 for the specified move:
.Sp
.Vb 1
\&        my mpaa = $film\->mpaa_info();
.Ve
.IP "\fIaspect_ratio()\fR" 4
.IX Item "aspect_ratio()"
Returns an aspect ratio of specified movie:
.Sp
.Vb 1
\&        my $aspect_ratio = $film\->aspect_ratio();
.Ve
.IP "\fIsummary()\fR" 4
.IX Item "summary()"
Retrieve film user summary:
.Sp
.Vb 1
\&        my $descr = $film\->summary();
.Ve
.IP "\fIcertifications()\fR" 4
.IX Item "certifications()"
Retrieve list of film certifications each element of which is hash reference \-
{ country => certificate }:
.Sp
.Vb 1
\&        my @cert = $film\->certifications();
.Ve
.IP "full_plot" 4
.IX Item "full_plot"
Return full movie plot.
.Sp
.Vb 1
\&        my $full_plot = $film\->full_plot();
.Ve
.IP "\fIofficial_sites()\fR" 4
.IX Item "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:
.Sp
.Vb 4
\&        my $sites = $film\->official_sites();
\&        for(@$sites) {
\&                print "Site name \- $_\->{title}; url \- $_\->{url}\en";
\&        }
.Ve
.IP "\fIrelease_dates()\fR" 4
.IX Item "release_dates()"
Returns a list of release dates of specified movie as array reference:
.Sp
.Vb 4
\&        my $sites = $film\->release_dates();
\&        for(@$sites) {
\&                print "Country \- $_\->{country}; release date \- $_\->{date}; info \- $_\->{info}\en";
\&        }
.Ve
.Sp
Option info contains additional information about release \- \s-1DVD\s0 premiere, re-release, restored version etc
.IP "" 4
Retrieve a list of plot keywords as an array reference:
.Sp
.Vb 4
\&        my $plot_keywords = $film\->plot_keywords();
\&        for my $keyword (@$plot_keywords) {
\&                print "keyword: $keyword\en";
\&        }
.Ve
.SS "Class Variables"
.IX Subsection "Class Variables"
.ie n .IP "%FIELDS" 4
.el .IP "\f(CW%FIELDS\fR" 4
.IX Item "%FIELDS"
Contains list all object's properties. See description of pragma \f(CW\*(C`fields\*(C'\fR.
.ie n .IP "@FILM_CERT" 4
.el .IP "\f(CW@FILM_CERT\fR" 4
.IX Item "@FILM_CERT"
Matches \s-1USA\s0 film certification notation and age.
.SH "EXPORTS"
.IX Header "EXPORTS"
Nothing
.SH "HOWTO CACTH EXCEPTIONS"
.IX Header "HOWTO CACTH EXCEPTIONS"
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:
.PP
.Vb 1
\&        [CRITICAL] Cannot retrieve page: 500 Can\*(Aqt read entity body ...
.Ve
.PP
To catch an exception can be used eval:
.PP
.Vb 5
\&        for my $search_crit ("search_crit1", "search_crit2", ..., "search_critN") {
\&        my $ret;
\&        eval {
\&                $ret = new IMDB::Film(crit => "$search_crit") || print "UNKNOWN ERROR\en";
\&        };
\&
\&        if($@) {
\&                # Opsssss! We got an exception!
\&                print "EXCEPTION: $@!";
\&                next;
\&        }
\&        }
.Ve
.SH "BUGS"
.IX Header "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
.SH "SEE ALSO"
.IX Header "SEE ALSO"
IMDB::Persons 
IMDB::BaseClass
WWW::Yahoo::Movies
IMDB::Movie
HTML::TokeParser
.PP
http://videoguide.sf.net
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael Stepanov \s-1AKA\s0 nite_man (stepanov.michael@gmail.com)
.SH "COPYRIGHT"
.IX Header "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.