local-lib5/man/man3/XML::RSS.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "XML::RSS 3"
 127 .TH XML::RSS 3 "2009-10-08" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 XML::RSS \- creates and updates RSS files
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 10
 137 \& # create an RSS 1.0 file (http://purl.org/rss/1.0/)
 138 \& use XML::RSS;
 139 \& my $rss = XML::RSS\->new(version => \*(Aq1.0\*(Aq);
 140 \& $rss\->channel(
 141 \&   title        => "freshmeat.net",
 142 \&   link         => "http://freshmeat.net",
 143 \&   description  => "the one\-stop\-shop for all your Linux software needs",
 144 \&   dc => {
 145 \&     date       => \*(Aq2000\-08\-23T07:00+00:00\*(Aq,
 146 \&     subject    => "Linux Software",
 147 \&     creator    => \*(Aqscoop@freshmeat.net\*(Aq,
 148 \&     publisher  => \*(Aqscoop@freshmeat.net\*(Aq,
 149 \&     rights     => \*(AqCopyright 1999, Freshmeat.net\*(Aq,
 150 \&     language   => \*(Aqen\-us\*(Aq,
 151 \&   },
 152 \&   syn => {
 153 \&     updatePeriod     => "hourly",
 154 \&     updateFrequency  => "1",
 155 \&     updateBase       => "1901\-01\-01T00:00+00:00",
 156 \&   },
 157 \&   taxo => [
 158 \&     \*(Aqhttp://dmoz.org/Computers/Internet\*(Aq,
 159 \&     \*(Aqhttp://dmoz.org/Computers/PC\*(Aq
 160 \&   ]
 161 \& );
 162 \&
 163 \& $rss\->image(
 164 \&   title  => "freshmeat.net",
 165 \&   url    => "http://freshmeat.net/images/fm.mini.jpg",
 166 \&   link   => "http://freshmeat.net",
 167 \&   dc => {
 168 \&     creator  => "G. Raphics (graphics at freshmeat.net)",
 169 \&   },
 170 \& );
 171 \&
 172 \& $rss\->add_item(
 173 \&   title       => "GTKeyboard 0.85",
 174 \&   link        => "http://freshmeat.net/news/1999/06/21/930003829.html",
 175 \&   description => "GTKeyboard is a graphical keyboard that ...",
 176 \&   dc => {
 177 \&     subject  => "X11/Utilities",
 178 \&     creator  => "David Allen (s2mdalle at titan.vcu.edu)",
 179 \&   },
 180 \&   taxo => [
 181 \&     \*(Aqhttp://dmoz.org/Computers/Internet\*(Aq,
 182 \&     \*(Aqhttp://dmoz.org/Computers/PC\*(Aq
 183 \&   ]
 184 \& );
 185 \&
 186 \& $rss\->textinput(
 187 \&   title        => "quick finder",
 188 \&   description  => "Use the text input below to search freshmeat",
 189 \&   name         => "query",
 190 \&   link         => "http://core.freshmeat.net/search.php3",
 191 \& );
 192 \&
 193 \& # Optionally mixing in elements of a non\-standard module/namespace
 194 \&
 195 \& $rss\->add_module(prefix=>\*(Aqmy\*(Aq, uri=>\*(Aqhttp://purl.org/my/rss/module/\*(Aq);
 196 \&
 197 \& $rss\->add_item(
 198 \&   title       => "xIrc 2.4pre2",
 199 \&   link        => "http://freshmeat.net/projects/xirc/",
 200 \&   description => "xIrc is an X11\-based IRC client which ...",
 201 \&   my => {
 202 \&     rating    => "A+",
 203 \&     category  => "X11/IRC",
 204 \&   },
 205 \& );
 206 \&
 207 \&  $rss\->add_item (title=>$title, link=>$link, slash=>{ topic=>$topic });
 208 \&
 209 \& # create an RSS 2.0 file
 210 \& use XML::RSS;
 211 \& my $rss = XML::RSS\->new (version => \*(Aq2.0\*(Aq);
 212 \& $rss\->channel(title          => \*(Aqfreshmeat.net\*(Aq,
 213 \&               link           => \*(Aqhttp://freshmeat.net\*(Aq,
 214 \&               language       => \*(Aqen\*(Aq,
 215 \&               description    => \*(Aqthe one\-stop\-shop for all your Linux software needs\*(Aq,
 216 \&               rating         => \*(Aq(PICS\-1.1 "http://www.classify.org/safesurf/" 1 r (SS~~000 1))\*(Aq,
 217 \&               copyright      => \*(AqCopyright 1999, Freshmeat.net\*(Aq,
 218 \&               pubDate        => \*(AqThu, 23 Aug 1999 07:00:00 GMT\*(Aq,
 219 \&               lastBuildDate  => \*(AqThu, 23 Aug 1999 16:20:26 GMT\*(Aq,
 220 \&               docs           => \*(Aqhttp://www.blahblah.org/fm.cdf\*(Aq,
 221 \&               managingEditor => \*(Aqscoop@freshmeat.net\*(Aq,
 222 \&               webMaster      => \*(Aqscoop@freshmeat.net\*(Aq
 223 \&               );
 224 \&
 225 \& $rss\->image(title       => \*(Aqfreshmeat.net\*(Aq,
 226 \&             url         => \*(Aqhttp://freshmeat.net/images/fm.mini.jpg\*(Aq,
 227 \&             link        => \*(Aqhttp://freshmeat.net\*(Aq,
 228 \&             width       => 88,
 229 \&             height      => 31,
 230 \&             description => \*(AqThis is the Freshmeat image stupid\*(Aq
 231 \&             );
 232 \&
 233 \& $rss\->add_item(title => "GTKeyboard 0.85",
 234 \&        # creates a guid field with permaLink=true
 235 \&        permaLink  => "http://freshmeat.net/news/1999/06/21/930003829.html",
 236 \&        # alternately creates a guid field with permaLink=false
 237 \&        # guid     => "gtkeyboard\-0.85"
 238 \&        enclosure   => { url=>$url, type=>"application/x\-bittorrent" },
 239 \&        description => \*(Aqblah blah\*(Aq
 240 \&);
 241 \&
 242 \& $rss\->textinput(title => "quick finder",
 243 \&                 description => "Use the text input below to search freshmeat",
 244 \&                 name  => "query",
 245 \&                 link  => "http://core.freshmeat.net/search.php3"
 246 \&                 );
 247 \&
 248 \& # create an RSS 0.9 file
 249 \& use XML::RSS;
 250 \& my $rss = XML::RSS\->new( version => \*(Aq0.9\*(Aq );
 251 \& $rss\->channel(title => "freshmeat.net",
 252 \&               link  => "http://freshmeat.net",
 253 \&               description => "the one\-stop\-shop for all your Linux software needs",
 254 \&               );
 255 \&
 256 \& $rss\->image(title => "freshmeat.net",
 257 \&             url   => "http://freshmeat.net/images/fm.mini.jpg",
 258 \&             link  => "http://freshmeat.net"
 259 \&             );
 260 \&
 261 \& $rss\->add_item(title => "GTKeyboard 0.85",
 262 \&                link  => "http://freshmeat.net/news/1999/06/21/930003829.html"
 263 \&                );
 264 \&
 265 \& $rss\->textinput(title => "quick finder",
 266 \&                 description => "Use the text input below to search freshmeat",
 267 \&                 name  => "query",
 268 \&                 link  => "http://core.freshmeat.net/search.php3"
 269 \&                 );
 270 \&
 271 \& # print the RSS as a string
 272 \& print $rss\->as_string;
 273 \&
 274 \& # or save it to a file
 275 \& $rss\->save("fm.rdf");
 276 \&
 277 \& # insert an item into an RSS file and removes the oldest ones if
 278 \& # there are already 15 items or more
 279 \& my $rss = XML::RSS\->new;
 280 \& $rss\->parsefile("fm.rdf");
 281 \&
 282 \& while (@{$rss\->{\*(Aqitems\*(Aq}} >= 15)
 283 \& {
 284 \&     pop(@{$rss\->{\*(Aqitems\*(Aq});
 285 \& }
 286 \&
 287 \& $rss\->add_item(title => "MpegTV Player (mtv) 1.0.9.7",
 288 \&                link  => "http://freshmeat.net/news/1999/06/21/930003958.html",
 289 \&                mode  => \*(Aqinsert\*(Aq
 290 \&                );
 291 \&
 292 \& # parse a string instead of a file
 293 \& $rss\->parse($string);
 294 \&
 295 \& # print the title and link of each RSS item
 296 \& foreach my $item (@{$rss\->{\*(Aqitems\*(Aq}}) {
 297 \&     print "title: $item\->{\*(Aqtitle\*(Aq}\en";
 298 \&     print "link: $item\->{\*(Aqlink\*(Aq}\en\en";
 299 \& }
 300 \&
 301 \& # output the RSS 0.9 or 0.91 file as RSS 1.0
 302 \& $rss\->{output} = \*(Aq1.0\*(Aq;
 303 \& print $rss\->as_string;
 304 .Ve
 305 .SH "DESCRIPTION"
 306 .IX Header "DESCRIPTION"
 307 This module provides a basic framework for creating and maintaining
 308 \&\s-1RDF\s0 Site Summary (\s-1RSS\s0) files. This distribution also contains many
 309 examples that allow you to generate \s-1HTML\s0 from an \s-1RSS\s0, convert between
 310 0.9, 0.91, and 1.0 version, and other nifty things.
 311 This might be helpful if you want to include news feeds on your Web
 312 site from sources like Slashdot and Freshmeat or if you want to syndicate
 313 your own content.
 314 .PP
 315 \&\s-1XML::RSS\s0 currently supports 0.9, 0.91, and 1.0 versions of \s-1RSS\s0.
 316 See http://backend.userland.com/rss091 for information on \s-1RSS\s0 0.91.
 317 See http://www.purplepages.ie/RSS/netscape/rss0.90.html for \s-1RSS\s0 0.9.
 318 See http://web.resource.org/rss/1.0/ for \s-1RSS\s0 1.0.
 319 .PP
 320 \&\s-1RSS\s0 was originally developed by Netscape as the format for
 321 Netscape Netcenter channels, however, many Web sites have since
 322 adopted it as a simple syndication format. With the advent of \s-1RSS\s0 1.0,
 323 users are now able to syndication many different kinds of content
 324 including news headlines, threaded measages, products catalogs, etc.
 325 .PP
 326 \&\fBNote:\fR In order to parse and generate dates (such as \f(CW\*(C`pubDate\*(C'\fR
 327 and \f(CW\*(C`dc:date\*(C'\fR) it is recommended to use DateTime::Format::Mail and
 328 DateTime::Format::W3CDTF , which is what \s-1XML::RSS\s0 uses internally
 329 and requires.
 330 .SH "METHODS"
 331 .IX Header "METHODS"
 332 .IP "\s-1XML::RSS\-\s0>new(version=>$version, encoding=>$encoding, output=>$output, stylesheet=>$stylesheet_url, 'xml:base'=>$base)" 4
 333 .IX Item "XML::RSS->new(version=>$version, encoding=>$encoding, output=>$output, stylesheet=>$stylesheet_url, 'xml:base'=>$base)"
 334 Constructor for \s-1XML::RSS\s0. It returns a reference to an \s-1XML::RSS\s0 object.
 335 You may also pass the \s-1RSS\s0 version and the \s-1XML\s0 encoding to use. The default
 336 \&\fBversion\fR is 1.0. The default \fBencoding\fR is \s-1UTF\-8\s0. You may also specify
 337 the \fBoutput\fR format regardless of the input version. This comes in handy
 338 when you want to convert \s-1RSS\s0 between versions. The \s-1XML::RSS\s0 modules
 339 will convert between any of the formats.  If you set <encode_output> \s-1XML::RSS\s0
 340 will make sure to encode any entities in generated \s-1RSS\s0.  This is now on by
 341 default.
 342 .Sp
 343 You can also pass an optional \s-1URL\s0 to an \s-1XSL\s0 stylesheet that can be used to
 344 output an \f(CW\*(C`<?xsl\-stylesheet ... ?>\*(C'\fR meta-tag in the header that will
 345 allow some browsers to render the \s-1RSS\s0 file as \s-1HTML\s0.
 346 .Sp
 347 You can also set \f(CW\*(C`encode_cb\*(C'\fR to a reference to a subroutine that will
 348 encode the output in a custom way. This subroutine accepts two parameters:
 349 a reference to the \f(CW\*(C`XML::RSS::Private::Output::Base\*(C'\fR\-derived object (which
 350 should normally not concern you) and the text to encode. It should return
 351 the text to encode. If not set, then the module will encode using its
 352 custom encoding routine.
 353 .Sp
 354 xml:base will set an \f(CW\*(C`xml:base\*(C'\fR property as per
 355 .Sp
 356 .Vb 1
 357 \&    http://www.w3.org/TR/xmlbase/
 358 .Ve
 359 .Sp
 360 Note that in order to encode properly, you need to handle \*(L"\s-1CDATA\s0\*(R" sections
 361 properly. Look at XML::RSS::Private::Output::Base's \f(CW\*(C`_default_encode()\*(C'\fR
 362 method for how to do it properly.
 363 .IP "add_item (title=>$title, link=>$link, description=>$desc, mode=>$mode)" 4
 364 .IX Item "add_item (title=>$title, link=>$link, description=>$desc, mode=>$mode)"
 365 Adds an item to the \s-1XML::RSS\s0 object. \fBmode\fR and \fBdescription\fR are optional.
 366 The default \fBmode\fR
 367 is append, which adds the item to the end of the list. To insert an item, set the mode
 368 to \fBinsert\fR.
 369 .Sp
 370 The items are stored in the array @{$obj\->{'items'}} where
 371 \&\fB\f(CB$obj\fB\fR is a reference to an \s-1XML::RSS\s0 object.
 372 .IP "as_string;" 4
 373 .IX Item "as_string;"
 374 Returns a string containing the \s-1RSS\s0 for the \s-1XML::RSS\s0 object.  This
 375 method will also encode special characters along the way.
 376 .IP "channel (title=>$title, link=>$link, description=>$desc, language=>$language, rating=>$rating, copyright=>$copyright, pubDate=>$pubDate, lastBuildDate=>$lastBuild, docs=>$docs, managingEditor=>$editor, webMaster=>$webMaster)" 4
 377 .IX Item "channel (title=>$title, link=>$link, description=>$desc, language=>$language, rating=>$rating, copyright=>$copyright, pubDate=>$pubDate, lastBuildDate=>$lastBuild, docs=>$docs, managingEditor=>$editor, webMaster=>$webMaster)"
 378 Channel information is required in \s-1RSS\s0. The \fBtitle\fR cannot
 379 be more the 40 characters, the \fBlink\fR 500, and the \fBdescription\fR
 380 500 when outputting \s-1RSS\s0 0.9. \fBtitle\fR, \fBlink\fR, and \fBdescription\fR,
 381 are required for \s-1RSS\s0 1.0. \fBlanguage\fR is required for \s-1RSS\s0 0.91.
 382 The other parameters are optional for \s-1RSS\s0 0.91 and 1.0.
 383 .Sp
 384 To retreive the values of the channel, pass the name of the value
 385 (title, link, or description) as the first and only argument
 386 like so:
 387 .Sp
 388 \&\f(CW$title\fR = channel('title');
 389 .IP "image (title=>$title, url=>$url, link=>$link, width=>$width, height=>$height, description=>$desc)" 4
 390 .IX Item "image (title=>$title, url=>$url, link=>$link, width=>$width, height=>$height, description=>$desc)"
 391 Adding an image is not required. \fBurl\fR is the \s-1URL\s0 of the
 392 image, \fBlink\fR is the \s-1URL\s0 the image is linked to. \fBtitle\fR, \fBurl\fR,
 393 and \fBlink\fR parameters are required if you are going to
 394 use an image in your \s-1RSS\s0 file. The remaining image elements are used
 395 in \s-1RSS\s0 0.91 or optionally imported into \s-1RSS\s0 1.0 via the rss091 namespace.
 396 .Sp
 397 The method for retrieving the values for the image is the same as it
 398 is for \fB\f(BIchannel()\fB\fR.
 399 .IP "parse ($string, \e%options)" 4
 400 .IX Item "parse ($string, %options)"
 401 Parses an \s-1RDF\s0 Site Summary which is passed into \fB\f(BIparse()\fB\fR as the first
 402 parameter. Returns the instance of the object so one can say
 403 \&\f(CW\*(C`<$rss\-\*(C'\fRparse($string)\->\fIother_method()\fR>>.
 404 .Sp
 405 See the \fIadd_module()\fR method for instructions on automatically adding
 406 modules as a string is parsed.
 407 .Sp
 408 \&\f(CW%options\fR is a list of options that specify how parsing is to be done. The
 409 available options are:
 410 .RS 4
 411 .IP "\(bu" 4
 412 allow_multiple
 413 .Sp
 414 Takes an array ref of names which indicates which elements should
 415 be allowed to have multiple occurrences. So, for example, to parse
 416 feeds with multiple enclosures
 417 .Sp
 418 .Vb 1
 419 \&   $rss\->parse($xml, { allow_multiple => [\*(Aqenclosure\*(Aq] });
 420 .Ve
 421 .IP "\(bu" 4
 422 hashrefs_instead_of_strings
 423 .Sp
 424 If true, then some items (so far "\f(CW\*(C`description\*(C'\fR") will become hash-references
 425 instead of strings (with a \fBcontent\fR key containing their content , \fBif\fR
 426 they have \s-1XML\s0 attributes. Without this key, the attributes will be ignored
 427 and there will only be a string. Thus, specifying this option may break
 428 compatibility.
 429 .IP "\(bu" 4
 430 modules_as_arrays
 431 .Sp
 432 This option when true, will parse the modules key-value-pairs as an arrayref of
 433 \&\f(CW\*(C`{ el => $key_name, value => $value, }\*(C'\fR hash-refs to gracefully
 434 handle duplicate items (see below). It will not affect the known modules such
 435 as dc (\*(L"Dublin Core\*(R").
 436 .RE
 437 .RS 4
 438 .RE
 439 .IP "parsefile ($file, \e%options)" 4
 440 .IX Item "parsefile ($file, %options)"
 441 Same as \fB\f(BIparse()\fB\fR except it parses a file rather than a string.
 442 .Sp
 443 See the \fIadd_module()\fR method for instructions on automatically adding
 444 modules as a string is parsed.
 445 .IP "save ($file)" 4
 446 .IX Item "save ($file)"
 447 Saves the \s-1RSS\s0 to a specified file.
 448 .ie n .IP "skipDays (day => $day)" 4
 449 .el .IP "skipDays (day => \f(CW$day\fR)" 4
 450 .IX Item "skipDays (day => $day)"
 451 Populates the skipDays element with the day \f(CW$day\fR.
 452 .ie n .IP "skipHours (hour => $hour)" 4
 453 .el .IP "skipHours (hour => \f(CW$hour\fR)" 4
 454 .IX Item "skipHours (hour => $hour)"
 455 Populates the skipHours element, with the hour \f(CW$hour\fR.
 456 .IP "strict ($boolean)" 4
 457 .IX Item "strict ($boolean)"
 458 If it's set to 1, it will adhere to the lengths as specified
 459 by Netscape Netcenter requirements. It's set to 0 by default.
 460 Use it if the \s-1RSS\s0 file you're generating is for Netcenter.
 461 strict will only work for \s-1RSS\s0 0.9 and 0.91. Do not use it for
 462 \&\s-1RSS\s0 1.0.
 463 .IP "textinput (title=>$title, description=>$desc, name=>$name, link=>$link);" 4
 464 .IX Item "textinput (title=>$title, description=>$desc, name=>$name, link=>$link);"
 465 This \s-1RSS\s0 element is also optional. Using it allows users to submit a Query
 466 to a program on a Web server via an \s-1HTML\s0 form. \fBname\fR is the \s-1HTML\s0 form name
 467 and \fBlink\fR is the \s-1URL\s0 to the program. Content is submitted using the \s-1GET\s0
 468 method.
 469 .Sp
 470 Access to the \fBtextinput\fR values is the the same as \fB\f(BIchannel()\fB\fR and
 471 \&\fB\f(BIimage()\fB\fR.
 472 .IP "add_module(prefix=>$prefix, uri=>$uri)" 4
 473 .IX Item "add_module(prefix=>$prefix, uri=>$uri)"
 474 Adds a module namespace declaration to the \s-1XML::RSS\s0 object, allowing you
 475 to add modularity outside of the the standard \s-1RSS\s0 1.0 modules.  At present,
 476 the standard modules Dublin Core (dc) and Syndication (syn) are predefined
 477 for your convenience. The Taxonomy (taxo) module is also internally supported.
 478 .Sp
 479 The modules are stored in the hash %{$obj\->{'modules'}} where
 480 \&\fB\f(CB$obj\fB\fR is a reference to an \s-1XML::RSS\s0 object.
 481 .Sp
 482 If you want to automatically add modules that the parser finds in
 483 namespaces, set the \f(CW$XML::RSS::AUTO_ADD\fR variable to a true value.  By
 484 default the value is false. (N.B. \s-1AUTO_ADD\s0 only updates the
 485 %{$obj\->{'modules'}} hash.  It does not provide the other benefits
 486 of using add_module.)
 487 .SS "\s-1RSS\s0 1.0 \s-1MODULES\s0"
 488 .IX Subsection "RSS 1.0 MODULES"
 489 XML-Namespace-based modularization affords \s-1RSS\s0 1.0 compartmentalized
 490 extensibility.  The only modules that ship \*(L"in the box\*(R" with \s-1RSS\s0 1.0
 491 are Dublin Core (http://purl.org/rss/1.0/modules/dc/), Syndication
 492 (http://purl.org/rss/1.0/modules/syndication/), and Taxonomy
 493 (http://purl.org/rss/1.0/modules/taxonomy/).  Consult the appropriate
 494 module's documentation for further information.
 495 .PP
 496 Adding items from these modules in \s-1XML::RSS\s0 is as simple as adding other
 497 attributes such as title, link, and description.  The only difference
 498 is the compartmentalization of their key/value paris in a second-level
 499 hash.
 500 .PP
 501 .Vb 1
 502 \&  $rss\->add_item (title=>$title, link=>$link, dc=>{ subject=>$subject, creator=>$creator, date=>$date });
 503 .Ve
 504 .PP
 505 For elements of the Dublin Core module, use the key 'dc'.  For elements
 506 of the Syndication module, 'syn'.  For elements of the Taxonomy module,
 507 \&'taxo'. These are the prefixes used in the \s-1RSS\s0 \s-1XML\s0 document itself.
 508 They are associated with appropriate URI-based namespaces:
 509 .PP
 510 .Vb 3
 511 \&  syn:  http://purl.org/rss/1.0/modules/syndication/
 512 \&  dc:   http://purl.org/dc/elements/1.1/
 513 \&  taxo: http://purl.org/rss/1.0/modules/taxonomy/
 514 .Ve
 515 .PP
 516 The Dublin Core ('dc') hash keys may be point to an array
 517 reference, which in turn will specify multiple such keys, and render them
 518 one after the other. For example:
 519 .PP
 520 .Vb 9
 521 \&    $rss\->add_item (
 522 \&        title => $title,
 523 \&        link => $link,
 524 \&        dc => {
 525 \&            subject=> ["Jungle", "Desert", "Swamp"],
 526 \&            creator=>$creator,
 527 \&            date=>$date
 528 \&        },
 529 \&    );
 530 .Ve
 531 .PP
 532 Dublin Core elements may occur in channel, image, item(s), and textinput
 533 \&\*(-- albeit uncomming to find them under image and textinput.  Syndication
 534 elements are limited to the channel element. Taxonomy elements can occur
 535 in the channel or item elements.
 536 .PP
 537 Access to module elements after parsing an \s-1RSS\s0 1.0 document using
 538 \&\s-1XML::RSS\s0 is via either the prefix or namespace \s-1URI\s0 for your convenience.
 539 .PP
 540 .Vb 1
 541 \&  print $rss\->{items}\->[0]\->{dc}\->{subject};
 542 \&
 543 \&  or
 544 \&
 545 \&  print $rss\->{items}\->[0]\->{\*(Aqhttp://purl.org/dc/elements/1.1/\*(Aq}\->{subject};
 546 .Ve
 547 .PP
 548 \&\s-1XML::RSS\s0 also has support for \*(L"non-standard\*(R" \s-1RSS\s0 1.0 modularization at
 549 the channel, image, item, and textinput levels.  Parsing an \s-1RSS\s0 document
 550 grabs any elements of other namespaces which might appear.  \s-1XML::RSS\s0
 551 also allows the inclusion of arbitrary namespaces and associated elements
 552 when building  \s-1RSS\s0 documents.
 553 .PP
 554 For example, to add elements of a made-up \*(L"My\*(R" module, first declare the
 555 namespace by associating a prefix with a \s-1URI:\s0
 556 .PP
 557 .Vb 1
 558 \&  $rss\->add_module(prefix=>\*(Aqmy\*(Aq, uri=>\*(Aqhttp://purl.org/my/rss/module/\*(Aq);
 559 .Ve
 560 .PP
 561 Then proceed as usual:
 562 .PP
 563 .Vb 1
 564 \&  $rss\->add_item (title=>$title, link=>$link, my=>{ rating=>$rating });
 565 .Ve
 566 .PP
 567 You can also set the value of the module's prefix to an array reference
 568 of \f(CW\*(C`{ el => , val => }\*(C'\fR hash-references, in which case duplicate
 569 elements are possible:
 570 .PP
 571 .Vb 4
 572 \&  $rss\->add_item(title=>$title, link=>$link, my=> [
 573 \&    {el => "rating", value => $rating1, }
 574 \&    {el => "rating", value => $rating2, },
 575 \&  ]
 576 .Ve
 577 .PP
 578 Non-standard namespaces are not, however, currently accessible via a simple
 579 prefix; access them via their namespace \s-1URL\s0 like so:
 580 .PP
 581 .Vb 1
 582 \&  print $rss\->{items}\->[0]\->{\*(Aqhttp://purl.org/my/rss/module/\*(Aq}\->{rating};
 583 .Ve
 584 .PP
 585 \&\s-1XML::RSS\s0 will continue to provide built-in support for standard \s-1RSS\s0 1.0
 586 modules as they appear.
 587 .SH "Non-API Methods"
 588 .IX Header "Non-API Methods"
 589 .ie n .SS "$rss\->\fIas_rss_0_9()\fP"
 590 .el .SS "\f(CW$rss\fP\->\fIas_rss_0_9()\fP"
 591 .IX Subsection "$rss->as_rss_0_9()"
 592 \&\fB\s-1WARNING\s0\fR: this function is not an \s-1API\s0 function and should not be called
 593 directly. It is kept as is for backwards compatibility with legacy code. Use
 594 the following code instead:
 595 .PP
 596 .Vb 2
 597 \&    $rss\->{output} = "0.9";
 598 \&    my $text = $rss\->as_string();
 599 .Ve
 600 .PP
 601 This function renders the data in the object as an \s-1RSS\s0 version 0.9 feed,
 602 and returns the resultant \s-1XML\s0 as text.
 603 .ie n .SS "$rss\->\fIas_rss_0_9_1()\fP"
 604 .el .SS "\f(CW$rss\fP\->\fIas_rss_0_9_1()\fP"
 605 .IX Subsection "$rss->as_rss_0_9_1()"
 606 \&\fB\s-1WARNING\s0\fR: this function is not an \s-1API\s0 function and should not be called
 607 directly. It is kept as is for backwards compatibility with legacy code. Use
 608 the following code instead:
 609 .PP
 610 .Vb 2
 611 \&    $rss\->{output} = "0.91";
 612 \&    my $text = $rss\->as_string();
 613 .Ve
 614 .PP
 615 This function renders the data in the object as an \s-1RSS\s0 version 0.91 feed,
 616 and returns the resultant \s-1XML\s0 as text.
 617 .ie n .SS "$rss\->\fIas_rss_1_0()\fP"
 618 .el .SS "\f(CW$rss\fP\->\fIas_rss_1_0()\fP"
 619 .IX Subsection "$rss->as_rss_1_0()"
 620 \&\fB\s-1WARNING\s0\fR: this function is not an \s-1API\s0 function and should not be called
 621 directly. It is kept as is for backwards compatibility with legacy code. Use
 622 the following code instead:
 623 .PP
 624 .Vb 2
 625 \&    $rss\->{output} = "1.0";
 626 \&    my $text = $rss\->as_string();
 627 .Ve
 628 .PP
 629 This function renders the data in the object as an \s-1RSS\s0 version 1.0 feed,
 630 and returns the resultant \s-1XML\s0 as text.
 631 .ie n .SS "$rss\->\fIas_rss_2_0()\fP"
 632 .el .SS "\f(CW$rss\fP\->\fIas_rss_2_0()\fP"
 633 .IX Subsection "$rss->as_rss_2_0()"
 634 \&\fB\s-1WARNING\s0\fR: this function is not an \s-1API\s0 function and should not be called
 635 directly. It is kept as is for backwards compatibility with legacy code. Use
 636 the following code instead:
 637 .PP
 638 .Vb 2
 639 \&    $rss\->{output} = "2.0";
 640 \&    my $text = $rss\->as_string();
 641 .Ve
 642 .PP
 643 This function renders the data in the object as an \s-1RSS\s0 version 2.0 feed,
 644 and returns the resultant \s-1XML\s0 as text.
 645 .ie n .SS "$rss\->\fIhandle_char()\fP"
 646 .el .SS "\f(CW$rss\fP\->\fIhandle_char()\fP"
 647 .IX Subsection "$rss->handle_char()"
 648 Needed for XML::Parser. Don't use this directly.
 649 .ie n .SS "$rss\->\fIhandle_dec()\fP"
 650 .el .SS "\f(CW$rss\fP\->\fIhandle_dec()\fP"
 651 .IX Subsection "$rss->handle_dec()"
 652 Needed for XML::Parser. Don't use this directly.
 653 .ie n .SS "$rss\->\fIhandle_start()\fP"
 654 .el .SS "\f(CW$rss\fP\->\fIhandle_start()\fP"
 655 .IX Subsection "$rss->handle_start()"
 656 Needed for XML::Parser. Don't use this directly.
 657 .SH "BUGS"
 658 .IX Header "BUGS"
 659 Please use rt.cpan.org for tracking bugs.  The list of current open
 660 bugs is at
 661     <http://rt.cpan.org/Dist/Display.html?Queue=XML\-RSS>.
 662 .PP
 663 To report a new bug, go to
 664     <http://rt.cpan.org/Ticket/Create.html?Queue=XML\-RSS>
 665 .PP
 666 Please include a failing test in your bug report.  I'd much rather
 667 have a well written test with the bug report than a patch.
 668 .PP
 669 When you create diffs (for tests or patches), please use the \f(CW\*(C`\-u\*(C'\fR
 670 parameter to diff.
 671 .SH "SOURCE AVAILABILITY"
 672 .IX Header "SOURCE AVAILABILITY"
 673 The source is available from the perl.org Subversion server:
 674 .PP
 675 <http://svn.perl.org/modules/XML\-RSS/>
 676 .SH "AUTHOR"
 677 .IX Header "AUTHOR"
 678 Original code: Jonathan Eisenzopf <eisen@pobox.com>
 679 .PP
 680 Further changes: Rael Dornfest <rael@oreilly.com>, Ask Bjoern Hansen
 681 <ask@develooper.com>
 682 .PP
 683 Currently: Shlomi Fish <shlomif@cpan.org>
 684 .SH "COPYRIGHT"
 685 .IX Header "COPYRIGHT"
 686 Copyright (c) 2001 Jonathan Eisenzopf <eisen@pobox.com> and Rael
 687 Dornfest <rael@oreilly.com>, Copyright (C) 2006\-2007 Ask Bjoern Hansen
 688 <ask@develooper.com>.
 689 .SH "LICENSE"
 690 .IX Header "LICENSE"
 691 \&\s-1XML::RSS\s0 is free software. You can redistribute it and/or
 692 modify it under the same terms as Perl itself.
 693 .SH "CREDITS"
 694 .IX Header "CREDITS"
 695 .Vb 12
 696 \& Wojciech Zwiefka <wojtekz@cnt.pl>
 697 \& Chris Nandor <pudge@pobox.com>
 698 \& Jim Hebert <jim@cosource.com>
 699 \& Randal Schwartz <merlyn@stonehenge.com>
 700 \& rjp@browser.org
 701 \& Kellan Elliott\-McCrea <kellan@protest.net>
 702 \& Rafe Colburn <rafe@rafe.us>
 703 \& Adam Trickett <atrickett@cpan.org>
 704 \& Aaron Straup Cope <asc@vineyard.net>
 705 \& Ian Davis <iand@internetalchemy.org>
 706 \& rayg@varchars.com
 707 \& Shlomi Fish <shlomif@iglu.org.il>
 708 .Ve
 709 .SH "SEE ALSO"
 710 .IX Header "SEE ALSO"
 711 \&\fIperl\fR\|(1), \fIXML::Parser\fR\|(3).