NAME
News::GroupInfo - keep track of newsgroup information
SYNOPSIS
use News::GroupInfo;
my $groupinfo= News::Active->new( '/home/tskirvin/kiboze/newsgroups' );
$groupinfo->subscribe("humanities.philosophy.objectivism");
$groupinfo->write;
See below for more information.
DESCRIPTION
News::GroupInfo is used to keep track of passive newsgroup information in an external file. It contains many News::GroupInfo::Entry
objects, one for each newsgroup we are subscribed to. It should be a fairly simple module to use and understand, as it is only a subsection of News::Archive
.
USAGE
Variables
- $News::GroupInfo::DEBUG - default value for c<debug()> in new objects.
- $News::Active::READONLY - default value for
readonly()
in new objects.
Basic Functions
The following functions give us access to the object class
- new ( FILE )
-
Creates and returns a new News::GroupInfo object.
FILE
is the filename (later accessed withfilename()
) that we will load old information from and save to when we close the object. It will be created if it doesn't already exist, and read (withread()
) from if it does.If
HASH
is offered, its possible values:debug Print debugging information when using this object. Defaults to $DEBUG. readonly Don't write anything back out with this object when we're done with it. Defaults to $READONLY.
Returns undef on failure, or the object on success.
- groups ()
-
Returns a hash reference containing all subscribed newsgroups; the keys are the group names, and the values are News::GroupInfo::Entry objects.
- filename ()
-
Returns the filename used for loading and saving our News::GroupInfo information.
- debug ()
-
Returns true if we want to print debugging information, false otherwise.
- readonly ()
-
Returns true if we shouldn't write out the information later, false otherwise.
- entry ( GROUP )
-
Returns the News::GroupInfo::Entry object for
GROUP
, or undef if none exists. - entries ( PATTERN )
-
Returns an array of News::GroupInfo::Entry objects whose newsgroup names match the given pattern
PATTERN
(usingNet::NNTP::Function::wildmat()
.
Newsgroup Functions
The following functions implement the functions that we actually want to use this module for, ie adding groups and articles to the active file.
- subscribe ( GROUP )
-
Adds a News::GroupInfo::Entry entry for the given
GROUP
, thus adding it to our subscription list. Returns 1 on success, undef otherwise. - unsubscribe ( GROUP )
-
Unsubscribe from
GROUP
by making sure there is no News::GroupInfo::Entry entry for that groupname. Returns 1 on success or if we were already unsubscribed, undef otherwise. - subscribed ( GROUP )
-
Returns 1 if we are subscribed to
GROUP
, 0 otherwise.
Input/Output Functions
The following functions are used for reading, displaying, and saving information from News::GroupInfo and News::GroupInfo::Entry.
- read ( [FILE] )
-
Reads News::GroupInfo::Entry information from
FILE
(or the value offile()
), populating the News::GroupInfo object. This file contains lines that each contain the output from a singleNews::GroupInfo::Entry::output()
call. Returns 1 on success, undef otherwise. - printable ()
-
Returns an array (or arrayref, depending on invocation) containing the value of
News::GroupInfo::Entry::print()
on each entry within the News::GroupInfo object. These are then suitable for printing. - output ()
-
Returns an array (or arrayref, depending on invocation) containing the value of
News::GroupInfo::Entry::output()
on each entry within the News::GroupInfo object. These are then suitable for saving to a database and later reloading. - write ( [FILE] )
-
Using the information from output(), writes out to
FILE
(or the value offile()
). Returns 1 on success, undef otherwise. If the readonly flag is set, we don't actually write anything back out.Note that this function is called when the object is destroyed as well.
NOTES
This and News::Active
are fairly similar, but are meant to take care of different types of information. The News::Active file is meant to be modified regularly, every time a new article is added; in INN terms this is the equivalent of the active file. The information in News::GroupInfo is meant to only be modified occasionally, when something major changes; in INN terms this is the equivalent of the newsgroups and active.times files.
TODO
File locking would be nice.
REQUIREMENTS
Net::NNTP::Functions
SEE ALSO
News::Archive, News::Active
AUTHOR
Tim Skirvin <tskirvin@killfile.org>
HOMEPAGE
http://www.killfile.org/~tskirvin/software/news-archive/
LICENSE
This code may be redistributed under the same terms as Perl itself.
COPYRIGHT
Copyright 2003-2004, Tim Skirvin.