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

  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";
  }

$VERSION = "0.12";
package News::Overview;
our $VERSION = "0.12";

# -*- Perl -*-          # Fri Oct 10 11:29:51 CDT 2003 
#############################################################################
# Written by Tim Skirvin <tskirvin@killfile.org>.  Copyright 2003, Tim
# Skirvin.  Redistribution terms are below.
#############################################################################

###############################################################################
### main() ####################################################################
###############################################################################

use strict;
use News::Article;
use News::Overview::Entry;
use Net::NNTP::Functions;

use vars qw( @DEFAULT );
@DEFAULT = qw( Subject: From: Date: Message-ID: References: 
		   	Bytes: Lines: Xref:full );

sub new {
  my ($proto, $default) = @_;
     $default ||= "";
  my $class = ref($proto) || $proto;
  my $self = {
 	Defaults => 	[ ref $default ? @{$default} : @DEFAULT ],
#       Count    =>     0,		# Number of articles currently in here
        Articles =>     {},		# Actual article information
        Article_By_ID =>  {},		# Actual article information
  	     };
  unshift @{$$self{Defaults}}, "Number:";
  $$self{'Fields'} = [ _fields($$self{'Defaults'}) ];
  bless $self, $class;
  $self;
}

sub default { wantarray ? @{shift->{'Defaults'}} : shift->{'Defaults'} ; }
sub defaults { _fields(@DEFAULT) }
sub fields  { wantarray ? @{shift->{'Fields'}}   : shift->{'Fields'}   ; }

# =item value ( KEY [, VALUE ])
# 
# Returns the ...hey, wait a second, we're not doing anything with this!
# 
# =cut
# 
# sub value {
#   my ($self, $key, $value) = @_; 
#   return undef unless $key;
#   $self->values->{$key} = $value if defined $value;
#   $self->values->{$key};
# }
# 
# =item values ( ) 
# 
# =cut
# 
# sub values  { shift->{'Values'} }
 

sub entries { values %{shift->{Articles}} }

sub count { scalar values %{shift->{Articles}} || 0 }

sub insert_entry {
  my ($self, @info) = @_;
  my %hash;
  foreach ($self->fields) { $hash{$_} = shift @info || ""; }
  my $msgid = $hash{'Message-ID'};

  # Don't do anything more if there's already an entry for this
  return undef if $self->{'Articles_By_ID'}->{$msgid};

  my @refs = split(/\s+/, $hash{'References'} || "");
  my $item = new News::Overview::Entry($msgid, \@refs, %hash); 
  foreach (@refs) { 
    my $artbyid = $self->{'Article_By_ID'}->{$_} || undef;
    if ($artbyid) { $artbyid->add_child($item) }
  } 
  $self->{'Article_By_ID'}->{$msgid} = $item;

  my $number = $hash{'Number'};	# Ought to abort if we don't have this
  $self->{'Articles'}->{$number} = $item;
  $item;
}

sub add_xover { 
  my ($self, @lines) = @_;
  my $count = 0;
  foreach my $line (@lines) { 
    chomp; my ($art, @info) = split(/\t/, $line); 
    $self->insert_entry( $art, @info ) and $count++
  }
  $$self{Count} += $count; $count;
}

sub add_from_nntp {
  my ($self, %lines) = @_;
  my $count = 0;
  foreach my $art (keys %lines) { 
    next unless ref $lines{$art};
    my @info = @{$lines{$art}};
    $self->insert_entry( $art, @info ) and $count++
  } 

  $$self{Count} += $count; $count;
}

sub add_from_article {
  my ($self, $num, $article) = @_;
  return undef unless ($num && $article && ref $article);

  my @info;
  my @defaults = ref $self ? $self->default : @DEFAULT;
  foreach my $field (@defaults) {
    $field =~ s/:.*//;
    next if $field eq 'Number';
    # next unless $field;
    if    (lc $field eq 'lines') { push @info, $article->lines; } 
    elsif (lc $field eq 'bytes') { push @info, $article->bytes; } 
    elsif ($article->header($field)) { 
      push @info, $article->header($field);
    } else { push @info, '' } 
  }
  $self->insert_entry( $num, @info ) ? 1 : 0;
}

