/branches/don/proposed/src/Modules/News.pl

#
# News.pl: Advanced news management
#   Author: dms
#  Version: v0.3 (20010412)
#  Created: 20010326
#    Notes: Testing done by greycat, kudos!
#
### structure:
# news{ channel }{ string } { item }
# newsuser{ channel }{ user } = time()
### where item is:
#	Time	- when it was added (used for sorting)
#	Author	- Who by.
#	Expire	- Time to expire.
#	Text	- Actual text.
###

package News;

use strict;

use vars qw($who $chan);

sub Parse {
    my($what)	= @_;
    $chan	= undef;
    $who	= lc $::who;

    if (!keys %::news) {
	if (!exists $::cache{newsFirst}) {
	    &::DEBUG("news: looks like we enabled news option just then; loading up news file just in case.");
	    $::cache{newsFirst} = 1;
	}

	&readNews();
    }

    if ($::msgType ne 'private') {
	$chan = $::chan;
    }

    if (defined $what and $what =~ s/^($::mask{chan})\s*//) {
	# TODO: check if the channel exists aswell.
	$chan	= lc $1;

	if (!&::IsNickInChan($who, $chan)) {
	    &::notice($who, "sorry but you're not on $chan.");
	    return;
	}
    }

    if (!defined $chan) {
	my @chans = &::getNickInChans($who);

	if (scalar @chans > 1) {
	    &::notice($who, "error: I dunno which channel you are referring to since you're on more than one. Try 'news #chan ...' instead");
	    return;
	}

	if (scalar @chans == 0) {
	    &::notice($who, "error: I couldn't find you on any chan. This must be a bug!");
	    return;
	}

	$chan	= $chans[0];
	&::VERB("Guessed $who being on chan $chan",2);
	$::chan	= $chan;	# hack for IsChanConf().
    }

    if (!defined $what or $what =~ /^\s*$/) {
	&list();
	return;
    }

    if ($what =~ /^add(\s+(.*))?$/i) {
	&add($2);

    } elsif ($what =~ /^del(\s+(.*))?$/i) {
	&del($2);

    } elsif ($what =~ /^mod(\s+(.*))?$/i) {
	&mod($2);

    } elsif ($what =~ /^set(\s+(.*))?$/i) {
	&set($2);

    } elsif ($what =~ /^(\d+)$/i) {
	&::VERB("News: read shortcut called.",2);
	&read($1);

    } elsif ($what =~ /^read(\s+(.*))?$/i) {
	&read($2);

    } elsif ($what =~ /^(latest|new)(\s+(.*))?$/i) {
	&latest($3 || $chan, 1);
#	$::cmdstats{'News latest'}++;

    } elsif ($what =~ /^stats?$/i) {
	&stats();

    } elsif ($what =~ /^list$/i) {
	&list();

    } elsif ($what =~ /^(expire|text|desc)(\s+(.*))?$/i) {
	# shortcut/link.
	# nice hack.
	my $cmd = $1;
	my($arg1,$arg2) = split(/\s+/, $3, 2);
	&set("$arg1 $cmd $arg2");

    } elsif ($what =~ /^help(\s+(.*))?$/i) {
	&::help("news $2");

    } elsif ($what =~ /^newsflush$/i) {
	&::msg($who, "newsflush called... check out the logs!");
	&::newsFlush();

    } elsif ($what =~ /^(un)?notify$/i) {
	my $state = ($1) ? 0 : 1;

	# TODO: don't notify even if 'News' is called.
	if (&::IsChanConf('newsNotifyAll') <= 0) {
	    &::DEBUG("news: chan => $chan, ::chan => $::chan.");
	    &::notice($who, "not available for this channel or disabled altogether.");
	    return;
	}

	my $t = $::newsuser{$chan}{$who};
	if ($state) {	# state = 1
	    if (defined $t and ($t == 0 or $t == -1)) {
		&::notice($who, "enabled notify.");
		delete $::newsuser{$chan}{$who};
		return;
	    }
	    &::notice($who, "already enabled.");

	} else {		# state = 0
	    my $x = $::newsuser{$chan}{$who};
	    if (defined $x and ($x == 0 or $x == -1)) {
		&::notice($who, 'notify already disabled');
		return;
	    }
	    $::newsuser{$chan}{$who} = -1;
	    &::notice($who, "notify is now disabled.");
	}

    } else {
	&::notice($who, "unknown command: $what");
    }
}

