News::Overview is 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";
}
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.
print ( SORT [, FIELDS] )
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.
Product's homepage
Requirements:
· News::Overview::Entry
· News::Article
· Net::NNTP::Functions
· Perl
Find us on Google+
