Linux Certif

Toute la documentation sur la certification Linux LPI

XMLTV::Lineup.3pm

NAME

XMLTV::Lineup - Perl extension to read and write TV lineup information in XMLTV lineup format

write_data(data, options...)

Takes a data structure and writes it as XML to standard output. Any extra arguments are passed on to XML::Writer's constructor, for example

     my $f = new IO::File '>out.xml'; die if not $f;
     write_data($data, OUTPUT => $f);
 
 

The encoding used for the output is given by the first element of the data.

Normally, there will be a warning for any Perl data which is not understood and cannot be written as XMLTV, such as strange keys in hashes. But as an exception, any hash key beginning with an underscore will be skipped over silently. You can store 'internal use only' data this way.

If a display name or channel hash contains a key beginning with 'debug', this key and its value will be written out as a comment inside the <display-name> or <channel> element. This lets you include small debugging messages in the XML output.

best_name(languages, pairs [, comparator])

The XMLTV format contains many places where human-readable text is given an optional 'lang' attribute, to allow mixed languages. This is represented in Perl as a pair [ text, lang ], although the second element may be missing or undef if the language is unknown. When several alernatives for an element (such as <title>) can be given, the representation is a list of [ text, lang ] pairs. Given such a list, what is the best text to use? It depends on the user's preferred language.

This function takes a list of acceptable languages and a list of [string, language] pairs, and finds the best one to use. This means first finding the appropriate language and then picking the 'best' string in that language.

The best is normally defined as the first one found in a usable language, since the XMLTV format puts the most canonical versions first. But you can pass in your own comparison function, for example if you want to choose the shortest piece of text that is in an acceptable language.

The acceptable languages should be a reference to a list of language codes looking like 'ru', or like 'de_DE'. The text pairs should be a reference to a list of pairs [ string, language ]. (As a special case if this list is empty or undef, that means no text is present, and the result is undef.) The third argument if present should be a cmp-style function that compares two strings of text and returns 1 if the first argument is better, -1 if the second better, 0 if they're equally good.

Returns: [s, l] pair, where s is the best of the strings to use and l is its language. This pair is 'live' - it is one of those from the list passed in. So you can use "best_name()" to find the best pair from a list and then modify the content of that pair.

(This routine depends on the "Lingua::Preferred" module being installed; if that module is missing then the first available language is always chosen.)

Example:

     my $langs = [ 'de', 'fr' ]; # German or French, please
 
     # Say we found the following under $ch->{display-name} for a channel $ch.
     my $pairs = [ [ 'BBC Trois', 'fr' ],
                   [ 'BBC One', 'en_US' ] ];
 
     my $best = best_name($langs, $pairs);
     print "chose title $best->[0]\n";
 
 

list_display_name_keys(), list_channel_keys()

Some users of this module may wish to enquire at runtime about which keys a programme or channel hash can contain. The data in the hash comes from the attributes and subelements of the corresponding element in the XML. The values of attributes are simply stored as strings, while subelements are processed with a handler which may return a complex data structure. These subroutines returns a hash mapping key to handler name and multiplicity. This lets you know what data types can be expected under each key. For keys which come from attributes rather than subelements, the handler is set to 'scalar', just as for subelements which give a simple string.

scalar

Reads and writes a simple string as the content of the XML element.

icon

An icon in XMLTV files is like the <img> element in HTML. It is represented in Perl as a hashref with 'src' and optionally 'width' and 'height' keys.

with-lang

In XML something like title can be either <title>Foo</title> or <title lang=``en''>Foo</title>. In Perl these are stored as [ 'Foo' ] and [ 'Foo', 'en' ]. For the former [ 'Foo', undef ] would also be okay.

This handler also has two modifiers which may be added to the name after '/'. /e means that empty text is allowed, and will be returned as the empty tuple [], to mean that the element is present but has no text. When writing with /e, undef will also be understood as present-but-empty. You cannot however specify a language if the text is empty.

The modifier /m means that the text is allowed to span multiple lines.

So for example with-lang/em is a handler for text with language, where the text may be empty and may contain newlines. Note that the with-lang-or-empty of earlier releases has been replaced by with-lang/e.

Now, which handlers are used for which subelements (keys) of display names and channels? And what is the multiplicity (should you expect a single value or a list of values)?

The following tables map subelements of <display-name> and of <channel> to the handlers used to read and write them. Many elements have their own handler with the same name, and most of the others use with-lang. The third column specifies the multiplicity of the element: * (any number) will give a list of values in Perl, + (one or more) will give a nonempty list, ? (maybe one) will give a scalar, and 1 (exactly one) will give a scalar which is not undef.

Handlers for <channel>

display-name, with-lang, +

icon, icon, *

homepage-url, scalar, ?

old-id, scalar, *

preferred-preset, scalar, ?

service-id, scalar, ?

transport-id, scalar, ?

network-id, scalar, ?

freq-number, scalar, ?

freq-hertz, scalar, ?

iptv-addr, scalar, ?

multicast-addr, scalar, ?

multicast-port, scalar, ?

preset, scalar, ?

WRITING

When writing data: the "write_data()" routine prints a whole XMLTV::Lineup document at once, but if you want to write a XMLTV::Lineup document incrementally you can manually create an "XMLTV::Lineup::Writer" object and call methods on it. Synopsis:

   use XMLTV::Lineup;
   my $w = new XMLTV::Lineup::Writer();
   $w->comment("Hello from XML::Writer's comment() method");
   $w->start({ 'generator-info-name' => 'Example code in pod' });
   my %ch = (id => 'test-channel', 'display-name' => [ [ 'Test', 'en' ] ]);
   $w->write_channel(\%ch);
   $w->end();
 
 

XMLTV::Lineup::Writer inherits from XML::Writer, and provides the following extra or overridden methods:

new(), the constructor

Creates an XMLTV::Lineup::Writer object and starts writing a XMLTV::Lineup file, printing the DOCTYPE line. Arguments are passed on to XML::Writer's constructor, except for the following:

the 'encoding' key if present gives the XML character encoding. For example:

   my $w = new XMLTV::Lineup::Writer(encoding => 'ISO-8859-1');
 
 

If encoding is not specified, XML::Writer's default is used (currently UTF-8).

start()

Write the start of the <xmltv-lineup> element. Parameter is a hashref which gives the attributes of this element.

Attributes are 'type', 'id' and 'version'

write_display_name()

Write a display name element. These are written before channel elements in the XML file.

write_lineup_icon()

Write an icon for the lineup. This is written before channel elements in the XML file.

write_channels()

Write several channels at once. Parameter is a reference to a hash mapping channel id to channel details. They will be written sorted by id, which is reasonable since the order of channels in an XMLTV file isn't significant.

write_channel()

Write a single channel. You can call this routine if you want, but most of the time "write_channels()" is a better interface.

end()

This ends the <xmltv-lineup> element and the file.

AUTHOR

Nick Morrott, knowledgejunkie@gmail.com

This file borrows _very_ heavily from XMLTV.pm.in by Ed Avis.

TODO

Write the DTD xmltv-lineup.dtd

SEE ALSO

The file format is defined by the DTD xmltv-lineup.dtd, which is included in the xmltv package along with this module. It should be installed in your system's standard place for SGML and XML DTDs.

The xmltv package has a web page at <http://membled.com/work/apps/xmltv/> which carries information about the file format and the various tools and apps which are distributed with this module.

COPYRIGHT

Copyright (C) 2009 Nick Morrott

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.