Man Xmltv Howto - RPM Search

Takes a data structure and writes it as XML to standard output. Anyextra 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 thedata.

Normally, there will be a warning for any Perl data which is notunderstood and cannot be written as XMLTV, such as strange keys inhashes. But as an exception, any hash key beginning with anunderscore will be skipped over silently. You can store 'internal useonly' data this way.

If a programme hash contains a key beginning with 'debug', this keyand its value will be written out as a comment inside the <programme>element. This lets you include small debugging messages in the XMLoutput.best_name(languages, pairs [, comparator])The XMLTV format contains many places where human-readable text isgiven an optional 'lang' attribute, to allow mixed languages. This isrepresented in Perl as a pair [ text, lang ], although the secondelement may be missing or undef if the language is unknown. Whenseveral alernatives for an element (such as <title>) can be given, therepresentation is a list of [ text, lang ] pairs. Given such a list,what is the best text to use? It depends on the user's preferredlanguage.

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 findingthe appropriate language and then picking the 'best' string in thatlanguage.

The best is normally defined as the first one found in a usablelanguage, since the XMLTV format puts the most canonical versionsfirst. But you can pass in your own comparison function, for exampleif you want to choose the shortest piece of text that is in anacceptable language.

The acceptable languages should be a reference to a list of languagecodes looking like 'ru', or like 'de_DE'. The text pairs should be areference to a list of pairs [ string, language ]. (As a special caseif this list is empty or undef, that means no text is present, and theresult is undef.) The third argument if present should be a cmp-stylefunction that compares two strings of text and returns 1 if the firstargument is better, -1 if the second better, 0 if they're equallygood.

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

Example:

my $langs = [ 'de', 'fr' ]; # German or French, please # Say we found the following under $p->{title} for a programme $p. my $pairs = [ [ 'La Cité des enfants perdus', 'fr' ], [ 'The City of Lost Children', 'en_US' ] ]; my $best = best_name($langs, $pairs); print "chose title $best->[0]\n";list_channel_keys(), list_programme_keys()Some users of this module may wish to enquire at runtime about whichkeys a programme or channel can contain. This subroutine returns ahash mapping key to handler name and multiplicity. This lets you knowwhat data types can be expected under each key. See the section on "DATA STRUCTURE" for details on what a handler is.

It is not possible to find out which keys are mandatory and whichoptional, only a list of all those which might possibly be present.An example use of these routines is the tv_grep(1) program, whichcreates its allowed command line arguments from the names of programmesubelements.cat(data, ...)Concatenate (and merge) listings data. Programmes are catenatedtogether, channels are merged, for credits we just take the firstand warn if the others differ.

See tv_cat(1) which is just a wrapper around this routine.

DATA STRUCTURE

For completeness, we describe more precisely how channels andprogrammes are represented in Perl. Each element of the channels listis a hashref corresponding to one <channel> element, and likewise forprogrammes. The possible keys of a channel (programme) hash are thenames of attributes or subelements of <channel> (<programme>). Thevalues for attributes are not processed in any way. But forsubelements, there is further processing needed to turn the XMLcontent of a subelement into Perl data. What is done depends on whattype of data is stored under that subelement. Also, if a certainelement can appear several times then the hash key for that elementpoints to a list of values rather than just one.

