NAME

News::Overview::Entry - an object for storing specific overview information

SYNOPSIS

  use News::Overview::Entry;
  use News::Overview;
  
  my $article = new News::Article;
  # Populate News::Article somehow; 
  
  # Create a new News::Overview::Entry object
  my $msgid = $article->header('message-id');
  my @refs = split(/\s+/, $article->header('references') || "");
  my %other; 
  foreach ( News::Overview->defaults ) { 
    $other{$_} = $article->header($_) || "";
  }
  my $entry = News::Overview::Entry->new($msgid, \@refs, %other);

See below for more specific information about related functions.

DESCRIPTION

News::Overview::Entry is an object meant to hold overview information about a single news article - that is, the minimal information necessary to sort the article with other articles, as used by XOVER in the NNTP specification. It is primarily a helper class for use with News::Overview; see that manual page for more information.

USAGE

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

Basic functions

new ( MSGID [, REFERENCES, OTHER] )

Creates a new News::Overview::Entry object. MSGID is the Message-ID of the object, and is required (the function will return undef if it's not present).

REFERENCES is an arrayref that contains the message-IDs of the entry's parents. OTHER is a hash of other information about the article, which are stored in the entry.

id ()

Returns the associated message-ID of the Entry.

parent ()

Returns the Entry's parent's message-ID, or undef if there isn't one. This is currently defined as "the last item in References". This isn't currently being used, and may change to something else.

children ()

Returns all of the children of the current Entry; each returned item is another News::Article::Entry object. Note that no children exist until they are added with add_child().

value ( FIELD )

Returns the value of the information stired in FIELD within the Entry.

values ( )

Returns a hashref containing all of the keys and values of the information associated with the Entry.

Additional Information

These functions offer additional information about the Entry, generally by parsing the above information.

depth ()

Returns the "depth" of the Entry, ie the number references above the article. A parent article (one with no References) is depth 0.

time ( )

Returns the time, in seconds since the epoch, that the Entry says it was posted at (generated by parsing the Date header; will default to 0).

This information is cached for later use within the item.

newsgroups ()

Returns the newsgroups associated with the entry, either by parsing the Newsgroups field or Xref. Returns an array of associated newsgroups.

Manipulation Functions

Besides new(), these functions are the only ones that actually modify the Entry in a notable way.

add_child ( CHILDREN )

Add children to the given item, each of which is a News::Overview::Entry object. These are later accessed with children(). This is useful for threading.

Returns the number of children that were successfully added.

REQUIREMENTS

News::Overview, Date::Parse

SEE ALSO

News::Overview

TODO

Use the parent() bit effectively. Make "pseudo-Entries", to make entries for articles that don't exist, to make threading more accurate.

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.