/ 
Perlanet-0.41
River stage one • 1 direct dependent • 1 total dependent
/ Perlanet

NAME

Perlanet - A program for creating web pages that aggregate web feeds (both RSS and Atom).

SYNOPSIS

my $perlanet = Perlanet->new;
$perlanet->run;

DESCRIPTION

Perlanet is a program for creating web pages that aggregate web feeds (both RSS and Atom). Web pages like this are often called "Planets" after the Python software which originally popularised them. Perlanet is a planet builder written in Perl - hence "Perlanet".

The emphasis on Perlanet is firmly on simplicity. It reads web feeds, merges them and publishes the merged feed as a web page and as a new feed. That's all it is intended to do. If you want to do more with your feeds (create feeds from inputs that don't publish feeds, filter or transform them in complex ways or publish them in interesting ways) then Perlanet isn't the right software for you. In that case I recommend that you take a look at Plagger - which is another feed aggregator, but one that is far more complex and, therefore, far more flexible.

For most uses, you probably don't want to use the Perlanet module. The perlanet command line program is far more likely to be useful.

CONSTRUCTOR

new

my $perlanet = Perlanet->new([ $config_filename ]);

The constructor method. Can be passed the filename of a configuration file (default ./perlanetrc) or a hashref of initialisers.

Example Configuration File

title: planet test
description: A Test Planet
url: http://planet.example.com/
author:
  name: Dave Cross
  email: dave@dave.org.uk
entries: 20
opml: opml.xml
page:
  file: index.html
  template: index.tt
feed:
  file: atom.xml
  format: Atom
cache_dir: /tmp/feeds
feeds:
  - url: http://blog.dave.org.uk/atom.xml
    title: Dave's Blog
    web: http://blog.dave.org.uk/
  - url: http://use.perl.org/~davorg/journal/rss
    title: Dave's use.perl Journal
    web: http://use.perl.org/~davorg/journal/
  - url: http://www.oreillynet.com/pub/feed/31?au=2607
    title: Dave on O'Reillynet
    web: http://www.oreillynet.com/pub/au/2607

For a detailed explanation of the configuration file contents, see "CONFIGURATION FILE" in perlanet.

Customised use (advanced)

my $perlanet = Perlanet->new(\%custom_attr_values);

Perlanet is a Moose class, if the configuration file doesn't provide enough flexibility, you may also instantiate the attribute values directly.

See "ATTRIBUTES" below for details of the key/value pairs to pass in.

ATTRIBUTES

cfg

A hashref of configuration data. This is filled from the configuration file if supplied. Use this if you want an alternative to the YAML format of the file.

ua

An instance of LWP::UserAgent. Defaults to a simple agent using $cfg->{agent} as the user agent name, or Perlanet/$VERSION .

opml

An instance of XML::OPML::SimpleGen. Optional. Defaults to a new instance with $cfg->{title} as it's title.

cache

An instance of CHI. Optional. Defaults to a new instance with the root_dir set to $cfg->{cache_dir}, if it was supplied.

cutoff

An instance of DateTime which represents the earliest date for which feed posts will be fetched/shown.

feeds

An arrayref of Perlanet::Feed objects representing the feeds to collect data from.

tidy

An instance of HTML::Tidy used to tidy the feed entry contents before outputting. For default settings see source of Perlanet.pm.

scrubber

An instance of HTML::Scrubber used to remove unwanted content from the feed entries. For default settings see source of Perlanet.pm.

METHODS

fetch_feeds

Called internally by "run" and passed the list of feeds in "feeds".

Attempt to download all given feeds, as specified in the feeds attribute. Returns a list of Perlanet::Feed objects, with the actual feed data loaded.

NB: This method also modifies the contents of "feeds".

select_entries

Called internally by "run" and passed the list of feeds from "fetch_eeds".

Returns a combined list of Perlanet::Entry objects from all given feeds.

sort_entries

Called internally by "run" and passed the list of entries from "select_entries".

Sort the given list of entries into created/modified order for aggregation. Takes a list of Perlanet::Entrys, and returns an ordered list.

clean

Clean a content string into a form presentable for display. By default, this means running the content through both HTML::Tidy and HTML::Scrubber. These 2 modules are configurable by override the "tidy" and "scrubber" attributes. If you do not wish to use HTML::Tidy/HTML::Scrubber or do something more complex, you may override this method.

Takes a string, and returns the cleaned string.

build_feed

Called internally by "run" and passed the list of entries from "sort_entries".

Takes a list of Perlanet::Entrys, and returns a Perlanet::Feed that is the actual feed for the planet.

render

Called internally by "run" and passed the feed from "build_feed".

Render the planet feed as a page. By default, this uses Template Toolkit to render to an HTML file, but can be overriden to render to wherever you need.

Takes a Perlanet::Feed as input (as generated by build_feed, the result is output to the configured $cfg->[page}{file>.

save

Called internally by "run" and passed the Perlanet::Feed from "build_feed".

Save the feed XML to a file on disk.

update_opml

Updates the OPML file of all contributers to this planet. If the opml attribute does not have a value, this method does nothing, otherwise it inserts each author into the OPML file and saves it to disk.

Uses the list of feeds from the "CONFIGURATION" in perlanet.

run

The main method which runs the perlanet process.

TO DO

See http://wiki.github.com/davorg/perlanet

SUPPORT

There is a mailing list which acts as both a place for developers to talk about maintaining and improving Perlanet and also for users to get support. You can sign up to this list at http://lists.mag-sol.com/mailman/listinfo/perlanet

To report bugs in Perlanet, please use the CPAN request tracker. You can either use the web page at http://rt.cpan.org/Public/Bug/Report.html?Queue=Perlanet or send an email to bug-Perlanet@rt.cpan.org.

SEE ALSO

AUTHOR

Dave Cross, <dave@mag-sol.com>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Magnum Solutions Ltd.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.