The conversion of a subelement's content to and from Perl data isdone by a handler. The most common handler is with-lang, used forhuman-readable text content plus an optional 'lang' attribute. Thereare other handlers for other data structures in the file format.Often two subelements will share the same handler, since they hold thesame type of data. The handlers defined are as follows; note thatmost of them will silently strip leading and trailing whitespace inelement content. Look at the DTD itself for an explanation of thewhole file format.creditsTurns a list of credits (for director, actor, writer, etc.) into ahash mapping 'role' to a list of names. The names in each role arekept in the same order.scalarReads and writes a simple string as the content of the XML element.lengthConverts the content of a <length> element into a number of seconds(so <length units=``minutes''>5</minutes> would be returned as 300). Onwriting out again tries to convert a number of seconds to a time inminutes or hours if that would look better.episode-numThe representation in Perl of XMLTV's odd episode numbers is as apair of [ content, system ]. As specified by the DTD, if the system isnot given in the file then 'onscreen' is assumed. Whitespace in the'xmltv_ns' system is unimportant, so on reading it is normalized toa single space on either side of each dot.videoThe <video> section is converted to a hash. The <present> subelementcorresponds to the key 'present' of this hash, 'yes' and 'no' areconverted to Booleans. The same applies to <colour>. The content ofthe <aspect> subelement is stored under the key 'aspect'. These keyscan be missing in the hash just as the subelements can be missing inthe XML.audioThis is similar to video. <present> is a Boolean value, whilethe content of <stereo> is stored unchanged.previously-shownThe 'start' and 'channel' attributes are converted to keys in a hash.presenceThe content of the element is ignored: it signfies something by itsvery presence. So the conversion from XML to Perl is a constant truevalue whenever the element is found; the conversion from Perl to XMLis to write out the element if true, don't write anything if false.subtitlesThe 'type' attribute and the 'language' subelement both become keys ina hash.ratingThe rating is represented as a tuple of [ rating, system, icons ].The last element is itself a listref of structures returned by theicon handler.star-ratingIn XML this is a string 'X/Y' plus a list of icons. In Perl representedas a pair [ rating, icons ] similar to rating.iconAn icon in XMLTV files is like the <img> element in HTML. It isrepresented in Perl as a hashref with 'src' and optionally 'width'and 'height' keys.with-langIn 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.with-lang-or-emptyEither text with language, or the empty string. This is used forthings which can have an optional human-readable 'explanation'. ThePerl representation is [ 'Foo', language ] for text with knownlanguage, [ 'Foo' ] or [ 'Foo', undef if the language is unknown,and just [] for 'present but no text'.

Now, which handlers are used for which subelements (keys) of channelsand programmes? And what is the multiplicity (should you expect asingle value or a list of values)?

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

Handlers for <channel>

display-name, with-lang, +icon, icon, *url, scalar, *

Handlers for <programme>

title, with-lang, +sub-title, with-lang, *desc, with-lang, *credits, credits, ?date, scalar, ?category, with-lang, *language, with-lang, ?orig-language, with-lang, ?length, length, ?icon, icon, *url, scalar, *country, with-lang, *episode-num, episode-num, ?video, video, ?audio, audio, ?previously-shown, previously-shown, ?premiere, with-lang-or-empty, ?last-chance, with-lang-or-empty, ?new, presence, ?subtitles, subtitles, *rating, rating, *star-rating, star-rating, ?

At present, no parsing or validation on dates is done because datesmay be partially specified in XMLTV. For example '2001' means thatthe year is known but not the month, day or time of day. Maybe in thefuture dates will be automatically converted to and fromDate::Manip objects. For now they just use the scalar handler.Similar remarks apply to URLs.

INCREMENTAL READING AND WRITING

Because of the way parsing is currently implemented, it is not possibleto read a file lazily. You have to wait for the whole XML document tobe loaded in and parsed, and then you are given all the programmes andchannels at once.

The "write_data()" function provides the equivalent approach to writing:it prints a whole XMLTV document at once. This is often sufficient, butsometimes you want to write out programmes gradually, as they are produced.For this you can manually create an "XMLTV::Writer" object and callmethods on it. Synopsis:

use XMLTV; my $w = new XMLTV::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); my %prog = (channel => 'test-channel', start => '200203161500', title => [ [ 'News', 'en' ] ]); $w->write_programme(\%prog); $w->end();XMLTV::Writer inherits from XML::Writer, and provides the following extraor overridden methods:new(), the constructorCreates an XMLTV::Writer object and starts writing an XMLTV file, printingthe DOCTYPE line. Arguments are passed on to XML::Writer's constructor,except that the 'encoding' key if present gives the XML character encoding.For example:

my $w = new XMLTV::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 <tv> element. Parameter is a hashref which givesthe attributes of this element.write_channels()Write several channels at once. Parameter is a reference to a hashmapping channel id to channel details. They will be written sortedby id, which is reasonable since the order of channels in an XMLTVfile isn't significant.write_channel()Write a single channel. You can call this routine if you want, butmost of the time "write_channels()" is a better interface.write_programme()Write details for a single programme as XML.end()Say you've finished writing programmes. This ends the <tv> elementand the file.

AUTHOR

Ed Avis, epa98AATTdoc.ic.ac.uk

SEE ALSO

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

The xmltv package has a web page at<http://www.doc.ic.ac.uk/~epa98/work/apps/xmltv/> which carriesinformation about the file format and the various tools and apps whichuse this module.

Index

NAMESYNOPSISDESCRIPTIONUSAGEDATA STRUCTUREHandlers for <channel>Handlers for <programme>INCREMENTAL READING AND WRITINGAUTHORSEE ALSOThis document was created byman2html,using the manual pages.