sub sort {
  my ($self, $sort, @entries) = @_; $sort ||= "";
  my ($reverse, $type) = $sort =~ m/^(\-?)(.*)$/;
  $type ||= 'Number';
  my @return;
  if (lc $type eq 'thread') { 	# thread them
    @return = $self->thread(@entries);
  } elsif (lc $type eq 'lines') { 
    @return = sort { 
	( $a->values->{ucfirst lc $type} <=> $b->values->{ucfirst lc $type} )
     || ( $a->time <=> $b->time ) } @entries; 
  } elsif ( lc $type eq 'date' || lc $type eq 'time' ) { 
    @return = sort { ( $a->time <=> $b->time ) } @entries;
  } elsif ( grep { lc $_ eq lc $type } $self->fields ) { 
    @return = sort { 
	( $a->values->{ucfirst lc $type} cmp $b->values->{ucfirst lc $type} )
     || ( $a->time <=> $b->time ) } @entries; 
  } else { 
    @return = sort { $a->values->{Number} <=> $b->values->{Number} } @entries; 
  }
  $reverse ? reverse @return : @return;
}

sub thread {
  my ($self, @entries) = @_;

  my %added;

  my @return;
  foreach my $ent ( sort News::Overview::_bythread @entries ) { 
    next unless ref $ent;
    my $parent = $ent->id;
    push @return, $ent unless ($added{$ent->id}++);
    my @children = $ent->children;   my @tosort;
    foreach (@children) { push @tosort, $_ unless $added{$_->id} }
    next unless @tosort;
    foreach my $item ( $self->thread(@tosort) ) {
      next unless ref $item;
      # my $item = $$self{Article_By_ID}->{$_};
      push @return, $item unless ($added{$item->id}++); 
    }
  }
  
  @return;
}

sub overview_fmt { my ($self) = @_; ref $self ? $self->default : \@DEFAULT; }

sub xover { 
  my ($self, $spec, @fields) = @_;
  @fields = $self->fields unless scalar @fields;
  my ($first, $last) = messagespec($spec);
  # my ($first, $last) = split('-', $spec);
  $first ||= 0;  
  my %entries;
  foreach my $key (keys %{$self->{Articles}}) {
    next if $key < $first;  
    next unless ($last > 0 && $key <= $last);	

    my $entry = $$self{Articles}->{$key};
		# Should be able to get the article by ID too
    next unless $entry;

    my @over;
    foreach (@fields) { 
      next if $_ eq 'Number'; 	# Skip the 'Number' field
      push @over, $entry->values->{$_} 
    }

    $entries{$key} = \@over;
  }
  \%entries;
}

sub print {
  my ($self, $sort, @fields) = @_;
  @fields = $self->fields unless scalar @fields;
  my @return;
  my @entries = $self->sort($sort, values %{$self->{Articles}});
  foreach my $art (@entries) { 
    push @return, $self->print_entry($art, @fields);
  }
  wantarray ? @return : join("\n", @return);
}

sub print_entry {
  my ($self, $entry, @fields) = @_;
  return "" unless ($entry && ref $entry);
  @fields = $self->fields unless scalar @fields;
  my @over;
  foreach (@fields) { push @over, $entry->value($_) }
  map { s/\s/ /g; } @over;	# Trim all whitespace
  join("\t", @over);
}

###############################################################################
### Internal Functions ########################################################
###############################################################################

### _fields ( ${@heads} )
# Retuns canonical names for the fields header.  Takes an arrayref,
# returns an array.
sub _fields {
  my $heads = shift; 
  my @heads = @{$heads};
  map { s/:.*//g; lc $_ } @heads; 
  @heads;
}

### _bythread ( $a, $b )
# Sort function, to do sorts by thread - this means depth first, then 
# number.  The actual "do children first" part is in thread().  
sub _bythread { 
  $a->depth <=> $b->depth 
    ||
  $a->time <=> $b->time 
  # $a->values->{Number} <=> $b->values->{Number}
}

### _bythread_basic ( $a, $b )
# More basic, depth-only search. 
sub _bythread_basic { $a->depth <=> $b->depth }

1;

###############################################################################
### Version History ###########################################################
###############################################################################
# v0.01b 	Fri Oct 10 11:32:39 CDT 2003 
### First commented version (above date indicates the start of the comments)
# v0.10b	Fri Oct 10 15:25:43 CDT 2003 
### Took out some unnecessary code where necessary.  Made a print_entry()
### function.  
# v0.11b	Fri Oct 10 15:36:45 CDT 2003 
### Very minor documentation changes
# v0.12		Thu Apr 22 13:19:25 CDT 2004 
### No real changes; internal code layout.