sub readNews {
    my $file = "$::bot_base_dir/infobot-news.txt";
    if (! -f $file or -z $file) {
	return;
    }

    if (fileno NEWS) {
	&::DEBUG("readNews: fileno exists, should never happen.");
	return;
    }

    my($item,$chan);
    my($ci,$cu) = (0,0);

    open(NEWS, $file);
    while (<NEWS>) {
	chop;

	# TODO: allow commands.

	if (/^[\s\t]+(\S+):[\s\t]+(.*)$/) {
	    if (!defined $item) {
		&::DEBUG("news: !defined item, never happen!");
		next;
	    }

	    $::news{$chan}{$item}{$1} = $2;
	    next;
	}

	# U <chan> <nick> <time>
	if (/^U\s+(\S+)\s+(\S+)\s+(\d+)$/) {
	    $::newsuser{$1}{$2} = $3;
	    $cu++;
	    next;
	}

	if (/^(\S+)[\s\t]+(.*)$/) {
	    $chan = $1;
	    $item = $2;
	    $ci++;
	}
    }
    close NEWS;

    my $cn = scalar(keys %::news);
    return unless ($ci or $cn or $cu);

    &::status("News: read ".
	$ci. &::fixPlural(' item', $ci). ' for '.
	$cn. &::fixPlural(' chan', $cn). ', '.
	$cu. &::fixPlural(' user', $cu), ' cache'
    );
}

sub writeNews {
    if (!scalar keys %::news and !scalar keys %::newsuser) {
	&::VERB("wN: nothing to write.",2);
	return;
    }

    # should define this at the top of file.
    my $file = "$::bot_base_dir/infobot-news.txt";

    if (fileno NEWS) {
	&::ERROR("News: write: fileno NEWS exists, should never happen.");
	return;
    }

    # TODO: add commands to output file.
    my $c = 0;
    my($cc,$ci,$cu) = (0,0,0);

    open(NEWS, ">$file");
    foreach $chan (sort keys %::news) {
	$c = scalar keys %{ $::news{$chan} };
	next unless ($c);
	$cc++;
	my $item;

	foreach $item (sort keys %{ $::news{$chan} }) {
	    $c = scalar keys %{ $::news{$chan}{$item} };
	    next unless ($c);
	    $ci++;

	    print NEWS "$chan $item\n";
	    my $what;
	    foreach $what (sort keys %{ $::news{$chan}{$item} }) {
		print NEWS "    $what: $::news{$chan}{$item}{$what}\n";
	    }
	    print NEWS "\n";
	}
    }

    # TODO: show how many users we wrote down.
    if (&::getChanConfList('newsKeepRead')) {
	# old users are removed in newsFlush(), perhaps it should be
	# done here.

	foreach $chan (sort keys %::newsuser) {

	    foreach (sort keys %{ $::newsuser{$chan} }) {
		print NEWS "U $chan $_ $::newsuser{$chan}{$_}\n";
		$cu++;
	    }
	}
    }

    close NEWS;

    &::status("News: Wrote $ci items for $cc chans, $cu user cache.");
}

