PostScript::ScheduleGrid::XMLTV - Create a printable TV listings grid from XMLTV data
This document describes version 0.03 of PostScript::ScheduleGrid::XMLTV, released October 12, 2013.
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.
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
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.
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
Keys you might want to include are:
The channel name as it should appear in the grid. By default, taken from the XMLTV
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
The number of lines that should be used for program listings. Defaults to the
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
This is the date and time at which the listings will end. Required.
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
en if that doesn't begin with a language code.
The number of lines that should be used for program listings (default 2). Can be overriden on a per-channel basis through the
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:
The title of the program.
The title of the episode. Will be appended to
show following a colon.
If this is a multi-part episode, a string like
undef. This will be appended to
show preceded by a space (after appending
episode, if any).
The category name for PostScript::ScheduleGrid.
The time at which the program begins.
The time at which the program is over.
A reference to the entry in
channels for the channel the program is appearing on.
For US listings from Schedules Direct, the
dd_progid identifying the episode.
The raw XMLTV data structure containing the information about this program occurrence.
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.)
This is the date and time at which the listings will begin. Required.
$decoded_text = $tv->decode($text);
This method decodes
$text using the encoding specified by XMLTV. May be used by
$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
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 = $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.
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.
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.
PostScript::ScheduleGrid::XMLTV requires no configuration files or environment variables.
You may also want to install Lingua::Preferred, which XMLTV uses to handle language selection.
No bugs have been reported.
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.
This software is copyright (c) 2013 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.
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.