.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\" ========================================================================
.\"
.IX Title "XML::RSS::SimpleGen 3pm"
.TH XML::RSS::SimpleGen 3pm "2018-05-06" "perl v5.26.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::RSS::SimpleGen \- for writing RSS files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& # A complete screen\-scraper and RSS generator here:
\&
\& use strict;
\& use XML::RSS::SimpleGen;
\& my $url = q;
\&
\& rss_new( $url, "eXile", "Moscow\-based Alternative Newspaper" );
\& rss_language( \*(Aqen\*(Aq );
\& rss_webmaster( \*(Aqxxxxx@yourdomain.com\*(Aq );
\& rss_twice_daily();
\&
\& get_url( $url );
\&
\& while(
\& m{
\es*(.*?);
\&
\& rss_new( $url, "eXile" );
\& rss_language( \*(Aqen\*(Aq );
\& get_url( $url );
\& ...
.Ve
.PP
does the same work as this \s-1OO\s0 code:
.PP
.Vb 6
\& use XML::RSS::SimpleGen ();
\& my $url = q;
\& my $rss = XML::RSS::SimpleGen\->new( $url, "eXile");
\& $rss\->language( \*(Aqen\*(Aq );
\& $rss\->get_url( $url );
\& ...
.Ve
.PP
(Note that the function \f(CW\*(C`get_url\*(C'\fR doesn't have a leading \*(L"rss_\*(R",
so its method name is the same as its function name. It's the
one exception.)
.PP
If this talk of objects puzzles you, see
HTML::Tree::AboutObjects in the \f(CW\*(C`HTML\-Tree\*(C'\fR dist, and/or see
the chapter \*(L"User's View of Object-Oriented Modules\*(R"
in my book \fIPerl & \s-1LWP\s0\fR ().
(The book is also useful as an extended discussion of screen-scraping.)
.PP
Note: in the code below, I use the word \*(L"accessor\*(R" a lot, to refer
to a function or method that you can call two possible ways:
1) like \f(CW\*(C`foo(\f(CIval\f(CW)\*(C'\fR to set the \*(L"foo\*(R" attribute to the value \fIval\fR,
or 2) like \f(CW\*(C`foo()\*(C'\fR to return the value of the \*(L"foo\*(R" attribute.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .IP """rss_new( \fIurl\fP );""" 4
.el .IP "\f(CWrss_new( \f(CIurl\f(CW );\fR" 4
.IX Item "rss_new( url );"
.PD 0
.ie n .IP """rss_new( \fIurl, title\fP );""" 4
.el .IP "\f(CWrss_new( \f(CIurl, title\f(CW );\fR" 4
.IX Item "rss_new( url, title );"
.ie n .IP """rss_new( \fIurl, title, description\fP );""" 4
.el .IP "\f(CWrss_new( \f(CIurl, title, description\f(CW );\fR" 4
.IX Item "rss_new( url, title, description );"
.ie n .IP "\fIor:\fR ""$rss = XML::RSS::SimpleGen\->new(...);""" 4
.el .IP "\fIor:\fR \f(CW$rss = XML::RSS::SimpleGen\->new(...);\fR" 4
.IX Item "or: $rss = XML::RSS::SimpleGen->new(...);"
.PD
This function creates a new \s-1RSS\s0 feed in memory. This should be the first
\&\f(CW\*(C`rss_\f(CIwhatever\f(CW\*(C'\fR function you call in your program. If you call it
again, it erases the current object (if any) and sets up a new one according
to whatever parameters you pass.
.Sp
The parameters are the full \s-1URL,\s0 the title, and the description of the
site (or page) that you're providing an \s-1RSS\s0 feed of. The description is
optional, but you should provide at least a \s-1URL\s0 and title.
.Sp
Examples:
.Sp
.Vb 1
\& rss_new( $url, "eXile", "Moscow\-based Alternative Newspaper" );
\&
\& rss_new( \*(Aqhttp://www.mybazouki.com/news/\*(Aq, "Bazouki News!" );
.Ve
.Sp
(As a method, XML::RSS::SimpleGen\->new simply returns a new
\&\s-1RSS\s0 object.)
.ie n .IP "the accessor ""rss_language(\fIlanguage_tag\fP)""" 4
.el .IP "the accessor \f(CWrss_language(\f(CIlanguage_tag\f(CW)\fR" 4
.IX Item "the accessor rss_language(language_tag)"
This declares what language this \s-1RSS\s0 feed is in. It must be
an RFC3066\-style language tags like \*(L"en\*(R", or \*(L"en-US\*(R", or \*(L"zh-TW\*(R".
(See \fII18N::LangTags::List\fR for a list.)
If you don't set the feed's language, it defaults to \*(L"en\*(R", for generic English.
.Sp
If you call this function without a parameter, it returns
the current value of the \s-1RSS\s0 feed's language. For example:
.Sp
.Vb 1
\& print "I\*(Aqm making an RSS feed for ", rss_language(), "!\en";
.Ve
.Sp
The same is true for all the functions that I label as \*(L"accessors\*(R".
.ie n .IP "the accessor ""rss_item_limit(\fInumber\fP)""" 4
.el .IP "the accessor \f(CWrss_item_limit(\f(CInumber\f(CW)\fR" 4
.IX Item "the accessor rss_item_limit(number)"
This sets the maximum number of items that this feed will show.
.Sp
The default value is 0, meaning that there is no maximum.
.Sp
If you set it to a positive number \fIN\fR, then the feed will show only
the first \fIN\fR items that you declare with \f(CW\*(C`rss_item\*(C'\fR. (Or, if you set
\&\f(CW\*(C`rss_history_file\*(C'\fR, then the newest \fIN\fR items that you declare
with \f(CW\*(C`rss_item\*(C'\fR.)
.Sp
If you set it to a negative number \fI\-N\fR, then the feed will show only
the last \fIN\fR items that you declare with \f(CW\*(C`rss_item\*(C'\fR. (Or, if you set
\&\f(CW\*(C`rss_history_file\*(C'\fR, then the oldest \fIN\fR items you declare with \f(CW\*(C`rss_item\*(C'\fR,
which is unlikely to be useful!)
.ie n .IP "the accessor ""rss_webMaster(\fIemail\-address\fP)""" 4
.el .IP "the accessor \f(CWrss_webMaster(\f(CIemail\-address\f(CW)\fR" 4
.IX Item "the accessor rss_webMaster(email-address)"
This declares what email address you, the \s-1RSS\s0 generator manager, can be
reached at. Example:
.Sp
.Vb 1
\& rss_webMaster( \*(Aqsburke@bazouki\-news.int\*(Aq );
.Ve
.ie n .IP """rss_history_file( \fIfilename\fP )""" 4
.el .IP "\f(CWrss_history_file( \f(CIfilename\f(CW )\fR" 4
.IX Item "rss_history_file( filename )"
This declares that you want this \s-1RSS\s0 feed to keep track of what items are
new, and to list them first when the \s-1RSS\s0 is emitted. To do this, the \s-1RSS\s0
generator has to store information in a file, where it tracks its \*(L"history\*(R",
i.e., when was the first time it saw given URLs, and the most recent time
it saw given URLs.
.Sp
Typical usage is:
.Sp
.Vb 1
\& rss_history_file( \*(Aqthisrssfeed.dat\*(Aq );
.Ve
.Sp
You should call \f(CW\*(C`rss_history_file\*(C'\fR \fIbefore\fR you make any calls to
\&\f(CW\*(C`rss_item\*(C'\fR.
.Sp
The history-file feature is meant for cases where your RSS-generator
program calls \f(CW\*(C`rss_item\*(C'\fR on \fIevery\fR link it sees, but only wants the
\&\fInew\fR links to appear in the \s-1RSS\s0 output. (This can be a good approach
if you're making an \s-1RSS\s0 feed of a page like
\&\f(CW\*(C`http://www.guardian.co.uk/\*(C'\fR where there's some new links (to the
recently added stories), but also links to some days-old stories, and
\&\fIalso\fR links to some always-there things like \*(L"Archive Search\*(R" and
\&\*(L"Contact Us\*(R" pages.
.Sp
Once you call rss_history_file, the specified file is read in. The
in-memory history (stored in the \s-1RSS\s0 object) is updated as you
call \f(CW\*(C`rss_item\*(C'\fR. But the file isn't updated until you call rss_save.
.Sp
(A do-what-I-mean side effect of calling \f(CW\*(C`rss_history_file\*(C'\fR is that it
sets rss_item_limit to 25 if it is currently 0.)
.Sp
(Incidentally, if you're using rss_history_file as part of a \s-1CGI\s0 that
emits \s-1RSS\s0 data, instead of a program that just saves to an \s-1RSS\s0 file,
then things will get complicated. You'll need to call an internal method
to explicitly commit the history file to disk, and you'll need a
semaphore file to avoid race conditions. Email me for full info.)
.ie n .IP """rss_item( \fIurl\fP );""" 4
.el .IP "\f(CWrss_item( \f(CIurl\f(CW );\fR" 4
.IX Item "rss_item( url );"
.PD 0
.ie n .IP """rss_item( \fIurl, title\fP );""" 4
.el .IP "\f(CWrss_item( \f(CIurl, title\f(CW );\fR" 4
.IX Item "rss_item( url, title );"
.ie n .IP """rss_item( \fIurl, title, description\fP );""" 4
.el .IP "\f(CWrss_item( \f(CIurl, title, description\f(CW );\fR" 4
.IX Item "rss_item( url, title, description );"
.PD
This adds a new item to the current feed. You will need to specify the
\&\s-1URL\s0 to add (and it should be a valid-looking \s-1URL,\s0 starting with
"\fIsomething:\fR", and not containing any spaces). You may also specify
the title, but it's optional. And finally, you can optionally specify a
description. (You can remember this because it starts with the essential
item first, and progresses toward the most optional.)
.Sp
Leading and tailing whitespace is removed from whichever of \fIurl,
title,\fR and \fIdescription\fR are defined values, and \s-1HTML\s0 is parsed out.
.Sp
A simple usage:
.Sp
.Vb 4
\& rss_item(
\& "http://www.harpers.org/MostRecentWR.html",
\& "Harper\*(Aqs Magazine\*(Aqs Weekly Review"
\& );
.Ve
.Sp
Although in practice, a typical call won't have string constants, but
will instead be like the example in the Synopsis sectios,
namely:
.Sp
.Vb 1
\& rss_item("$url$1", $2, $3);
.Ve
.Sp
Incidentally, as a do-what-I-mean feature, if the first parameter
doesn't look like a \s-1URL\s0 but one of the others does, then this error is
silently forgiven. This is so you can occasionally slip up and forget
the order of the parameters.
.Sp
(In the unlikely event where you \fIneed\fR to avoid the HTML-removal
features, you can do this by passing scalar-references instead of
normal strings, like so: \f(CW\*(C`rss_item($url, $title, \e$not_to_be_escaped)\*(C'\fR.)
.ie n .IP """rss_item_count()""" 4
.el .IP "\f(CWrss_item_count()\fR" 4
.IX Item "rss_item_count()"
This returns the number of items you've declared. I anticipate that its
main usage will be something like:
.Sp
.Vb 2
\& die "What, no objects found at $url ?!"
\& unless rss_item_count();
.Ve
.Sp
or, maybe...
.Sp
.Vb 1
\& exit unless rss_item_count();
.Ve
.Sp
\&...depending on how/whether you'd want to react to cases where you don't
see anything to put into an \s-1RSS\s0 feed.
.Sp
Note that the parens are optional, since this command takes no options
(just like Perl's \f(CW\*(C`time()\*(C'\fR function).
.ie n .IP """rss_image( \fIurl, h, w\fP );""" 4
.el .IP "\f(CWrss_image( \f(CIurl, h, w\f(CW );\fR" 4
.IX Item "rss_image( url, h, w );"
This declares that you want to declare a particular image as the logo for
this feed. Most feeds don't have such a thing, and most readers just ignore
it anyway, but if you want to declare it, this function is how. The
three parameters, which are all required, are: the image's \s-1URL,\s0 its
height in pixels, and its width in pixels.
According to various specs, the width should/must be between 1 and 144,
an the height should/must be between 1 and 400.
.Sp
A typical usage:
.Sp
.Vb 1
\& rss_image("http://interglacial.com/rss/weebl.gif", 106, 140);
.Ve
.Sp
Be careful not to mix up the height and width.
.ie n .IP """rss_save( \fIfilename\fP );""" 4
.el .IP "\f(CWrss_save( \f(CIfilename\f(CW );\fR" 4
.IX Item "rss_save( filename );"
.PD 0
.ie n .IP """rss_save( \fIfilename, max_age_days\fP );""" 4
.el .IP "\f(CWrss_save( \f(CIfilename, max_age_days\f(CW );\fR" 4
.IX Item "rss_save( filename, max_age_days );"
.PD
This saves the \s-1RSS\s0 date to the file you specify. If the \s-1RSS\s0 data hasn't
changed, the file (and its modtime) aren't altered. The optional \fImax_age_days\fR
parameter means that if ever the file exists, and its content hasn't changed
for that many days or longer, then the program should die with a warning
message. For example, in the case of a screen-scraper for a site that we
know should (in theory) change its content at least weekly, we might save
the \s-1RSS\s0 file with:
.Sp
.Vb 2
\& rss_save("whatever.rss", 17);
\& # Scream if the feed is unchanged for 17 days.
.Ve
.Sp
The seventeen there is gotten by assuming that just maybe the site
might skip two weeks for a vacation now and then, and might even put
out the pre-vacation issue a few days early \*(-- but that if ever the program
notices that the data hasn't changed for 17 days, then it should emit
error messages. If you want to disable this feature on a one-time basis,
just change the modtime (like via \f(CW\*(C`touch\*(C'\fR) on the \fIwhatever.rss\fR file.
.Sp
If you don't specify a \f(CW\*(C`max_age_days\*(C'\fR value, then this whole
complain-if-it's-old feature is disabled.
.ie n .IP """rss_as_string();""" 4
.el .IP "\f(CWrss_as_string();\fR" 4
.IX Item "rss_as_string();"
This returns the RSS-XML data as a string. This function is called
internally by the rss_save function; but you might want to call it
explicitly, as in a \s-1CGI,\s0 where your \s-1CGI\s0 would probably end like this:
.Sp
.Vb 2
\& print "Content\-type: application/xml\en\en", rss_as_string();
\& exit;
.Ve
.ie n .IP """get_url( \fIurl\fP );""" 4
.el .IP "\f(CWget_url( \f(CIurl\f(CW );\fR" 4
.IX Item "get_url( url );"
.PD 0
.ie n .IP """$content = get_url( \fIurl\fP );""" 4
.el .IP "\f(CW$content = get_url( \f(CIurl\f(CW );\fR" 4
.IX Item "$content = get_url( url );"
.ie n .IP "\fIor:\fR ""$content = $rss\->get_url(...);""" 4
.el .IP "\fIor:\fR \f(CW$content = $rss\->get_url(...);\fR" 4
.IX Item "or: $content = $rss->get_url(...);"
.ie n .IP "\fIor:\fR ""$content\->get_url(...);""" 4
.el .IP "\fIor:\fR \f(CW$content\->get_url(...);\fR" 4
.IX Item "or: $content->get_url(...);"
.PD
This tries to get the content of the given url, and returns it.
.Sp
This is quite like LWP::Simple's \f(CW\*(C`get\*(C'\fR function, but with some
additional features:
.RS 4
.IP "\(bu" 4
If it can't
get the \s-1URL\s0's content at first, it will sleep for a few seconds and try
again, up to about five times. (This is to avoid the case of the \s-1URL\s0
being temporarily inaccessible simply because the \s-1DNS\s0 is a bit slow,
or because the server is too busy.)
.IP "\(bu" 4
If it can't get the content, even after several retries,
it will abort the program (like a \f(CW\*(C`die\*(C'\fR). If you want to override this
behavior, then call it as \f(CW\*(C`eval { get_url($url) };\*(C'\fR
.IP "\(bu" 4
If you call the function in void context (i.e., not using its
return value), then the function assigns the \s-1URL\s0's content to \f(CW$_\fR.
That's so you can write nice concise code like this:
.Sp
.Vb 5
\& get_url $thatsite;
\& m/Top Stories Tonight/ or die "What, no top stories?";
\& while( m{(.*?)}g ) {
\& rss_item("$thatsite/$1", $2);
\& }
.Ve
.IP "\(bu" 4
This returns the content of the \s-1URL\s0 not exactly as-is, but after
changing its newlines to native format. That is, if the contents of the
\&\s-1URL\s0 use CR-LF pairs to express newlines, then \f(CW\*(C`get_url\*(C'\fR changes these
to \f(CW\*(C`\en\*(C'\fR's before returning the content. (Similarly for old MacOS
newline format.) Clearly this is wrong in you're dealing with binary
data; in that case, use LWP::Simple's \f(CW\*(C`get\*(C'\fR directly.
.IP "\(bu" 4
Finally, as a resource-conversation measure, this function
will also try to call \f(CW\*(C`sleep\*(C'\fR a few times if it sees several quick
calls to itself coming from a program that seems to be running
under crontab. As most of my RSS-generators are crontabbed, I
find it very useful that I can have however many \f(CW\*(C`get_url\*(C'\fR's in
my crontabbed programs without worrying that they'll take even a
noticeable part of the server's bandwidth.
.RE
.RS 4
.RE
.ie n .IP """rss_hourly"" \fIor\fR ""rss_daily"" \fIor\fR ""rss_twice_daily"" \fIor\fR ""rss_thrice_daily"" \fIor\fR ""rss_weekly"" \fIor\fR ""rss_every_other_hour""" 4
.el .IP "\f(CWrss_hourly\fR \fIor\fR \f(CWrss_daily\fR \fIor\fR \f(CWrss_twice_daily\fR \fIor\fR \f(CWrss_thrice_daily\fR \fIor\fR \f(CWrss_weekly\fR \fIor\fR \f(CWrss_every_other_hour\fR" 4
.IX Item "rss_hourly or rss_daily or rss_twice_daily or rss_thrice_daily or rss_weekly or rss_every_other_hour"
Calling one of these functions declares that this feed is usually
generated at the same time(s) every day (or every week, in the case of
\&\f(CW\*(C`rss_weekly\*(C'\fR). And, where it's not just once a day/week, these multiple
times a day are evenly spaced. These functions then set the feed's
\&\f(CW\*(C`updatePeriod\*(C'\fR, \f(CW\*(C`updateBase\*(C'\fR, \f(CW\*(C`updateFrequency\*(C'\fR, \f(CW\*(C`skipHours\*(C'\fR,
\&\f(CW\*(C`skipDays\*(C'\fR, and \f(CW\*(C`ttl\*(C'\fR elements appropriately, so that \s-1RSS\s0 readers can know at
at what times there could (or couldn't) be new content in this feed.
.Sp
In other words: use \f(CW\*(C`rss_twice_daily\*(C'\fR if this feed is updated at about the
same time every day and then again 12 hours later. Use \f(CW\*(C`rss_thrice_daily\*(C'\fR
if this feed is updated at the same time daily, and then 8 hours later, and
then 8 hours later. And use \f(CW\*(C`rss_every_other_hour\*(C'\fR if the feed updates
at about \fIn\fR minutes past every even numbered hour, or every odd-numbered
hour.
.Sp
Clearly I mean these functions to be used in programs that are crontabbed
to run at particular intervals, as with a crontab line like one of these:
.Sp
.Vb 6
\& 52 * * * * ~/thingy # => rss_hourly
\& 52 23 * * * ~/thingy # => rss_daily
\& 52 4,16 * * * ~/thingy # => rss_twice_daily
\& 52 5,13,21 * * * ~/thingy # => rss_thrice_daily
\& 52 23 * * 3 ~/thingy # => rss_weekly
\& 52 */2 * * * ~/thingy # => rss_every_other_hour
.Ve
.Sp
Clearly there aren't \f(CW\*(C`rss_\f(CIinterval\f(CW\*(C'\fR functions for all the scheduling
possibilities programs \*(-- if you have a program that has to run at
6am, 8am, 1pm, and 4pm, there's no function for that. However, the above
crontab lines (or with minor changes, like \f(CW\*(C`1,9,17\*(C'\fR instead of \f(CW\*(C`5,13,21\*(C'\fR)
are just fine for almost every \s-1RSS\s0 feed I've run.
.Sp
An aside: I recommend running the programs at about 52 minutes past the hour,
generally in series, like so:
.Sp
.Vb 1
\& 52 5,13,21 * * * ~/thingy ; ~/dodad ; ~/makething ; ~/gizmo
.Ve
.Sp
However, your mileage may vary.
.Sp
Incidentally, these functions take no arguments, so the parentheses are
optional. That is, these two lines do the same thing:
.Sp
.Vb 2
\& rss_hourly;
\& rss_hourly();
.Ve
.SS "\s-1MINOR FUNCTIONS\s0"
.IX Subsection "MINOR FUNCTIONS"
These are functions that you probably won't need often, or at all. I include
these for the sake of completeness, and so that advanced users might find them
useful in some cases.
.ie n .IP """rss_skipHours( \fIgmt_hour_num, gmt_hour_num, ...\fP );""" 4
.el .IP "\f(CWrss_skipHours( \f(CIgmt_hour_num, gmt_hour_num, ...\f(CW );\fR" 4
.IX Item "rss_skipHours( gmt_hour_num, gmt_hour_num, ... );"
This function directly sets the \f(CW\*(C`skipHours\*(C'\fR element's values to the
specified \s-1GMT\s0 hour numbers.
.ie n .IP """rss_updateHours();""" 4
.el .IP "\f(CWrss_updateHours();\fR" 4
.IX Item "rss_updateHours();"
.PD 0
.ie n .IP """rss_updateHours( \fIgmt_hour_num, gmt_hour_num, ...\fP );""" 4
.el .IP "\f(CWrss_updateHours( \f(CIgmt_hour_num, gmt_hour_num, ...\f(CW );\fR" 4
.IX Item "rss_updateHours( gmt_hour_num, gmt_hour_num, ... );"
.PD
This function is a wrapper around \f(CW\*(C`rss_skipHours\*(C'\fR \*(-- you call
\&\f(CW\*(C`rss_updateHours\*(C'\fR with a list of \s-1GMT\s0 hour numbers, and
\&\f(CW\*(C`rss_updateHours\*(C'\fR will call \f(CW\*(C`rss_skipHours(0 .. 23)\*(C'\fR except \fIwithout\fR
whatever hour numbers you specified.
.Sp
If you call with an empty list (i.e., \f(CW\*(C`rss_updateHours();\*(C'\fR), then
we uses \f(CW\*(C`gmtime\*(C'\fR to find out the current hour (and rounds it up
if it's after 50 minutes past), basically just as if you'd called:
.Sp
.Vb 1
\& rss_updateHours( (gmtime(600+time()))[2] );
.Ve
.ie n .IP """rss_skipDays();""" 4
.el .IP "\f(CWrss_skipDays();\fR" 4
.IX Item "rss_skipDays();"
.PD 0
.ie n .IP """rss_skipDays( \fIgmt_day_num, gmt_day_num, ...\fP );""" 4
.el .IP "\f(CWrss_skipDays( \f(CIgmt_day_num, gmt_day_num, ...\f(CW );\fR" 4
.IX Item "rss_skipDays( gmt_day_num, gmt_day_num, ... );"
.ie n .IP """rss_skipDays( \fIgmt_day_name, gmt_day_name, ...\fP );""" 4
.el .IP "\f(CWrss_skipDays( \f(CIgmt_day_name, gmt_day_name, ...\f(CW );\fR" 4
.IX Item "rss_skipDays( gmt_day_name, gmt_day_name, ... );"
.PD
This function directly sets the \f(CW\*(C`skipDays\*(C'\fR element's values to the
specified weekdays. Note that this accepts either integers (like
6 for Saturday, Sunday being either 0 or 7), or their exact
English names.
.Sp
If you use the \f(CW\*(C`skipDays\*(C'\fR field, consider that it refers to days
figured by \s-1GMT,\s0 not local time. For example, if I say to skip Saturdays,
that means Saturdays \s-1GMT,\s0 which in my timezone (Alaska) starts
in the middle of Friday afternoon.
.ie n .IP """rss_updateDays();""" 4
.el .IP "\f(CWrss_updateDays();\fR" 4
.IX Item "rss_updateDays();"
.PD 0
.ie n .IP """rss_updateDays( \fIgmt_day_num, gmt_day_num, ...\fP );""" 4
.el .IP "\f(CWrss_updateDays( \f(CIgmt_day_num, gmt_day_num, ...\f(CW );\fR" 4
.IX Item "rss_updateDays( gmt_day_num, gmt_day_num, ... );"
.ie n .IP """rss_updateDays( \fIgmt_day_name, gmt_day_name, ...\fP );""" 4
.el .IP "\f(CWrss_updateDays( \f(CIgmt_day_name, gmt_day_name, ...\f(CW );\fR" 4
.IX Item "rss_updateDays( gmt_day_name, gmt_day_name, ... );"
.PD
This function is a wrapper around \f(CW\*(C`rss_skipDays\*(C'\fR \*(-- you call
\&\f(CW\*(C`rss_updateDays\*(C'\fR with a list of \s-1GMT\s0 day names/numbers, and
\&\f(CW\*(C`rss_updateDays\*(C'\fR will call \f(CW\*(C`rss_skipDays(0 .. 6)\*(C'\fR except \fIwithout\fR
whatever days you specified.
.Sp
If you call with an empty list (i.e., \f(CW\*(C`rss_updateDays();\*(C'\fR), then
we uses \f(CW\*(C`gmtime\*(C'\fR to find out the current day (\s-1GMT\s0!), basically
just as if you'd called:
.Sp
.Vb 1
\& rss_updateDays( (gmtime(600+time()))[6] );
.Ve
.ie n .IP """rss_updatePeriod( \fIperiodstring\fP );""" 4
.el .IP "\f(CWrss_updatePeriod( \f(CIperiodstring\f(CW );\fR" 4
.IX Item "rss_updatePeriod( periodstring );"
This function directly sets the \f(CW\*(C`sy:updatePeriod\*(C'\fR element's value to the
period specified. You must specify one of the strings:
\&\*(L"yearly\*(R", \*(L"monthly\*(R", \*(L"weekly\*(R", \*(L"daily\*(R", \*(L"hourly\*(R".
I advise using \*(L"weekly\*(R" only if you know what you're doing, and
\&\*(L"yearly\*(R", \*(L"monthly\*(R" only if you \fIreally\fR know what you're doing.
.ie n .IP """rss_updatePeriod( \fIperiodstring\fP, \fIint\fP, \fIbase\fP );""" 4
.el .IP "\f(CWrss_updatePeriod( \f(CIperiodstring\f(CW, \f(CIint\f(CW, \f(CIbase\f(CW );\fR" 4
.IX Item "rss_updatePeriod( periodstring, int, base );"
This is a shortcut for
\&\f(CW\*(C`rss_updatePeriod(\f(CIperiodstring\f(CW); rss_updateFrequency(\f(CIint\f(CW)\*(C'\fR
.ie n .IP """rss_updatePeriod( \fIperiodstring\fP, \fIint\fP, \fIbase\fP );""" 4
.el .IP "\f(CWrss_updatePeriod( \f(CIperiodstring\f(CW, \f(CIint\f(CW, \f(CIbase\f(CW );\fR" 4
.IX Item "rss_updatePeriod( periodstring, int, base );"
This is a shortcut for
\&\f(CW\*(C`rss_updatePeriod(\f(CIperiodstring\f(CW); rss_updateFrequency(\f(CIint\f(CW);
rss_updateBase(\f(CIbase\f(CW)\*(C'\fR
.ie n .IP """rss_updateBase( \fIiso_date_string\fP );""" 4
.el .IP "\f(CWrss_updateBase( \f(CIiso_date_string\f(CW );\fR" 4
.IX Item "rss_updateBase( iso_date_string );"
.PD 0
.ie n .IP """rss_updateBase( \fIepoch_time\fP );""" 4
.el .IP "\f(CWrss_updateBase( \f(CIepoch_time\f(CW );\fR" 4
.IX Item "rss_updateBase( epoch_time );"
.PD
This function directly sets the \f(CW\*(C`sy:updateBase\*(C'\fR element's value to the
moment specified. If you pass in an epoch time, it is converted to
an \s-1ISO\s0 date string.
.ie n .IP "the accessor ""rss_updateFrequency( \fIinteger\fP );""" 4
.el .IP "the accessor \f(CWrss_updateFrequency( \f(CIinteger\f(CW );\fR" 4
.IX Item "the accessor rss_updateFrequency( integer );"
This function directly sets the \f(CW\*(C`sy:updateFrequency\*(C'\fR element's value to the
value specified. The value has to be a nonzero positive integer.
.Sp
For example, this means that this feed updates at/by the start of every hour
and 30 minutes past:
.Sp
.Vb 3
\& rss_updateBase(\*(Aq2000\-01\-01T00:00\-00:00\*(Aq);
\& rss_updateFrequency(2);
\& rss_updatePeriod(\*(Aqhourly\*(Aq); # 2*hourly means "twice an hour"
.Ve
.Sp
Recall that this can also be done with the
the \f(CW\*(C`rss_updatePeriod( \f(CIper\f(CW, \f(CIfreq\f(CW, \f(CIbase\f(CW )\*(C'\fR shortcut, like so:
.Sp
.Vb 1
\& rss_updateBase(\*(Aqhourly\*(Aq, 2, \*(Aq2000\-01\-01T00:00\-00:00\*(Aq);
.Ve
.ie n .IP "the accessor ""rss_retention(\fInumber\fP)""" 4
.el .IP "the accessor \f(CWrss_retention(\f(CInumber\f(CW)\fR" 4
.IX Item "the accessor rss_retention(number)"
If you are using an \f(CW\*(C`rss_history_file(\f(CIfile\f(CW)\*(C'\fR, the history file will
accrete a list of all URLs it has seen. But to keep this file from potentially
getting immense, items that haven't been seen for a while are thrown out.
The period of time a feed's items go unseen before each is forgotten is
called that feed's \fBretention\fR, and is expressed in seconds.
.Sp
The default retention value is 32 days (i.e., 32*24*60*60, the number
of seconds in 32 days). If you wanted to change it to just a week,
you would do this with \f(CW\*(C`rss_retention(7*24*60*60)\*(C'\fR.
.Sp
As a special case, a zero or negative value for the retention means
to never clear anything from the history file, no matter how long
it has gone unseen.
.ie n .IP """rss_add_comment( \fIstrings\fP );""" 4
.el .IP "\f(CWrss_add_comment( \f(CIstrings\f(CW );\fR" 4
.IX Item "rss_add_comment( strings );"
Call this function if you want to add extra \s-1XML\s0 comments to this \s-1RSS\s0 file.
For example, if you call this:
.Sp
.Vb 4
\& rss_add_comment(
\& "Our terms of use: http://wherever.int/rsstou.html",
\& "Any questions? Ask jimmy@wherever.int",
\& );
.Ve
.Sp
\&...then this \s-1RSS\s0 feed will contain this \s-1XML\s0 fairly early on in the file:
.Sp
.Vb 2
\&
\&
.Ve
.ie n .IP "the accessor ""rss_css( \fIurl\fP )""" 4
.el .IP "the accessor \f(CWrss_css( \f(CIurl\f(CW )\fR" 4
.IX Item "the accessor rss_css( url )"
This defines the given \s-1URL\s0 as being the XML-CSS stylesheet for this \s-1RSS\s0
feed. The default value is \*(L"./rss.css\*(R" if \f(CW\*(C`\-e "rss.css"\*(C'\fR is true, otherwise
is the value http://www.interglacial.com/rss/rss.css
.ie n .IP "the accessor ""rss_xsl( \fIurl\fP )""" 4
.el .IP "the accessor \f(CWrss_xsl( \f(CIurl\f(CW )\fR" 4
.IX Item "the accessor rss_xsl( url )"
This defines the given \s-1URL\s0 as being the XML-XSL stylesheet for this \s-1RSS\s0
feed. The default value is none.
.ie n .IP "The accessors ""rss_url( \fIstring\fP ), rss_title( \fIstring\fP ), rss_description( \fIstring\fP )""" 4
.el .IP "The accessors \f(CWrss_url( \f(CIstring\f(CW ), rss_title( \f(CIstring\f(CW ), rss_description( \f(CIstring\f(CW )\fR" 4
.IX Item "The accessors rss_url( string ), rss_title( string ), rss_description( string )"
These define this feed's \s-1URL,\s0 title, and description. These functions
are just for completeness, since it's simpler to just specify any/all of
these parameters in the call to \f(CW\*(C`rss_new\*(C'\fR.
.ie n .IP "the accessor ""rss_ttl( \fInumber\fP )""" 4
.el .IP "the accessor \f(CWrss_ttl( \f(CInumber\f(CW )\fR" 4
.IX Item "the accessor rss_ttl( number )"
This sets the parameter of this \s-1RSS\s0 feed's \f(CW\*(C`ttl\*(C'\fR element, which
suggests how long (in minutes, not seconds!) an \s-1RSS\s0 reader should wait after it polls
a feed until it polls it again. For example, \f(CW\*(C`rss_ttl(90)\*(C'\fR would suggest
that a reader should not poll this feed more often than every 90 minutes.
.Sp
(This element is somewhat obsolescent next to the newer and more
informative \f(CW\*(C`sy:update*\*(C'\fR elements, but is included for backward
compatibility.)
.ie n .IP "the accessor ""rss_allow_duplicates( \fIboolean\fP )""" 4
.el .IP "the accessor \f(CWrss_allow_duplicates( \f(CIboolean\f(CW )\fR" 4
.IX Item "the accessor rss_allow_duplicates( boolean )"
This controls whether or not duplicate items are filtered out out the
feed. By default this is \fIon\fR. Note that duplicates are detected only
by their \s-1URL,\s0 so if you call this:
.Sp
.Vb 3
\& rss_item(\*(Aqhttp://foo.int/donate\*(Aq, "Give!");
\& rss_item(\*(Aqhttp://foo.int/donate\*(Aq, "We need money!");
\& rss_save(\*(Aqbegging.rss\*(Aq);
.Ve
.Sp
\&...then only the first will appear in the feed, since the second item
has a \s-1URL\s0 that is already being saved in this feed. (However,
\&\f(CW\*(C`rss_item_count\*(C'\fR is still 2, because filtering out duplicates is
something that only happens as the feed is saved.)
.ie n .IP "the accessor ""rss_docs( \fIurl\fP )""" 4
.el .IP "the accessor \f(CWrss_docs( \f(CIurl\f(CW )\fR" 4
.IX Item "the accessor rss_docs( url )"
This sets the value of the not-generally-useful \f(CW\*(C`doc\*(C'\fR \s-1RSS\s0 element.
The default value is \*(L"./about_rss.html\*(R" if \f(CW\*(C`\-e "about_rss.html"\*(C'\fR is
true, otherwise \*(L"http://www.interglacial.com/rss/about.html\*(R".
.ie n .IP "the accessors ""rss_image_url(\fIurl\fP), rss_image_width(\fInumber\fP), rss_image_height(\fInumber\fP), rss_image_title(\fItext\fP), rss_image_link(\fIurl\fP), rss_image_description(\fItext\fP)""" 4
.el .IP "the accessors \f(CWrss_image_url(\f(CIurl\f(CW), rss_image_width(\f(CInumber\f(CW), rss_image_height(\f(CInumber\f(CW), rss_image_title(\f(CItext\f(CW), rss_image_link(\f(CIurl\f(CW), rss_image_description(\f(CItext\f(CW)\fR" 4
.IX Item "the accessors rss_image_url(url), rss_image_width(number), rss_image_height(number), rss_image_title(text), rss_image_link(url), rss_image_description(text)"
These are for manually setting the values of this feed's image element's
subelements:
.Sp
.Vb 8
\&
\& (rss_image_url)
\& (rss_image_width)
\& (rss_image_height)
\& (rss_image_title)
\& (rss_image_link)
\& (rss_image_description)
\&
.Ve
.Sp
You rarely need to call any of these \f(CW\*(C`rss_image_\f(CIwhatever\f(CW\*(C'\fR functions \*(--
usually just calling \f(CW\*(C`rss_image( \f(CIurl, h, w\f(CW );\*(C'\fR is enough.
.SH "RSS VERSION"
.IX Header "RSS VERSION"
\&\s-1RSS\s0 feeds emitted by this module are basically according to v0.92 \s-1RSS,\s0
with a very few extensions from v2.0 \s-1RSS.\s0 They are not \s-1RDF\s0 files.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1XML::RSS\s0
.PP
.PP
.PP
.PP
.PP
You might also like my book \fIPerl and \s-1LWP\s0\fR, which discusses the many
screen-scraping techniques that you would use for extracting data from
\&\s-1HTML\s0 to make into \s-1RSS\s0 feeds:
.IP "" 4
.IX Item ""
.PD 0
.IP "" 4
.IX Item ""
.IP "" 4
.IX Item ""
.IP " \*(-- examples of Perl programs that produce \s-1RSS\s0's (which are visible at )" 4
.IX Item " examples of Perl programs that produce RSS's (which are visible at )"
.PD
.SH "COPYRIGHT AND DISCLAIMERS"
.IX Header "COPYRIGHT AND DISCLAIMERS"
Copyright (c) 2003,4 Sean M. Burke. All rights reserved.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.PP
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.
.PP
Portions of the data tables in this module are derived from the
entity declarations in the W3C \s-1XHTML\s0 specification.
.PP
Currently (January 2004), that's these three:
.PP
.Vb 3
\& http://www.w3.org/TR/xhtml1/DTD/xhtml\-lat1.ent
\& http://www.w3.org/TR/xhtml1/DTD/xhtml\-special.ent
\& http://www.w3.org/TR/xhtml1/DTD/xhtml\-symbol.ent
.Ve
.PP
Portions of the code in this module were adapted from parts of
Gisle Aas's LWP::Simple and the old (v2.x) version of his
HTML::Parser.
.SH "AUTHOR"
.IX Header "AUTHOR"
Sean M. Burke \f(CW\*(C`sburke@cpan.org\*(C'\fR