/ 
WWW-Yahoo-Groups-1.85
River stage zero No dependents
/ WWW::Yahoo::Groups

NAME

WWW::Yahoo::Groups - automated access to Yahoo! Groups.

SYNOPSIS

my $y = WWW::Yahoo::Groups->new();
$y->login( $user => $pass );
$y->list( 'Jade_Pagoda' );
my $email = $y->fetch_message( 2345 );

# Error catching
my $email = eval { $y->fetch_message( 93848 ) };
if ( $@ and ref $@ and $@->isa('X::WWW::Yahoo::Groups') )
{
    warn "Problem: ".$@->error;
}

ABSTRACT

WWW::Yahoo::Groups retrieves messages from the archive of Yahoo Groups. It provides a simple OO interface to logging in and retrieving said messages which you may then do with as you will.

DESCRIPTION

WWW::Yahoo::Groups is a subclass of WWW::Mechanize, overriding a few methods and supplying a few extra. As such, any method available in WWW::Mechanize is available to WWW::Yahoo::Groups, perhaps augmented with extra features.

Try to be a well behaved bot and sleep() for a few seconds (at least) after doing things. It's considered polite. There's a method autosleep() that should be useful for this.

It is recommended that you use this only if you're the moderator of a group, else you will get munged email addresses for everything. If there's sufficient demand for semi-automatic address demunging, I'll add it.

All exceptions are subclasses of X::WWW::Yahoo::Groups, itself a subclass of Exception::Class.

Things it does

  • Handles access restricted archives. It lets you login.

  • Handles the intermittent advertisements. It notes that it got one and progresses straight to the message.

  • Handles attachments. We get the source which happens to be the raw stuff.

  • Sanity checking. Could be improved, but it will generally barf if it doesn't understand something.

Things it is yet to do

  • Handle errors. Well, it does, but not as gracefully as it might in some situations.

  • Header restoration. I've found that some groups' archives have unusually corrupted headers. Evidently it would be beneficial to restore these headers. As far as I can tell, it comes from not being a moderator on the lists in question.

As these are recognised flaws, they are on the TODO list.

METHODS

new()

Create a new WWW::Yahoo::Groups robot.

my $y = WWW::Yahoo::Groups->new();

agent()

Returns or sets the WWW::Mechanize based agent. Not for general use.

debug()

Enable/disable/read debugging mode.

$y->debug(0); # Disable
$y->debug(1); # Enable
warn "Debugging!" if $y->debug();

get()

Fetch a given URL.

If debug() is enabled, then it will displaying a warning showing the URL. If autosleep() has been given an interval, then get() will sleep for that interval after successfully fetching a page.

$y->get( 'http://groups.yahoo.com' );

Generally, you won't need to use this method. It's used by a number of the other methods and will throw a X::WWW::Yahoo::Groups::BadFetch if it is unable to retrieve the specified page.

Returns 0 if success, else an exception object.

my $rv = $y->get( 'http://groups.yahoo.com' );
$rv->rethrow if $rv;

# or, more idiomatically
my $rv = $y->get( 'http://groups.yahoo.com' ) and $rv->rethrow;

autosleep()

If given a parameter, it sets the numbers of seconds to sleep. Otherwise, it returns the number.

$y->autosleep( 5 );
sleep ( $y->autosleep() );

May throw X::WWW::Yahoo::Groups::BadParam if given invalid parameters.

This is used by get(). If autosleep() is set, then get() will sleep() for the specified period after every fetch.

login()

Logs the robot into the Yahoo! Groups system.

$y->login( $user => $passwd );

May throw:

  • X::WWW::Yahoo::Groups::BadFetch if it cannot fetch any of the appropriate pages.

  • X::WWW::Yahoo::Groups::BadParam if given invalid parameters.

  • X::WWW::Yahoo::Groups::BadLogin if unable to log in for some reason (error will be given the text of the Yahoo error).

  • X::WWW::Yahoo::Groups::AlreadyLoggedIn if the object is already logged in. I intend to make this exception redundant, and add a logout() method.

logout()

Logs the robot out of the Yahoo! Groups system.

$y->logout();

May throw:

  • X::WWW::Yahoo::Groups::BadFetch if it cannot fetch any of the appropriate pages.

  • X::WWW::Yahoo::Groups::BadParam if given invalid parameters.

  • X::WWW::Yahoo::Groups::NotLoggedIn if the bot is already logged out (or never logged in).

