xmltv-util 0.5.67-0.1 / usr / bin / tv_grab_fr_kazer

#!/usr/bin/perl -w

eval 'exec /usr/bin/perl -w -S $0 ${1+"$@"}'
    if 0; # not running under some shell

=pod

=head1 NAME

tv_grab_fr_kazer - Grab TV listings from Kazer in France.

=head1 SYNOPSIS

tv_grab_fr_kazer --help

tv_grab_fr_kazer --configure [--config-file FILE]

tv_grab_fr_kazer [--config-file FILE]
                 [--days N] [--offset N] [--channel xmltvid,xmltvid,...]
                 [--output FILE] [--quiet] [--debug]

tv_grab_fr_kazer --list-channels [--config-file FILE]
                 [--output FILE] [--quiet] [--debug]
                 
                
=head1 DESCRIPTION

Output TV and listings in XMLTV format for many stations
available in France. This program consumes the EPG service offering
from Kazer at L<http://www.kazer.org/>.
See TODO INSERTLINKHERE
for their terms of service. (automatic translation suggests it's free
for personal use, verfication appreciated)

First you must register an account at kazer.org and choose which stations
you want to receive.

Then run B<tv_grab_fr_kazer --configure> to setup the grabber with your
userhash and maybe filter the channels. (in case you feed multiple
consumers with data from one account, like using different configurations
for tv cable and iptv channels)

After these two steps running B<tv_grab_fr_kazer> with no arguments will
get a listings for the stations you chose for all available days
including today.

ATTENTION: The downloaded data is cached for one hour, so if you add channels
to your account it can take up to one hour until they are returned from the
grabber. You can remove the downloaded guide to force an immediate refresh
by deleteing the guide from the supplementry file cache. On Unix like system
it is by default at ~/.xmltv/supplement/tvguide.zip?u=<your userhash>.

=head1 OPTIONS

B<--configure> Prompt for which stations to download and write the
configuration file.

Note that due to the format of the source data, tv_grab_fr_kazer always
downloads data for all channels that have been selected on kazer.org.
Removing channels from the configuration in order to speed up downloads or
reduce data transfer will therefore not work.

B<--config-file FILE> Set the name of the configuration file, the
default is B<~/.xmltv/tv_grab_fr_kazer.conf>.  This is the file written by
B<--configure> and read when grabbing.

B<--output FILE> When grabbing, write output to FILE rather than
standard output.

B<--days N> When grabbing, grab N days rather than everything available.

B<--offset N> Start grabbing at today + N days.

Note that due to the format of the source data, tv_grab_fr_kazer always
downloads data for all available days and then filters for days specified
with --days and --offset. Specifying --days and/or --offset in order to
speed up downloads or reduce data transfer will therefore not work.

B<--quiet> Only print error-messages on STDERR.

B<--debug> Provide more information on progress to stderr to help in
debugging.

B<--list-channels>    Output a list of all channels that data is available
                      for. The list is in xmltv-format.

B<--capabilities> Show which capabilities the grabber supports. For more
information, see L<http://wiki.xmltv.org/index.php/XmltvCapabilities>

B<--version> Show the version of the grabber.

B<--help> Print a help message and exit.

=head1 ERROR HANDLING

If the grabber fails to download data from kazer.org, it will print an 
errormessage to STDERR and then exit with a status code of 1 to indicate 
that the data is missing. 

=head1 ENVIRONMENT VARIABLES

The environment variable HOME can be set to change where configuration
files are stored. All configuration is stored in $HOME/.xmltv/. On Windows,
it might be necessary to set HOME to a path without spaces in it.

=head1 CREDITS

Grabber written by Karl Dietz, dekarl -at- users -dot- sourceforge -dot- net
as a an example on how to wrap a file download into a well formed grabber.
This documentation copied from tv_grab_cz by Mattias Holmlund,
This documentation copied from tv_grab_uk by Ed Avis, 
ed -at- membled -dot- com. Original grabber by Jiri Kaderavek,
jiri -dot- kaderavek -at- webstep -dot- net with modifications by
Petr Stehlik, pstehlik -at- sophics -dot- cz.

Data provided via web service from kazer.org. Check their terms of usage!

=head1 BUGS

None known.

=cut

use strict;
use DateTime;
use Encode; # used to convert 'perl strings' into 'utf-8 strings'
use IO::Uncompress::Unzip qw/unzip/;
use XML::LibXML;

use XMLTV::Configure::Writer;
use XMLTV::Options qw/ParseOptions/;
use XMLTV::Supplement qw/GetSupplement SetSupplementRoot/;

# TODO verify if we need to switch between kazer.org and xmltv.org to avoid messing with the downloaded xmltv.dtd
SetSupplementRoot( 'http://www.kazer.org/' );

# kazer.org holds 7-8 days currently, likely to raise to 14 in the future.
my $maxdays = 1+14; # data source is limited to n days (including today)

my( $opt, $conf ) = ParseOptions( { 
    grabber_name => "tv_grab_fr_kazer",
    capabilities => [qw/apiconfig baseline manualconfig preferredmethod/],
    listchannels_sub => \&list_channels,
    stage_sub => \&config_stage,
    version => '$Id: tv_grab_fr_kazer,v 1.7 2015/06/27 00:30:54 knowledgejunkie Exp $',
    description => "France (Kazer)",
    # prefer 'allatonce' as we download one big zip file and filter it afterwards
    preferredmethod => 'allatonce',
    defaults => { days => $maxdays, offset => 0, quiet => 0, debug => 0 },
} );

