NAME

TVGuide::NL - fetch Dutch TV schedule from http://gids.omroep.nl/

SYNOPSIS

  use TVGuide::NL;
  $g = TVGuide::NL->new();
  print for $g->whats_on('ned1','rtl5','bbc2','cnn');
  print for $g->whats_next('ned1','rtl5','bbc2','cnn');

DESCRIPTION

The TVGuide::NL module is a perl interface to the TV schedules of http://gids.omroep.nl/.

Please note that you are allowed to use the data from http://gids.omroep.nl/ for your personal use only. Please refer to http://gids.omroep.nl/info/help.php#faq7 for more information on the copyright of the program scedule data.

METHODS

$g = TVGuide::NL->new( %options );

This is the constructor of the TVGuide::NL object.

The options hash allows you to specify certain behavioral changes of the modules. The following options are available:

cache

By default, a TVGuide::NL object caches the data it fetched from the web to a file 'tvguide.nl.$>.cache' in a temporary directory (usually /tmp/ on UNIX-flavored systems). This is done mainly to improve performance of the module.

The cache filename can be changed by setting this option. If the filename you specify does not contain any directory separators, the cache file is placed in a temporary directory. If you want to put the cache file in the current directory, prepend './' to the filename you specify.

Caching to disk can be disabled altogether by setting this option to a FALSE value. Note that this does not disable caching of the data in memory.

debug

Set the debug options to a true value to see noisy debug output.

$g->is_valid_station( $s )

This function can be used to check if a certain station name (e.g. 'BBC World'), code (e.g. 'Z44') or abbreviation (e.g. 'bbcw') is valid.

It returns 0 if the input is not a valid station, 1 if it is a name of a station, 2 if it is a station code and 3 if it is a station abbreviation.

$g->all_station_codes

Returns a list of Z-codes of all known stations.

$g->all_station_names

Returns a list of the names of all known stations.

@c = $g->station_code( @s )

This function converts a list of stations codes and/or abbreviations to the corresponding list of codes.

If this function is used in scalar context, and it is called with exactly 1 argument, it returns a scalar rather than a list.

The result is set to undef is the station is invalid or unknown.

For example:

        @c = $g->station_code( 'bbcw', 'z44', 'bbw', 'foobar');

returns ('Z44','Z44','Z44',undef), while

        $c = $g->station( 'bbcw' );

returns 'Z44'.

$n = $g->station_name( $c )

Returns the full name of the station with code or abbreviation $c.

$n = $g->station_abbr( $c )

Returns the abbreviation of the station $c.

$g->update_schedule( @s );

This method updates the schedules of the stations given in the arguments.

$g->update_movies( @s );

This method updates the movie schedule, retaining only movies that are broadcast on stations given in the arguments.

@p = $g->whats_on( @s )

returns an array containing the programs that are currently being shown on the channels @s.

@p = $g->whats_next( @s )

returns an array containing the programs that will be shown next on the channels @s.

$p = $g->whats_on_today( $s )

Returns an array containing the programs that are to be broadcast on the stations $s for the remainder of the day.

@p = $g->movies_today( $showall, @s )

This functions returns an array of movies that are on TV on the stations @s today. If $showall is true, all movies are returned, if it is false, only movies that have not ended yet are returned.

$t = $g->timestamp( $stat );

Returns the timestamp when the data for station $stat was last updated.

Returns undef if the station was invalid, 0 if the station was never updated.

DATA STRUCTURES

If you don't like the ready-to-use functions for displaying the data, you can also access the TV schedule directly. For example:

    use TVGuide::NL;
    use Data::Dumper;
    $g = TVGuide::NL->new;
    $g->update_schedule('ned1','ned2','ned3','bbc1','bbc2');
    $g->update_movies();
    print Data::Dumper($g->{schedule}->{today});

The structure of the $g->{schedule} hash is quite straightforward:

    $p = $g->{schedule}->{today}->{Z1}->{schedule}->[0]

is the record of the first program that's on station 'Z1' today; Z1 corresponds to 'ned1'; you can find this out by looking at the %TVGuide::NL::STATION_NAMES or %TVGuide::NL::CODE_LOOKUP hashes, or by calling %TVGuide::NL->station_name('Z1').

Schedules for other days than `today' are not currently implemented.

The field of this record are as follows:

    $p->{time}    the time at which the program starts
    $p->{title}   the name of the show
    $p->{desc}    a short description of the program (see CAVEATS)
    $p->{info}    an url with more info (prepend `http://gids.omroep.nl/')
    $p->{omroep}  the broadcasting association 

The movies are in the table with stations code `Z0'. These records are a bit different and have somewhat more information:

    $p->{time}      start time of the movie
    $p->{stop}      end time of the movie
    $p->{title}     title of the movie
    $p->{station}   station code (Znn) at which the movie is broadcast
    $p->{desc}      synopsis of the movies 
    $p->{info}      url for more infomation
    $p->{director}  the director of the movie
    $p->{year}      the year in which the movie was first released

EXAMPLES

For some examples on how to use this library, see the example CGI scripts that are included in the distribution.

NOTES

This module has currently only been tested with Perl 5.8.4. It might work with Perl 5.6, but it probably won't work with earlier versions because of the utf8-encoding issues. If you can confirm that it does or does not work using a specific pre-5.8 Perl version, please let me know.

CAVEATS

The descriptions of the programs is cut off after a (very limited) number of chars. This happens because the omroep.nl page simple doesn't show larger descriptions on their main schedule pages. It might be improved by parsing the print-ready page instead (which is on my TODO list).

BUGS

Many, most probably.

AUTHOR

TVGuide::NL was written by Bas Zoetekouw in 2005. Feel free to contact me at bas@debian.org with any questions, suggestions or patches.

COPYRIGHT

Copyright © 2005 by Bas Zoetekouw <bas@debian.org>. All rights reserved.

This program is free software; you may use it, (re)distribute it and/or modify it under either the terms of version 2 of the GNU General Public License or the terms of the Artistic License.

cpanm TVGuide::NL

perl -MCPAN -e shell
install TVGuide::NL