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 with filename()) 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 (with read()) 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 (using Net::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 of file()), populating the News::GroupInfo object. This file contains lines that each contain the output from a single News::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 of file()). 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.

cpanm News::Archive

perl -MCPAN -e shell
install News::Archive