loggedin()

Returns 1 if you are logged in, else 0. Note that this merely tests if you've used the login() method successfully, not whether the Yahoo! site has expired your session.

print "Logged in!\n" if $w->loggedin();

list()

If given a parameter, it sets the list to use. Otherwise, it returns the current list, or undef if no list is set.

IMPORTANT: list name must be correctly cased as per how Yahoo! Groups cases it. If not, you may experience odd behaviour.

$y->list( 'Jade_Pagoda' );
my $list = $y->list();

May throw X::WWW::Yahoo::Groups::BadParam if given invalid parameters.

See also lists() for how to get a list of possible lists.

lists()

If you'd like a list of the groups to which you are subscribed, then use this method.

my @groups = $w->lists();

May throw X::WWW::Yahoo::Groups::BadParam if given invalid parameters, or X::WWW::Yahoo::Groups::BadFetch if it cannot fetch any of the appropriate pages from which it extracts the information.

Note that it does handle people with more than one page of groups.

first_msg_id()

Returns the lowest message number with the archive.

my $first = $w->first_msg_id();

It will throw X::WWW::Yahoo::Groups::NoListSet if no list has been specified with lists(), X::WWW::Yahoo::Groups::UnexpectedPage if the page fetched does not contain anything we thought it would, and X::WWW::Yahoo::Groups::BadFetch if it is unable to fetch the page it needs.

last_msg_id()

Returns the highest message number with the archive.

my $last = $w->last_msg_id();
# Fetch last 10 messages:
for my $number ( ($last-10) .. $last )
{
    push @messages, $w->fetch_message( $number );
}

It will throw X::WWW::Yahoo::Groups::NoListSet if no list has been specified with lists(), X::WWW::Yahoo::Groups::UnexpectedPage if the page fetched does not contain anything we thought it would, and X::WWW::Yahoo::Groups::BadFetch if it is unable to fetch the page it needs.

fetch_message()

Fetches a specified message from the list's archives. Returns it as a mail message (with headers) suitable for saving into a Maildir.

my $message = $y->fetch_message( 435 );

May throw any of:

  • X::WWW::Yahoo::Groups::BadFetch if it cannot fetch any of the appropriate pages.

  • X::WWW::Yahoo::Groups::BadParam if given invalid parameters.

  • X::WWW::Yahoo::Groups::NoListSet if no list is set.

  • X::WWW::Yahoo::Groups::UnexpectedPage if we fetched a page and it was not what we thought it was meant to be.

  • X::WWW::Yahoo::Groups::NotThere if the message does not exist in the archive (any of deleted, never archived or you're beyond the range of the group).

fetch_rss()

Returns the RSS for the group's most recent messages. See XML::Filter::YahooGroups for ways to process this RSS into containing the message bodies.

my $rss = $w->fetch_rss();

If a parameter is given, it will return that many items in the RSS file. The number must be between 1 and 100 inclusive.

my $rss = $w->fetch_rss( 10 );

reformat_headers

This does some simple reformatting of headers. Yahoo!Groups seems to manage to mangle multiline headers. This is particularly noticable with the Received header.

The rule is that any line that starts with a series of lowercase letters or hyphens that is NOT immediately followed by a colon is regarded as being part of the previous line and is indented with a space character (as per RFC2822).

THANKS

Simon Hanmer for having problems with the module, thus resulting in improved error reporting, param validation and corrected prerequisites. Since then, Simon also provided a basis for the lists() and last_msg_id() methods and is causing me to think harder about my exceptions.

Aaron Straup Cope (ASCOPE) for writing XML::Filter::YahooGroups which uses this module for retrieving message bodies to put into RSS.

Randal Schwartz (MERLYN) for pointing out some problems back in 1.4.

Ray Cielencki (SLINKY) for first_msg_id and "Age Restricted" notice bypassing.

BUGS

Support for this module is provided courtesy the CPAN RT system via the web or email:

http://perl.dellah.org/rt/yahoogroups
bug-www-yahoo-groups@rt.cpan.org

This makes it much easier for me to track things and thus means your problem is less likely to be neglected.

LICENSE AND COPYRIGHT

Copyright © Iain Truskett, 2002-2003. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Iain Truskett <spoon@cpan.org>

SEE ALSO

perl, XML::Filter::YahooGroups, http://groups.yahoo.com/.

WWW::Mechanize, Exception::Class.