sub add {
    my($str) = @_;

    if (!defined $chan or !defined $str or $str =~ /^\s*$/) {
	&::help('news add');
	return;
    }

    if (length $str > 64) {
	&::notice($who, "That's not really an item (>64chars)");
	return;
    }

    if (exists $::news{$chan}{$str}{Time}) {
	&::notice($who, "'$str' for $chan already exists!");
	return;
    }

    $::news{$chan}{$str}{Time}	= time();
    my $expire = &::getChanConfDefault('newsDefaultExpire',7, $chan);
    $::news{$chan}{$str}{Expire}	= time() + $expire*60*60*24;
    $::news{$chan}{$str}{Author}	= $::who;	# case!

    my $agestr	= &::Time2String($::news{$chan}{$str}{Expire} - time() );
    my $item	= &newsS2N($str);
    &::notice($who, "Added '\037$str\037' at [".gmtime(time).
		"] by \002$::who\002 for item #\002$item\002.");
    &::notice($who, "Now do 'news text $item <your_description>'");
    &::notice($who, "This item will expire at \002".
	gmtime($::news{$chan}{$str}{Expire})."\002 [$agestr from now] "
    );

    &writeNews();
}

sub del {
    my($what)	= @_;
    my $item	= 0;

    if (!defined $what) {
	&::help('news del');
	return;
    }

    if ($what =~ /^\d+$/) {
	my $count = scalar keys %{ $::news{$chan} };
	if (!$count) {
	    &::notice($who, "No news for $chan.");
	    return;
	}

	if ($what > $count or $what < 0) {
	    &::notice($who, "$what is out of range (max $count)");
	    return;
	}

	$item	= &getNewsItem($what);
	$what	= $item;		# hack hack hack.

    } else {
	$_	= &getNewsItem($what);	# hack hack hack.
	$what	= $_ if (defined $_);

	if (!exists $::news{$chan}{$what}) {
	    my @found;
	    foreach (keys %{ $::news{$chan} }) {
		next unless (/\Q$what\E/);
		push(@found, $_);
	    }

	    if (!scalar @found) {
		&::notice($who, "could not find $what.");
		return;
	    }

	    if (scalar @found > 1) {
		&::notice($who, "too many matches for $what.");
		return;
	    }

	    $what	= $found[0];
	    &::DEBUG("news: del: str: guessed what => $what");
	}
    }

    if (exists $::news{$chan}{$what}) {
	my $auth = 0;
	$auth++ if ($::who eq $::news{$chan}{$what}{Author});
	$auth++ if (&::IsFlag('o'));

	if (!$auth) {
	    # TODO: show when it'll expire.
	    &::notice($who, "Sorry, you cannot remove items; just let them expire on their own.");
	    return;
	}

	&::notice($who, "ok, deleted '$what' from \002$chan\002...");
	delete $::news{$chan}{$what};
    } else {
	&::notice($who, "error: not found $what in news for $chan.");
    }
}

