Tim Skirvin


News::Active - keep track of news active file information


  use News::Active;
  my $active = News::Active->new( '/home/tskirvin/kiboze/active' );

See below for more information.


News::Active is used to keep track of active newsgroup information in an external file. It contains many News::Active::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.



$News::Active::DEBUG - default value for 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 [, HASH] )

Creates and returns a new News::Active 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::Active::Entry objects.

filename ()

Returns the filename used for loading and saving our News::Active 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::Active::Entry object for GROUP, or undef if none exists.

entries ( PATTERN )

Returns an array of News::Active::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::Active::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::Active::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.

add_article ( GROUP [, ARGS] )

Invokes News::Active::add_article() on the entry for GROUP.

Input/Output Functions

The following functions are used for reading, displaying, and saving information from News::Active and News::Active::Entry.

read ( [FILE] )

Reads News::Active::Entry information from FILE (or the value of file()), populating the News::Active object. This file contains lines that each contain the output from a single News::Active::Entry::output() call. Returns 1 on success, undef otherwise.

printable ()

Returns an array (or arrayref, depending on invocation) containing the value of News::Active::Entry::print() on each entry within the News::Active object. These are then suitable for printing.

output ()

Returns an array (or arrayref, depending on invocation) containing the value of News::Active::Entry::output() on each entry within the News::Active 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.


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.


File locking would be nice.




News::Archive, News::GroupInfo


Tim Skirvin <tskirvin@killfile.org>




This code may be redistributed under the same terms as Perl itself.


Copyright 2003-2004, Tim Skirvin.