File Coverage

blib/lib/WWW/Moviepilot.pm

Criterion	Covered	Total	%
statement	24	94	25.5
branch	0	12	0.0
condition	0	8	0.0
subroutine	8	18	44.4
pod	10	10	100.0
total	42	142	29.5

package WWW::Moviepilot;

use warnings;
use strict;

use Carp;
use JSON::Any;
use LWP::UserAgent;
use URI;
use URI::Escape;

use WWW::Moviepilot::Movie;

=head1 NAME

WWW::Moviepilot - Interface to the moviepilot.de database

=head1 VERSION

Version 0.04

=cut

our $VERSION = '0.04';

=head1 SYNOPSIS

    use WWW::Moviepilot;
    my $m = WWW::Moviepilot->new({
        api_key => ...,
        host    => 'www.moviepilot.de',
    });

    # direct retrieval
    my $movie = $m->movie( 'matrix' );

    # search
    my @movies = $m->search_movie( 'matrix' );
    foreach my $movie ( @movies ) {
        print $movie->display_title;
    }

    # cast of a movie
    my @cast = $m->cast( 'matrix' );
    foreach my $person ( @cast ) {
        print $person->last_name;
        print $person->character;
    }

    # filmography of a person
    my @filmography = $m->filmography( 'paul-newman' );
    foreach my $movie ( @filmography ) {
        print $movie->display_title;
        print $movie->character;
    }

I

=head1 METHODS

=head2 new( $args )

Creates a new WWW::Moviepilot instance.

    my $m = WWW::Moviepilot->new( $args );

C<$args> must be a hash reference, you should supply an API key:

    $args->{api_key} = ...;

To get a valid API key you should read L.

Further optional arguments:

=over 4

=item * C (default: C)

The host where the requests are sent to.

=item * C (default: C<< LWP::UserAgent->new >>)

A L compatible user agent.

=back

=cut