sub list {
    if (!scalar keys %{ $::news{$chan} }) {
	&::notice($who, "No news for \002$chan\002.");
	return;
    }

    if (&::IsChanConf('newsKeepRead') > 0) {
	my $x = $::newsuser{$chan}{$who};

	if (defined $x and ($x == 0 or $x == -1)) {
	    &::DEBUG("news: not updating time for $who.");
	} else {
	    if (!scalar keys %{ $::news{$chan} }) {
		&::DEBUG("news: should not add $chan/$who to cache!");
	    }

	    $::newsuser{$chan}{$who} = time();
	}
    }

    # &notice() breaks OPN :( - using msg() instead!
    my $count = scalar keys %{ $::news{$chan} };
    &::msg($who, "|==== News for \002$chan\002: ($count items)");
    my $newest	= 0;
    my $expire	= 0;
    my $eno	= 0;
    foreach (keys %{ $::news{$chan} }) {
	my $t	= $::news{$chan}{$_}{Time};
	my $e	= $::news{$chan}{$_}{Expire};
	$newest = $t if ($t > $newest);
	if ($e > 1 and $e < $expire) {
	    $expire	= $e;
	    &::DEBUG("before newsS2N($_)");
	    $eno	= &newsS2N($_);
	    &::DEBUG("after newsS2N($_) == $eno");
	}
    }
    my $timestr = &::Time2String(time() - $newest);
    &::msg($who, "|= Last updated $timestr ago.");
    &::msg($who, " \037Num\037  \037Item ".(' 'x40)." \037");

#    &::DEBUG("news: list: expire = $expire");
#    &::DEBUG("news: list: eno    = $eno");

    my $i = 1;
    foreach ( &getNewsAll() ) {
	my $subtopic	= $_;
	my $setby	= $::news{$chan}{$subtopic}{Author};
	my $chr		= (exists $::News{$chan}{$subtopic}{Text}) ? '' : '*';

	if (!defined $subtopic) {
	    &::DEBUG("news: warn: subtopic == undef.");
	    next;
	}

	# TODO: show request stats aswell.
	&::msg($who, sprintf("\002[\002%2d\002]\002%s %s",
				$i, $chr, $subtopic));
	$i++;
    }

    my $z = $::newsuser{$who};
    if (defined $z) {
	&::DEBUG("cache $who: $z");
    } else {
	&::DEBUG("cache: $who doesn't have newscache set.");
    }

    &::msg($who, "|= End of News.");
    &::msg($who, "use 'news read <#>' or 'news read <keyword>'");
}

sub read {
    my($str) = @_;

    if (!defined $chan or !defined $str or $str =~ /^\s*$/) {
	&::help('news read');
	return;
    }

    if (!scalar keys %{ $::news{$chan} }) {
	&::notice($who, "No news for \002$chan\002.");
	return;
    }

    my $item	= &getNewsItem($str);
    if (!defined $item or !scalar keys %{ $::news{$chan}{$item} }) {
	# TODO: numerical check.
	if ($str =~ /^(\d+)[-, ](\d+)$/ or
	    $str =~ /^-(\d+)$/ or
	    $str =~ /^(\d+)-$/ or 0
	) {
	    &::notice($who, "We don't support multiple requests of news items yet.  Sorry.");
	    return;
	}

	&::notice($who, "No news item called '$str'");
	return;
    }

    if (!exists $::news{$chan}{$item}{Text}) {
	&::notice($who, 'Someone forgot to add info to this news item');
	return;
    }

    my $t	= gmtime( $::news{$chan}{$item}{Time} );
    my $a	= $::news{$chan}{$item}{Author};
    my $text	= $::news{$chan}{$item}{Text};
    my $num	= &newsS2N($item);
    my $rwho	= $::news{$chan}{$item}{Request_By} || $::who;
    my $rcount	= $::news{$chan}{$item}{Request_Count} || 0;

    if (length $text < $::param{maxKeySize}) {
	&::VERB("NEWS: Possible news->factoid redirection.",2);
	my $f	= &::getFactoid($text);

	if (defined $f) {
	    &::VERB("NEWS: ok, $text is factoid redirection.",2);
	    $f =~ s/^<REPLY>\s*//i;	# anything else?
	    $text = $f;
	}
    }

    $_ = $::news{$chan}{$item}{'Expire'};
    my $e;
    if ($_) {
	$e = sprintf("\037%s\037  [%s from now]",
		scalar(gmtime($_)),
		&::Time2String($_ - time())
	);
    }

    &::notice($who, "+- News \002$chan\002 #$num: $item");
    &::notice($who, "| Added by $a at \037$t\037");
    &::notice($who, "| Expire: $e") if (defined $e);
    &::notice($who, $text);
    &::notice($who, "| Requested \002$rcount\002 times, last by \002$rwho\002") if ($rcount and $rwho);

    $::news{$chan}{$item}{'Request_By'}   = $::who;
    $::news{$chan}{$item}{'Request_Time'} = time();
    $::news{$chan}{$item}{'Request_Count'}++;
}