if (not defined( $conf->{'userhash'} )) {
    print STDERR "No userhash selected in configfile " .
                 $opt->{'config-file'} . "\n" .
                 "Please run the grabber with --configure.\n";
    exit 1;
}

if (not defined( $conf->{'channel'} )) {
    print STDERR "No channels selected in configfile " .
                 $opt->{'config-file'} . "\n" .
                 "Please run the grabber with --configure.\n";
    exit 1;
}

# hash of channels for the channel/programme callback
my %channels = map { $_ => $_ } @{$conf->{channel}};

# limit to maxdays in the future
if ($opt->{offset} + $opt->{days} > $maxdays) {
    $opt->{days} = $maxdays - $opt->{offset};
}

if ($opt->{days} < 1) {
    $opt->{days} = 0;
}

# Get the actual data and print it to stdout.
my $is_success=1;

my $epgsource;
my $epgsourcezip;
if ($opt->{days} > 0) {
    $epgsourcezip = GetSupplement( undef, 'tvguide.zip?u=' . $conf->{'userhash'}->[0] );
} else {
    if( !$opt->{quiet} ) {
        print( STDERR "no data available for the requested time period\n" );
    }
    $is_success = 0;
}

unzip \$epgsourcezip => \$epgsource;

# TODO some fixups, they have been reported to the site and can be remove once they are not needed anymore
# FIXME XMLTV::parse_callback doesn't seem to read role=""
#$epgsource =~ s|<actor>(.*?) \((.*?)\)</actor>|<actor role="$2">$1</actor>|g;


# === setup writer ===
my %w_args = (
    cutoff => '000000',
    days => $opt->{days},
    encoding => 'UTF-8',
    offset => $opt->{offset}
);

my $writer = new XMLTV::Writer( %w_args );
# as suggested on http://wiki.xmltv.org/index.php/Supplementary_Files
# FIXME does not work because the XMLTV::Writer forces a SYSTEM of xmltv.id on us
#$writer->doctype( 'tv', undef, 'http://supplement.xmltv.org/xmltv.dtd' );
$writer->start({
    'generator-info-name' => 'XMLTV/$Id: tv_grab_fr_kazer,v 1.7 2015/06/27 00:30:54 knowledgejunkie Exp $',
    'generator-info-url' => 'http://www.xmltv.org/',
    'source-info-name' => 'KaZeR\'s XMLTV',
    'source-info-url' => 'http://www.kazer.org/',
});


# === the callbacks ===
my $encoding;
sub encoding_cb( $ ) { $encoding = shift }

my $credits;
sub credits_cb( $ ) { $credits = shift }

# The callback for each channel gets filtered by the hash of configured channels.
sub channel_cb( $ ) {
    my $c = shift;

    if( defined( $channels{$c->{id}} ) ) {
        $writer->write_channel($c);
    }
}

# The callback for each programme.  We know that channels are
# always read before programmes, so the %channels hash will be
# fully populated.
#
# It just filters the programmes by configured channel. The filtering by time is done by the Writer itself.
#
sub programme_cb( $ ) {
    my $p = shift;

    if( defined( $channels{$p->{channel}} ) ) {
        $writer->write_programme($p);
    }
}


# Let's go.
XMLTV::parse_callback($epgsource, \&encoding_cb, \&credits_cb,
                      \&channel_cb, \&programme_cb);


$writer->end();

if( $is_success ) {
     exit 0;
} else {
     exit 1;
}

sub config_stage
{
     my( $stage, $conf ) = @_;

     # Sample stage_sub that only needs a single stage.

     die "Unknown stage $stage" if $stage ne "start";

     my $result;
     my $writer = new XMLTV::Configure::Writer( OUTPUT => \$result,
                                                              encoding => 'utf-8' );
     $writer->start( { grabber => 'tv_grab_fr_kazer' } );

     # TODO add french strings
     $writer->write_string( {
         id => 'userhash',
         title => [ [ 'Userhash', 'en' ] ],
         description => [ [ 'Your userhash at kazer.org. It is shown on ' .
             'http://www.kazer.org/my-channels.html together with your ' .
             'selection of channels.', 'en' ],
             [ encode('utf-8', "Votre userhash pour kazer.org. Il est indiqu\xe9 sur " .
             'http://www.kazer.org/my-channels.html au dessus du ' .
             "s\xe9lecteur de cha\xeenes." ), 'fr' ] ],
         default => '',
     } );

     $writer->end( 'select-channels' );

     return $result;
}

sub list_channels
{
     my( $conf, $opt ) = @_;

     # Return a string containing an xmltv-document with <channel>-elements
     # for all available channels.

     my $channellist = GetSupplement( undef, 'tvguide.zip?u=' . $conf->{'userhash'}->[0] );
     my $xml;
     unzip \$channellist => \$xml;

     my $parser=XML::LibXML->new();
     my $input=$parser->parse_string( $xml )->getDocumentElement();

     my $output=XML::LibXML::Document->new( '1.0', 'utf-8' );
     my $root=XML::LibXML::Element->new( 'tv' );
     $output->setDocumentElement( $root );

     foreach my $channel( $input->getElementsByTagName( 'channel') ) {
         $root->appendChild( $channel );
     }

     return $output->toString();
}