The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
PostScript-ScheduleGrid-XMLTV-0.04
River stage zero No dependents
++
/ PostScript::ScheduleGrid::XMLTV

NAME

PostScript::ScheduleGrid::XMLTV - Create a printable TV listings grid from XMLTV data

VERSION

This document describes version 0.04 of PostScript::ScheduleGrid::XMLTV, released August 15, 2015.

SYNOPSIS

  use DateTime ();
  use PostScript::ScheduleGrid::XMLTV ();

  my $start_date = DateTime->today(time_zone => 'local');
  my $end_date   = $start_date->clone->add(days => 3);

  my $tv = PostScript::ScheduleGrid::XMLTV->new(
    start_date => $start_date,  end_date => $end_date,
  );

  my $grid = $tv->parsefiles('your_xmltv_datafile.xml')->grid;

  $grid->output('listings.ps');

See examples/example.pl for a more realistic example.

DESCRIPTION

PostScript::ScheduleGrid::XMLTV interfaces PostScript::ScheduleGrid with XMLTV to create printable TV listings. It is not a subclass of either module; instead, it creates a PostScript::ScheduleGrid object on demand.

It does not handle downloading the TV listings from their source. You should use one of the XMLTV grabbers to download listings and produce an XMLTV data file.

Then, you create a PostScript::ScheduleGrid::XMLTV object, call its parsefiles and/or parse methods to import the XMLTV data, and then call its grid method to get a PostScript::ScheduleGrid object. You can then call the grid's output method to save your printable listings in a PostScript file, or pass the grid to "psconvert" in PostScript::Convert to generate a PDF or bitmap image.

ATTRIBUTES

channel_settings

This is a hashref that allows you to override the default configuration for a channel. The key is either the channel ID assigned by XMLTV (e.g. I10183.labs.zap2it.com) or its default display name (e.g. 285 EWTN). (If both keys are present, both are used, but the channel ID takes precedence over the display name.) The value is merged with the default channel settings when creating entries in the channels hash.

Keys you might want to include are:

name

The channel name as it should appear in the grid. By default, taken from the XMLTV display-name.

Number

This controls the order in which channels appear in the grid. They are sorted in ascending order by Number (note the capitalization). Defaults to the first string of digits in the XMLTV display-name.

lines

The number of lines that should be used for program listings. Defaults to the lines_per_channel attribute.

channels

This is a hashref containing the schedule data. You don't normally deal directly with this; it's assembled from the XMLTV data. For advanced tasks, you could manipulate this hash between parsing the listings and calling the grid method.

end_date

This is the date and time at which the listings will end. Required.

languages

This is an arrayref of language codes identifying your prefered languages (as used by XMLTV's best_name function). By default, it's taken from $ENV{LANG}, or en if that doesn't begin with a language code.

lines_per_channel

The number of lines that should be used for program listings (default 2). Can be overriden on a per-channel basis through the channel_settings attribute.

program_callback

An optional CodeRef that will be called for each program occurrence. It receives a single hashref containing data about this occurrence, and can modify that hashref to alter the way the program will appear in the grid. The keys are:

show **

The title of the program.

episode **

The title of the episode. Will be appended to show following a colon.

part **

If this is a multi-part episode, a string like (1/2), otherwise undef. This will be appended to show preceded by a space (after appending episode, if any).

category **

The category name for PostScript::ScheduleGrid.

start **

The time at which the program begins.

stop **

The time at which the program is over.

channel

A reference to the entry in channels for the channel the program is appearing on.

dd_progid

For US listings from Schedules Direct, the dd_progid identifying the episode.

xml

The raw XMLTV data structure containing the information about this program occurrence.

parser

The PostScript::ScheduleGrid::XMLTV object that is parsing the data.

The keys identified with ** may be modified by the callback. (Note: while you can modify the start & stop times, you probably shouldn't.)

start_date

This is the date and time at which the listings will begin. Required.

METHODS

decode

  $decoded_text = $tv->decode($text);

This method decodes $text using the encoding specified by XMLTV. May be used by program_callback.

get_text

  $decoded_text = $tv->get_text(\@choices, [$specific]);

This method picks the best available language from the pairs in @choices using XMLTV's best_name function and returns that string after decoding it. It gets the list of languages to look for from the languages attribute.

If the optional parameter $specific is defined, then only an exact match to that language will be returned. It will return undef if an exact match is not found.

grid

  $grid = $tv->grid(...);

This method constructs and returns a PostScript::ScheduleGrid object using the supplied parameters and the current listings data. It may only be called once.

You may pass any parameters that are accepted by the PostScript::ScheduleGrid constructor, either in a single hashref, or as a list of key => value pairs.

parse

  $tv->parse($xmltv_document);

This method parses XMLTV data contained in a string, adding the program listings to the schedule. It returns the $tv object, so you can chain method calls.

parsefiles

  $tv->parsefiles($filename, ...);

This method parses one or more XMLTV data files, adding the program listings to the schedule. It returns the $tv object, so you can chain method calls.

CONFIGURATION AND ENVIRONMENT

PostScript::ScheduleGrid::XMLTV requires no configuration files or environment variables.

DEPENDENCIES

PostScript::ScheduleGrid::XMLTV requires PostScript::ScheduleGrid, DateTime::Format::XMLTV, Moose, MooseX::Types, MooseX::Types::DateTime, and namespace::autoclean.

You also need XMLTV (0.005 or later), which is not currently available from CPAN. You can get it at http://xmltv.org.

You may also want to install Lingua::Preferred, which XMLTV uses to handle language selection.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-PostScript-ScheduleGrid-XMLTV AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=PostScript-ScheduleGrid-XMLTV.

You can follow or contribute to PostScript-ScheduleGrid-XMLTV's development at https://github.com/madsen/postscript-schedulegrid-xmltv.

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Christopher J. Madsen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.