|rss_new( url );|
|rss_new( url, title );|
|rss_new( url, title, description );|
|or: $rss = XML::RSS::SimpleGen->new(...);||
This function creates a new RSS feed in memory. This should be the first
rss_whatever 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.
The parameters are the full URL, the title, and the description of the site (or page) that youre providing an RSS feed of. The description is optional, but you should provide at least a URL and title.
(As a method, XML::RSS::SimpleGen->new simply returns a new RSS object.)
|the accessor rss_language(language_tag)||
This declares what language this RSS feed is in. It must be
an RFC3066-style language tags like en, or en-US, or zh-TW.
(See I18N::LangTags::List for a list.)
If you dont set the feeds language, it defaults to en, for generic English.
If you call this function without a parameter, it returns the current value of the RSS feeds language. For example:
|the accessor rss_item_limit(number)||
This sets the maximum number of items that this feed will show.
The default value is 0, meaning that there is no maximum.
If you set it to a positive number N, then the feed will show only the first N items that you declare with rss_item. (Or, if you set rss_history_file, then the newest N items that you declare with rss_item.)
If you set it to a negative number -N, then the feed will show only the last N items that you declare with rss_item. (Or, if you set rss_history_file, then the oldest N items you declare with rss_item, which is unlikely to be useful!)
|the accessor rss_webMaster(email-address)||
This declares what email address you, the RSS generator manager, can be
reached at. Example:
|rss_history_file( filename )||
This declares that you want this RSS feed to keep track of what items are
new, and to list them first when the RSS is emitted. To do this, the RSS
generator has to store information in a file, where it tracks its history,
i.e., when was the first time it saw given URLs, and the most recent time
it saw given URLs.
Typical usage is:
You should call rss_history_file before you make any calls to rss_item.
The history-file feature is meant for cases where your RSS-generator program calls rss_item on every link it sees, but only wants the new links to appear in the RSS output. (This can be a good approach if youre making an RSS feed of a page like http://www.guardian.co.uk/ where theres some new links (to the recently added stories), but also links to some days-old stories, and also links to some always-there things like Archive Search and Contact Us pages.
Once you call rss_history_file, the specified file is read in. The in-memory history (stored in the RSS object) is updated as you call rss_item. But the file isnt updated until you call rss_save.
(A do-what-I-mean side effect of calling rss_history_file is that it sets rss_item_limit to 25 if it is currently 0.)
(Incidentally, if youre using rss_history_file as part of a CGI that emits RSS data, instead of a program that just saves to an RSS file, then things will get complicated. Youll need to call an internal method to explicitly commit the history file to disk, and youll need a semaphore file to avoid race conditions. Email me for full info.)
|rss_item( url );|
|rss_item( url, title );|
|rss_item( url, title, description );||
This adds a new item to the current feed. You will need to specify the
URL to add (and it should be a valid-looking URL, starting with
"something:", and not containing any spaces). You may also specify
the title, but its 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.)
Leading and tailing whitespace is removed from whichever of url, title, and description are defined values, and HTML is parsed out.
A simple usage:
Although in practice, a typical call wont have string constants, but will instead be like the example in the Synopsis sectios, namely:
Incidentally, as a do-what-I-mean feature, if the first parameter doesnt look like a URL 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.
(In the unlikely event where you need to avoid the HTML-removal features, you can do this by passing scalar-references instead of normal strings, like so: rss_item($url, $title, \$not_to_be_escaped).)
This returns the number of items youve declared. I anticipate that its
main usage will be something like:
...depending on how/whether youd want to react to cases where you dont see anything to put into an RSS feed.
Note that the parens are optional, since this command takes no options (just like Perls time() function).
|rss_image( url, h, w );||
This declares that you want to declare a particular image as the logo for
this feed. Most feeds dont 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 images URL, 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.
A typical usage:
Be careful not to mix up the height and width.
|rss_save( filename );|
|rss_save( filename, max_age_days );||
This saves the RSS date to the file you specify. If the RSS data hasnt
changed, the file (and its modtime) arent altered. The optional max_age_days
parameter means that if ever the file exists, and its content hasnt 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 RSS file with:
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 hasnt 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 touch) on the whatever.rss file.
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 CGI, where your CGI would probably end like this:
|get_url( url );|
|$content = get_url( url );|
|or: $content = $rss->get_url(...);|
This tries to get the content of the given url, and returns it.
This is quite like LWP::Simples get function, but with some additional features:
|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
rss_weekly). And, where its not just once a day/week, these multiple
times a day are evenly spaced. These functions then set the feeds
updatePeriod, updateBase, updateFrequency, skipHours,
skipDays, and ttl elements appropriately, so that RSS readers can know at
at what times there could (or couldnt) be new content in this feed.
In other words: use rss_twice_daily if this feed is updated at about the same time every day and then again 12 hours later. Use rss_thrice_daily if this feed is updated at the same time daily, and then 8 hours later, and then 8 hours later. And use rss_every_other_hour if the feed updates at about n minutes past every even numbered hour, or every odd-numbered hour.
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:
Clearly there arent rss_interval functions for all the scheduling possibilities programs if you have a program that has to run at 6am, 8am, 1pm, and 4pm, theres no function for that. However, the above crontab lines (or with minor changes, like 1,9,17 instead of 5,13,21) are just fine for almost every RSS feed Ive run.
An aside: I recommend running the programs at about 52 minutes past the hour, generally in series, like so:
However, your mileage may vary.
Incidentally, these functions take no arguments, so the parentheses are optional. That is, these two lines do the same thing:
These are functions that you probably wont 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.
rss_skipHours( gmt_hour_num, gmt_hour_num, ... ); This function directly sets the skipHours elements values to the specified GMT hour numbers. rss_updateHours(); rss_updateHours( gmt_hour_num, gmt_hour_num, ... ); This function is a wrapper around rss_skipHours you call rss_updateHours with a list of GMT hour numbers, and rss_updateHours will call rss_skipHours(0 .. 23) except without whatever hour numbers you specified.
rss_updateHours( (gmtime(600+time())) );
rss_skipDays(); rss_skipDays( gmt_day_num, gmt_day_num, ... ); rss_skipDays( gmt_day_name, gmt_day_name, ... ); This function directly sets the skipDays elements 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.
If you use the skipDays field, consider that it refers to days figured by GMT, not local time. For example, if I say to skip Saturdays, that means Saturdays GMT, which in my timezone (Alaska) starts in the middle of Friday afternoon.
rss_updateDays(); rss_updateDays( gmt_day_num, gmt_day_num, ... ); rss_updateDays( gmt_day_name, gmt_day_name, ... ); This function is a wrapper around rss_skipDays you call rss_updateDays with a list of GMT day names/numbers, and rss_updateDays will call rss_skipDays(0 .. 6) except without whatever days you specified.
rss_updateDays( (gmtime(600+time())) );
rss_updatePeriod( periodstring ); This function directly sets the sy:updatePeriod elements value to the period specified. You must specify one of the strings: yearly, monthly, weekly, daily, hourly. I advise using weekly only if you know what youre doing, and yearly, monthly only if you really know what youre doing. rss_updatePeriod( periodstring, int, base ); This is a shortcut for rss_updatePeriod(periodstring); rss_updateFrequency(int) rss_updatePeriod( periodstring, int, base ); This is a shortcut for rss_updatePeriod(periodstring); rss_updateFrequency(int); rss_updateBase(base) rss_updateBase( iso_date_string ); rss_updateBase( epoch_time ); This function directly sets the sy:updateBase elements value to the moment specified. If you pass in an epoch time, it is converted to an ISO date string. the accessor rss_updateFrequency( integer ); This function directly sets the sy:updateFrequency elements value to the value specified. The value has to be a nonzero positive integer.
For example, this means that this feed updates at/by the start of every hour and 30 minutes past:
rss_updateBase(2000-01-01T00:00-00:00); rss_updateFrequency(2); rss_updatePeriod(hourly); # 2*hourly means "twice an hour"
Recall that this can also be done with the the rss_updatePeriod( per, freq, base ) shortcut, like so:
rss_updateBase(hourly, 2, 2000-01-01T00:00-00:00);
the accessor rss_retention(number) If you are using an rss_history_file(file), the history file will accrete a list of all URLs it has seen. But to keep this file from potentially getting immense, items that havent been seen for a while are thrown out. The period of time a feeds items go unseen before each is forgotten is called that feeds <B>retentionB>, and is expressed in seconds.
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 rss_retention(7*24*60*60).
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.
rss_add_comment( strings ); Call this function if you want to add extra XML comments to this RSS file. For example, if you call this:
...then this RSS feed will contain this XML fairly early on in the file:
the accessor rss_css( url ) This defines the given URL as being the XML-CSS stylesheet for this RSS feed. The default value is ./rss.css if -e "rss.css" is true, otherwise is the value http://www.interglacial.com/rss/rss.css the accessor rss_xsl( url ) This defines the given URL as being the XML-XSL stylesheet for this RSS feed. The default value is none. The accessors rss_url( string ), rss_title( string ), rss_description( string ) These define this feeds URL, title, and description. These functions are just for completeness, since its simpler to just specify any/all of these parameters in the call to rss_new. the accessor rss_ttl( number ) This sets the parameter of this RSS feeds ttl element, which suggests how long (in minutes, not seconds!) an RSS reader should wait after it polls a feed until it polls it again. For example, rss_ttl(90) would suggest that a reader should not poll this feed more often than every 90 minutes.
(This element is somewhat obsolescent next to the newer and more informative sy:update* elements, but is included for backward compatability.)
the accessor rss_allow_duplicates( boolean ) This controls whether or not duplicate items are filtered out out the feed. By default this is on. Note that duplicates are detected only by their URL, so if you call this:
...then only the first will appear in the feed, since the second item has a URL that is already being saved in this feed. (However, rss_item_count is still 2, because filtering out duplicates is something that only happens as the feed is saved.)
the accessor rss_docs( url ) This sets the value of the not-generally-useful doc RSS element. The default value is ./about_rss.html if -e "about_rss.html" is true, otherwise http://www.interglacial.com/rss/about.html. 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 feeds image elements subelements:
<image> <url> (rss_image_url) </url> <width> (rss_image_width) </width> <height> (rss_image_height) </height> <title> (rss_image_title) </title> <link> (rss_image_link) </link> <description> (rss_image_description) </description> </image>
You rarely need to call any of these rss_image_whatever functions usually just calling rss_image( url, h, w ); is enough.
RSS feeds emitted by this module are basically according to v0.92 RSS, with a very few extensions from v2.0 RSS. They are not RDF files.
You might also like my book Perl and LWP, which discusses the many screen-scraping techniques that you would use for extracting data from HTML to make into RSS feeds:
<http://www.oreilly.com/catalog/perllwp/> <http://www.amazon.com/exec/obidos/ASIN/0596001789/> <http://www.amazon.co.uk/exec/obidos/ASIN/0596001789/t> <http://interglacial.com/d/scrapers> examples of Perl programs that produce RSSs (which are visible at <http://interglacial.com/rss/> )
Copyright (c) 2003,4 Sean M. Burke. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
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.
Portions of the data tables in this module are derived from the entity declarations in the W3C XHTML specification.
Currently (January 2004), thats these three:
Sean M. Burke email@example.com
|perl v5.20.3||XML::RSS::SIMPLEGEN (3)||2004-02-07|