sub new {
    my ($class, $args) = @_;
    my $self = bless {} => $class;
    $self->{api_key} = $args->{api_key} || croak "api_key is missing at " . __PACKAGE__ . "->new()";
    $self->{host}    = $args->{host}    || 'www.moviepilot.de';
    $self->{ua}      = $args->{ua}      || LWP::UserAgent->new;

    $self->{host} = 'http://' . $self->{host} unless $self->{host} =~ m{^http://};

    return $self;
}

=head2 movie( $name ) | movie( $source => $id )

Retrieve a movie as L object.
There are two ways to specify which movie to retrieve.
First, you can provide the name of the movie (this name is some kind of normalised,
I'm not sure how exactly):

    my $movie = $m->movie( 'matrix' );

The second form is to provide an alternate ID:

    my $movie = $m->movie( imdb => '133093' );
    my $movie = $m->movie( amazon => 'B00004R80K' );

=cut

sub movie {
    my ($self, @args) = @_;

    my $url = $self->host . '/movies/';
    if ( @args > 2 ) {
        croak "invalid usage of " . __PACKAGE__ . "->movie()";
    }
    $url .= join '-id-', map { uri_escape($_) } @args;
    $url .= '.json';

    my $uri = URI->new( $url );
    $uri->query_form( api_key => $self->api_key );
    my $res = $self->ua->get( $uri->as_string );

    if( $res->is_error ) {
        croak $res->status_line;
    }

    my $json = JSON::Any->from_json( $res->decoded_content );

    my $movie = WWW::Moviepilot::Movie->new({ m => $self });
    $movie->populate({ data => { movie => $json } });
    return $movie;
}

=head2 search_movie( $query )

Searches for a movie and returns a list with results:

    my @movielist = $m->search_movie( 'matrix' );
    if ( @movielist == 0 ) {
        print 'no movies found';
    }
    else {
        # each $movie is a WWW::Moviepilot::Movie object
        foreach my $movie ( @movielist ) {
            print $movie->display_title;        # e.g. Matrix
            print $movie->production_year;      # e.g. 1999
            print scalar $movie->emotions_list; # e.g. Spannend,Aufregend

            # in list context, all *_list fields are split up by comma
            my @emotions = $movie->emotions_list;
        }
    }

At most there are 20 movies returned.

See L.

=cut

sub search_movie {
    my ($self, $query) = @_;

    my $uri = URI->new( $self->host . '/searches/movies.json' );
    $uri->query_form(
        api_key => $self->api_key,
        q       => $query,
    );

    my $res = $self->ua->get( $uri->as_string );
    if ( $res->is_error ) {
        croak $res->status_line;
    }

    my $o = JSON::Any->from_json( $res->decoded_content );

    my @result = ();
    foreach my $entry ( @{ $o->{movies} } ) {
        my $movie = WWW::Moviepilot::Movie->new({ m => $self });
        $movie->populate({ data => { movie => $entry } });
        push @result, $movie;
    }

    return @result;
}

=head2 person( $name )

Retrieve a person as L object.
You should provide the name of the movie (this name is some kind of normalised,
I'm not sure how exactly):

    my $person = $m->person( 'paul-newman' );

=cut

sub person {
    my ($self, $name) = @_;

    my $uri = URI->new( $self->host . '/people/' . uri_escape($name) . '.json' );
    $uri->query_form( api_key => $self->api_key );
    my $res = $self->ua->get( $uri->as_string );

    if( $res->is_error ) {
        croak $res->status_line;
    }

    my $json = JSON::Any->from_json( $res->decoded_content );
    my $person = WWW::Moviepilot::Person->new({ m => $self });
    $person->populate({ data => { person => $json } });
    return $person;
}

=head2 search_person( $query )

Searches for a person and returns a list with results:

    my @people = $m->search_person( 'Paul Newman' );
    if ( @people == 0 ) {
        print 'no people found';
    }
    else {
        # each $person is a WWW::Moviepilot::Person object
        foreach my $person ( @person ) {
            print $person->first_name; # e.g. Paul
            print $person->last_name;  # e.g. Newman
        }
    }

See L.

=cut

sub search_person {
    my ($self, $query) = @_;

    my $uri = URI->new( $self->host . '/searches/people.json' );
    $uri->query_form(
        api_key => $self->api_key,
        q       => $query,
    );

    my $res = $self->ua->get( $uri->as_string );
    if ( $res->is_error ) {
        croak $res->status_line;
    }

    my $o = JSON::Any->from_json( $res->decoded_content );

    my @result = ();
    foreach my $entry ( @{ $o->{people} } ) {
        my $person = WWW::Moviepilot::Person->new({ m => $self });
        $person->populate({ data => { person => $entry } });
        push @result, $person;
    }

    return @result;
}

=head2 cast( $name )

Returns the cast of a movie.

    my $m = WWW::Moviepilot->new(...);
    my @cast = $m->cast('brust-oder-keule');

See L.

=cut

sub cast {
    my ($self, $name) = @_;
    my $movie = WWW::Moviepilot::Movie->new({ m => $self });
    return $movie->cast( $name );
}

=head2 filmography( $name )

Returns the filmography of a person.

    my $m = WWW::Moviepilot->new(...);
    my @filmography = $m->filmography('paul-newman');

See L.

=cut

sub filmography {
    my ($self, $name) = @_;
    my $person = WWW::Moviepilot::Person->new({ m => $self });
    return $person->filmography( $name );
}

=head2 api_key

    my $api_key = $m->api_key;

Returns the API key provided to the C constructor.

=cut

sub api_key { return shift->{api_key} }

=head2 ua

    my $ua = $m->ua;

Returns the user agent, usually a L.

=cut

sub ua { return shift->{ua} }

=head2 host

    my $host = $m->host;

Returns host which the requests are sent to provided to the C constructor.

=cut

sub host { return shift->{host} }

1;
__END__