The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

News::Overview - an object to store condensed information about Usenet posts

SYNOPSIS

  use News::Overview;
  use Net::NNTP;
  
  my $overview = News::Overview->new();
  my $nntp = new Net::NNTP;

  $nntp->group("killfile.test");
  $overview->add_from_nntp($nntp->xover);

  foreach my $entry ( $overview->sort ('thread', $overview->entries) ) {
    print $overview->print_entry($entry), "\n";
  }

DESCRIPTION

News::Overview objects store combined information about many messages, as generally done in INN's overview format and semi-codified in the XOVER extentions to RFC1036. Each object is meant to store a single newsgroup's worth of basic header information - by default the message number, subject, poster, date of posting, message identifier, references to the article's parents, size of the body, number of lines in the body, and information on where this message is stored within the server. This information is then used to offer summartes of messages in the group, sort the messages, and so forth.

The main unit of storage within News::Overview is the object News::Overview::Entry; each one of these contains information on a single article. News::Overview itself is dedicated to creating, storing, and manipulating these Entries.

USAGE

All of this object's usage is contained within its functions.

Basic Functions

new ( [ DEFAULT_ARRAY_REF ] )

Creates a new News::Overview object.

If DEFAULT_ARRAY_REF is offered, we will use this to define which fields are stored in all the associated Entries; otherwise, we default to the fields in @News::Overview::DEFAULT. The 'Number:' field is added as well, to store the "article number" that each entry is associated with.

Returns the new blessed object, or undef if unsuccessful.

default ()

In array context, returns the full list of default information associated with each Entry. In scalar context, returns the same as an arrayref.

defaults ( )

Same as default(), except this information is instead based on @News::Overview::DEFAULT (ie doesn't include Number:).

fields ()

In array context, returns the list of fields stored in each associated Entry. In scalar context, returns this as an arrayref.

This differs from default() only in as much as everything after the ':' is trimmed; these are meant to be used as

entries ()

Returns the (unsorted) array of News::Overview::Entry objects within the object.

count ()

Returns the number of News::Overview::Entry objects associated with this object.

Adding Entries

These functions add new News::Overview::Entry items to the object, as parsed from several sources.

insert_entry ( NUMBER, INFOARRAY )

Actually does the work of inserting an Entry into the object. NUMBER is the article number, which is used as they key for this Entry; INFOARRAY is the list of information necessary for each Entry, sorted by whatever function called this one.

Returns undef if there's already an entry matching the given NUMBER, otherwise returns the new entry.

add_xover ( LINES )

Reads in raw xover LINES (such as those created by print()) and creates entries for each, using insert_entry(). Returns the number of Entries that were succesfully added.

add_from_nntp ( LINEHASH )

Reads in the information returned by Net::NNTP's xover() function, and and creates entries for each, using insert_entry(). Returns the number of Entries that were succesfully added.

add_from_article ( NUMBER, ARTICLE )

Takes ARTICLE, a News::Article object, and generates the necessary information to populate an Entry from it. NUMBER is the key that will be associated with the article; we need it separately because we can't really get it from the article directly. Returns 1 if successful, 0 if not (roughly the same as add_xover() and add_from_nntp()).

Sorting Functions

These functions are used to sort the Entries within the News::Overview object.

sort ( SORTTYPE, ENTRIES )

Sort array ENTRIES based on SORTTYPE. Possible sorting types (case insensitive):

  thread        Uses thread() to sort the messages
  date          Sort (numerically) by the article time
  time          Sort (numerically) by the article time
  lines         Sort (numerically) by lines, then by time
  (other)       Sort (with 'cmp') based on the value of the specified
                field, ie sort by 'From' or 'Subject', then by time
  

If SORTTYPE is prefixed with a '-', then we will return the entries in revere order.

Returns the sorted array.

thread ( ENTRIES )

Sort ENTRIES by thread - that is, with articles that directly follow up to a given article following the first article. The general algorithm:

  Sort ENTRIES by depth and time of posting.
  For each entry, return the entry and its sorted children.
  No article is returned twice.

This doesn't quite work the way you'd expect it to; if the original parent isn't there, any number of children may appear elsewhere, because there was no common parent ENTRY to hold things together. The only solution I can see is to look at parents as well, sorting them but not printing them, which isn't currently being done; I may do this in a future version of this package.

This function is fairly computationally intensive. It might be nice to cache this information somehow in some applications; I suspect that this would be a job for a different module, however. There's probably also some computational cruft that I haven't looked for yet.

NNTP Functions

These functions perform functions similar to those requested by Net::NNTP, and are therefore useful for creating modules dedicated to getting this information in other ways.

overview_fmt ()

Returns an array reference to the field names, in order, that are stored in the Entries.

xover ( MESSAGESPEC [, FIELDS ] )

Returns a hash reference where the keys are the message numbers and the values are array references containing the overview fields for that message. MESSAGESPEC is parsed with Net::NNTP::Function's messagespec() function to decide wich articles to get; FIELDS is an array of fields to retrieve, which (if not offered) will default to the value of fields().

We aren't currently dealing with the response if MESSAGESPEC is a message-ID (or empty); we're assuming that it's just numbers. This is wrong.

Printing Functions

These functions offer printable versions of the overview information, which can be used for long-term storage.

Makes a printable version of all of the Entries in the object. Sorts the entries based on SORT; FIELDS describes which fields to output; defaults to fields(). The saved fields are separated with tabs, with all other whitespace trimmed. This is suitable for saving out to a file and later reading back in with add_xover().

Returns an array of lines of text containing the information in array context, or in scalar context returns these lines joined with newlines.

print_entry ( ENTRY )

Print a specific entry's worth of information, as described above.

REQUIREMENTS

News::Overview::Entry, News::Article, Net::NNTP::Functions

SEE ALSO

News::Overview::Entry, News::Article, Net::NNTP::Functions

NOTES

This was originally designed to be used with News::Archive and kiboze.pl; it eventually got dragged into News::Web as well, and so it became worth making into a separate function. It also didn't quite fit into my newslib project, since it might be worth optimizing this specifically in the future. Aah, well.

TODO

We should build xhdr(), xpat(), and other Net::NNTP functions into here, just like xover() and overview_fmt().

It would be nice if there was a way to say "return 500 entries" in an xover-type context, instead of "return 1 through 500"; sadly, since Net::NNTP->xover() doesn't have this, so I'll have to work out some other way to implement it.

We should be able to limit what we're returning in some more logical manner, ie with an SQL-type select() function - "return all entries posted between x and y dates", or "return all entries posted by user z", or whatever.

AUTHOR

Tim Skirvin <tskirvin@killfile.org>

COPYRIGHT

Copyright 2003 by Tim Skirvin <tskirvin@killfile.org>. This code may be distributed under the same terms as Perl itself.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 271:

You forgot a '=back' before '=head2'