sub mod {
    my($item, $str) = split /\s+/, $_[0], 2;

    if (!defined $item or $item eq '' or $str =~ /^\s*$/) {
	&::help('news mod');
	return;
    }

    my $news = &getNewsItem($item);

    if (!defined $news) {
	&::DEBUG("news: error: mod: news == undefined.");
	return;
    }
    my $nnews = $::news{$chan}{$news}{Text};
    my $mod_news  = $news;
    my $mod_nnews = $nnews;

    # SAR patch. mu++
    if ($str =~ m|^\s*s([/,#\|])(.+?)\1(.*?)\1([a-z]*);?\s*$|) {
	my ($delim, $op, $np, $flags) = ($1,$2,$3,$4);

	if ($flags !~ /^(g)?$/) {
	    &::notice($who, "error: Invalid flags to regex.");
	    return;
	}

	### TODO: use m### to make code safe!
	# TODO: make code safer.
	my $done = 0;
	# TODO: use eval to deal with flags easily.
	if ($flags eq '') {
	    $done++ if (!$done and $mod_news  =~ s/\Q$op\E/$np/);
	    $done++ if (!$done and $mod_nnews =~ s/\Q$op\E/$np/);
	} elsif ($flags eq 'g') {
	    $done++ if ($mod_news  =~ s/\Q$op\E/$np/g);
	    $done++ if ($mod_nnews =~ s/\Q$op\E/$np/g);
	}

	if (!$done) {
	    &::notice($who, "warning: regex not found in news.");
	    return;
	}

	if ($mod_news ne $news) { # news item.
	    if (exists $::news{$chan}{$mod_news}) {
		&::notice($who, "item '$mod_news' already exists.");
		return;
	    }

	    &::notice($who, "Moving item '$news' to '$mod_news' with SAR s/$op/$np/.");
	    foreach (keys %{ $::news{$chan}{$news} }) {
		$::news{$chan}{$mod_news}{$_} = $::news{$chan}{$news}{$_};
		delete $::news{$chan}{$news}{$_};
	    }
	    # needed?
	    delete $::news{$chan}{$news};
	}

	if ($mod_nnews ne $nnews) { # news Text/Description.
	    &::notice($who, "Changing text for '$news' SAR s/$op/$np/.");
	    if ($mod_news ne $news) {
		$::news{$chan}{$mod_news}{Text} = $mod_nnews;
	    } else {
		$::news{$chan}{$news}{Text}	= $mod_nnews;
	    }
	}

	return;
    } else {
	&::notice($who, "error: that regex failed ;(");
	return;
    }

    &::notice($who, "error: Invalid regex. Try s/1/2/, s#3#4#...");
}

sub set {
    my($args) = @_;
    my($item, $what, $value);

    if (!defined $args) {
	&::DEBUG("news: set: args == NULL.");
	return;
    }

    $item = $1 if ($args =~ s/^(\S+)\s*//);
    $what = $1 if ($args =~ s/^(\S+)\s*//);
    $value = $args;

    if ($item eq '') {
	&::help('news set');
	return;
    }

    my $news = &getNewsItem($item);

    if (!defined $news) {
	&::notice($who, "Could not find item '$item' substring or # in news list.");
	return;
    }

    # list all values for chan.
    if (!defined $what or $what =~ /^\s*$/) {
	&::msg($who, "set: you didn't fill me on the arguments! (what and values)");
	return;
    }

    my $ok = 0;
    my @elements = ('Expire','Text');
    foreach (@elements) {
	next unless ($what =~ /^$_$/i);
	$what = $_;
	$ok++;
	last;
    }

    if (!$ok) {
	&::notice($who, "Invalid set.  Try: @elements");
	return;
    }

    # show (read) what.
    if (!defined $value or $value =~ /^\s*$/) {
	&::msg($who, "set: you didn't fill me on the arguments! (value)");
	return;
    }

    if (!exists $::news{$chan}{$news}) {
	&::notice($who, "news '$news' does not exist");
	return;
    }

    if ($what eq 'Expire') {
	# TODO: use do_set().

	my $time = 0;
	my $plus = ($value =~ s/^\+//g);
	while ($value =~ s/^(\d+)(\S*)\s*//) {
	    my($int,$unit) = ($1,$2);
	    $time += $int	if ($unit =~ /^s(ecs?)?$/i);
	    $time += $int*60	if ($unit =~ /^m(in(utes?)?)?$/i);
	    $time += $int*60*60 if ($unit =~ /^h(ours?)?$/i);
	    $time += $int*60*60*24 if (!$unit or $unit =~ /^d(ays?)?$/i);
	    $time += $int*60*60*24*7 if ($unit =~ /^w(eeks?)?$/i);
	    $time += $int*60*60*24*30 if ($unit =~ /^mon(th)?$/i);
	}

	if ($value =~ s/^never$//i) {
	    # never.
	    $time = -1;
	} elsif ($plus) {
	    # from now.
	    $time += time();
	} else {
	    # from creation of item.
	    $time += $::news{$chan}{$news}{Time};
	}

	if (!$time or ($value and $value !~ /^never$/i)) {
	    &::DEBUG("news: set: Expire... need to parse.");
	    &::msg($who, "hrm... couldn't parse that.");
	    return;
	}

	if ($time == -1) {
	    &::notice($who, "Set never expire for \002$item\002." );
	} elsif ($time < -1) {
	    &::DEBUG("news: time should never be negative ($time).");
	    return;
	} else {
	    &::notice($who, "Set expire for \002$item\002, to ".
		gmtime($time) ." [".&::Time2String($time - time())."]" );

	    if (time() > $time) {
		&::DEBUG("news: hrm... time() > $time, should expire.");
	    }
	}


	$::news{$chan}{$news}{Expire} = $time;

	return;
    }

    my $auth = 0;
#    &::DEBUG("news: who => '$who'");
    my $author = $::news{$chan}{$news}{Author};
    $auth++ if ($::who eq $author);
    $auth++ if (&::IsFlag('o'));
    if (!defined $author) {
	&::DEBUG("news: news{$chan}{$news}{Author} is not defined! auth'd anyway");
	$::news{$chan}{$news}{Author} = $::who;
	$author = $::who;
	$auth++;
    }

    if (!$auth) {
	# TODO: show when it'll expire.
	&::notice($who, "Sorry, you cannot set items. (author $author owns it)");
	return;
    }

    # TODO: clean this up.
    my $old = $::news{$chan}{$news}{$what};
    if (defined $old) {
	&::DEBUG("news: old => $old.");
    }
    $::news{$chan}{$news}{$what} = $value;
    &::notice($who, "Setting [$chan]/{$news}/<$what> to '$value'.");
}

sub latest {
    my ($tchan, $flag) = @_;

    # hack hack hack.  fix later.
    $chan = $tchan;
    $who  = $::who;

    # TODO: if chan = undefined, guess.
#    if (!exists $::news{$chan}) {
    if (!exists $::channels{$chan}) {
	&::notice($who, "invalid chan $chan") if ($flag);
	return;
    }

    my $t = $::newsuser{$chan}{$who};
#    if (defined $t) {
#	&::DEBUG("newsuser: $chan/$who == $t");
#    } else {
#	&::DEBUG("newsuser: $chan/$who == undefined");
#    }

    if (defined $t and ($t == 0 or $t == -1)) {
	if ($flag) {
	    &::notice($who, "if you want to read news, try \002/msg $::ident news $chan\002 or \002/msg $::ident news $chan notify\002");
	} else {
	    &::DEBUG("news: not displaying any new news for $who");
	    return;
	}
    }

    $::chan	= $chan;
    return if (&::IsChanConf('newsNotifyAll') <= 0);

    # I don't understand this code ;)
    $t = 1 if (!defined $t);

    if (!defined $t) {
#	&::msg($who, "News is disabled for $chan");
	&::DEBUG("news: $chan: something went really wrong.");
	return;
    }

    my @new;
    foreach (keys %{ $::news{$chan} }) {
	next if (!defined $t);
	next if ($t > $::news{$chan}{$_}{Time});

	# don't list new items if they don't have Text.
	if (!exists $::news{$chan}{$_}{Text}) {
	    if (time() - $::news{$chan}{$_}{Time} > 60*60*24*3) {
		&::DEBUG("deleting news{$chan}{$_} because it was too old and had no text info.");
		delete $::news{$chan}{$_};
	    }

	    next;
	}

	push(@new, $_);
    }

    # !scalar @new, $flag
    if (!scalar @new and $flag) {
	&::notice($who, "no new news for $chan for $who.");
	# valid to set this?
	$::newsuser{$chan}{$who} = time();
	return;
    }

    # scalar @new, !$flag
    my $unread	= scalar @new;
    my $total	= scalar keys %{ $::news{$chan} };
    if (!$flag && &::IsChanConf('newsTellUnread') <= 0) {
	return;
    }

    if (!$flag) {
	return unless ($unread);

	# just a temporary measure not to flood ourself off the
	# network with news until we get global notice() and msg()
	# throttling.
	if (time() - ($::cache{newsTime} || 0) < 5) {
	    &::status("news: not displaying latest notice to $who/$chan.");
	    return;
	}

	$::cache{newsTime} = time();
	my $reply = "There are unread news in $chan ($unread unread, $total total). /msg $::ident news $::chan latest";
	$reply	 .= "  If you don't want further news notification, /msg $::ident news unnotify" if ($unread == $total);
	&::notice($who, $reply);

	return;
    }

    # scalar @new, $flag
    if (scalar @new) {
	&::notice($who, "+==== New news for \002$chan\002 ($unread new; $total total):");

	my $t = $::newsuser{$chan}{$who};
	if (defined $t and $t > 1) {
	    my $timestr = &::Time2String( time() - $t );
	    &::notice($who, "|= Last time read $timestr ago");
	}

	my $i;
	my @sorted;
	foreach (@new) {
	    $i   = &newsS2N($_);
	    $sorted[$i] = $_;
	}

	for ($i=0; $i<=scalar(@sorted); $i++) {
	    my $news = $sorted[$i];
	    next unless (defined $news);

#	    my $age = time() - $::news{$chan}{$news}{Time};
	    my $msg = sprintf("\002[\002%2d\002]\002 %s", $i, $news);
###			$i, $_, &::Time2String($age)
	    $::conn->schedule(int((2+$i)/2), sub {
		&::notice($who, $msg);
	    } );
	}

	# TODO: implement throttling via schedule into &notice() / &msg().
	$::conn->schedule(int((2+$i)/2), sub {
	    &::notice($who, "|= to read, do \002news $chan read <#>\002 or \002news $chan read <keyword>\002");
	} );

	# lame hack to prevent dupes if we just ignore it.
	my $x = $::newsuser{$chan}{$who};
	if (defined $x and ($x == 0 or $x == -1)) {
	    &::DEBUG("news: not updating time for $who. (2)");
	} else {
	    $::newsuser{$chan}{$who} = time();
	}
    }
}

###
### helpers...
###

sub getNewsAll {
    my %time;
    foreach (keys %{ $::news{$chan} }) {
	$time{ $::news{$chan}{$_}{Time} } = $_;
    }

    my @items;
    foreach (sort { $a <=> $b } keys %time) {
	push(@items, $time{$_});
    }

    return @items;
}

sub newsS2N {
    my($what)	= @_;
    my $item	= 0;
    my @items;
    my $no;

    my %time;
    foreach (keys %{ $::news{$chan} }) {
	my $t = $::news{$chan}{$_}{Time};

	if (!defined $t or $t !~ /^\d+$/) {
	    &::DEBUG("news: warn: t is undefined for news{$chan}{$_}{Time}; removing item.");
	    delete $::news{$chan}{$_};
	    next;
	}

	$time{$t} = $_;
    }

    foreach (sort { $a <=> $b } keys %time) {
	$item++;
	return $item if ($time{$_} eq $what);
    }

    &::DEBUG("newsS2N($what): failed...");
}

sub getNewsItem {
    my($what)	= @_;
    my $item	= 0;

    $what =~ s/^\#//;	# '#1' for example.

    my %time;
    foreach (keys %{ $::news{$chan} }) {
	my $t = $::news{$chan}{$_}{Time};

	if (!defined $t or $t !~ /^\d+$/) {
	    &::DEBUG("news: warn: t is undefined for news{$chan}{$_}{Time}; removing item.");
	    delete $::news{$chan}{$_};
	    next;
	}

	$time{$t} = $_;
    }

    # number to string resolution.
    if ($what =~ /^\d+$/) {
	foreach (sort { $a <=> $b } keys %time) {
	    $item++;
	    return $time{$_} if ($item == $what);
	}

    } else {
	# partial string to full string resolution
	# in some cases, string->number resolution.

	my @items;
	my $no;
	foreach (sort { $a <=> $b } keys %time) {
	    $item++;
#	    $no = $item if ($time{$_} eq $what);
##	    if ($time{$_} eq $what) {
##		$no = $item;
##		next;
##	    }

	    push(@items, $time{$_}) if ($time{$_} =~ /\Q$what\E/i);
	}

##	if (defined $no and !@items) {
##	    &::DEBUG("news: string->number resolution: $what->$no.");
##	    return $no;
##	}

	if (scalar @items > 1) {
	    &::DEBUG("news: Multiple matches, not guessing.");
	    &::notice($who, "Multiple matches, not guessing.");
	    return;
	}

	if (@items) {
#	    &::DEBUG("news: gNI: part_string->full_string: $what->$items[0]");
	    return $items[0];
	} else {
	    &::DEBUG("news: gNI: No match for '$what'");
	    return;
	}
    }

    &::ERROR("news: gNI: should not happen (what = $what)");
    return;
}

sub do_set {
    my($what,$value) = @_;

    if (!defined $chan) {
	&::DEBUG("news: do_set: chan not defined.");
	return;
    }

    if (!defined $what or $what =~ /^\s*$/) {
	&::DEBUG("news: what $what is not defined.");
	return;
    }

    if (!defined $value or $value =~ /^\s*$/) {
	&::DEBUG("news: value $value is not defined.");
	return;
    }

    &::TODO("news: do_set:");
}

sub stats {
    &::DEBUG("News: stats called.");
    &::msg($who, "check my logs/console.");
    my($i,$j) = (0,0);

    # total request count.
    foreach $chan (keys %::news) {
	foreach (keys %{ $::news{$chan} }) {
	    $i += $::news{$chan}{$_}{Request_Count};
	}
    }
    &::DEBUG("news: stats: total request count => $i");
    $i = 0;

    # total user cached.
    foreach $chan (keys %::newsuser) {
	$i += $::newsuser{$chan}{$_};
    }
    &::DEBUG("news: stats: total user cache => $i");
    $i = 0;

    # average latest time read.
    my $t = time();
    foreach $chan (keys %::newsuser) {
	$i += $t - $::newsuser{$chan}{$_};
	&::DEBUG(" i = $i");
	$j++;
    }
    &::DEBUG("news: stats: average latest time read: total time: $i");
    &::DEBUG("news: ... count: $j");
    &::DEBUG("news:   average: ".sprintf("%.02f", $i/($j||1))." sec/user");
    $i = $j = 0;
}

sub AUTOLOAD { &::AUTOLOAD(@_); }

1;

# vim:ts=4:sw=4:expandtab:tw=80