[usenet/newsstats.git] / gatherstats.pl

#! /usr/bin/perl -W
#
# gatherstats.pl
#
# This script will gather statistical information from a database
# containing headers and other information from a INN feed.
# 
# It is part of the NewsStats package.
#
# Copyright (c) 2010-2012 Thomas Hochstein <thh@inter.net>
#
# It can be redistributed and/or modified under the same terms under 
# which Perl itself is published.

BEGIN {
  our $VERSION = "0.01";
  use File::Basename;
  push(@INC, dirname($0));
}
use strict;

use NewsStats qw(:DEFAULT :TimePeriods ListNewsgroups ReadGroupList);

use DBI;
use Getopt::Long qw(GetOptions);
Getopt::Long::config ('bundling');

################################# Definitions ##################################

# define types of information that can be gathered
# all / groups (/ clients / hosts)
my %LegalStats;
@LegalStats{('all','groups')} = ();

################################# Main program #################################

### read commandline options
my ($OptCheckgroupsFile,$OptClientsDB,$OptDebug,$OptGroupsDB,$OptTLH,
    $OptHostsDB,$OptMonth,$OptRawDB,$OptStatsType,$OptTest);
GetOptions ('c|checkgroups=s' => \$OptCheckgroupsFile,
            'clientsdb=s'     => \$OptClientsDB,
            'd|debug!'        => \$OptDebug,
            'groupsdb=s'      => \$OptGroupsDB,
            'hierarchy=s'     => \$OptTLH,
            'hostsdb=s'       => \$OptHostsDB,
            'm|month=s'       => \$OptMonth,
            'rawdb=s'         => \$OptRawDB,
            's|stats=s'       => \$OptStatsType,
            't|test!'         => \$OptTest,
            'h|help'          => \&ShowPOD,
            'V|version'       => \&ShowVersion) or exit 1;

### read configuration
my %Conf = %{ReadConfig($HomePath.'/newsstats.conf')};

### override configuration via commandline options
my %ConfOverride;
$ConfOverride{'DBTableRaw'}   = $OptRawDB if $OptRawDB;
$ConfOverride{'DBTableGrps'}  = $OptGroupsDB if $OptGroupsDB;
$ConfOverride{'DBTableClnts'} = $OptClientsDB if $OptClientsDB;
$ConfOverride{'DBTableHosts'} = $OptHostsDB if $OptHostsDB;
$ConfOverride{'TLH'} = $OptTLH if $OptTLH;
&OverrideConfig(\%Conf,\%ConfOverride);

### get type of information to gather, defaulting to 'all'
$OptStatsType = 'all' if !$OptStatsType;
&Bleat(2, sprintf("Unknown type '%s'!", $OptStatsType))
  if !exists($LegalStats{$OptStatsType});

### get time period from --month
# get verbal description of time period, drop SQL code
my ($Period) = &GetTimePeriod($OptMonth);
&Bleat(2,"--month option has an invalid format - please use 'YYYY-MM' or ".
         "'YYYY-MM:YYYY-MM'!") if (!$Period or $Period eq 'all time');

### reformat $Conf{'TLH'}
my $TLH;
if ($Conf{'TLH'}) {
  # $Conf{'TLH'} is parsed as an array by Config::Auto;
  # make a flat list again, separated by :
  if (ref($TLH) eq 'ARRAY') {
    $TLH = join(':',@{$Conf{'TLH'}});
  } else {
    $TLH  = $Conf{'TLH'};
  }
  # strip whitespace
  $TLH =~ s/\s//g;
  # check for illegal characters
  &Bleat(2,'Config error - illegal characters in TLH definition!')
    if ($TLH !~ /^[a-zA-Z0-9:]+$/);
  if ($TLH =~ /:/) {
    # reformat $TLH from a:b to (a)|(b),
    # e.g. replace '.' by '|'
    $TLH =~ s/:/)|(/g;
    $TLH = '(' . $TLH . ')';
  };
};

# read list of newsgroups from --checkgroups
# into a hash
my %ValidGroups = %{ReadGroupList($OptCheckgroupsFile)} if $OptCheckgroupsFile;

### init database
my $DBHandle = InitDB(\%Conf,1);

### get data for each month
&Bleat(1,'Test mode. Database is not updated.') if $OptTest;
foreach my $Month (&ListMonth($Period)) {

  print "---------- $Month ----------\n" if $OptDebug;

  if ($OptStatsType eq 'all' or $OptStatsType eq 'groups') {
    ### ----------------------------------------------
    ### get groups data (number of postings per group)
    # get groups data from raw table for given month
    my $DBQuery = $DBHandle->prepare(sprintf("SELECT newsgroups FROM %s.%s ".
                                             "WHERE day LIKE ? AND NOT disregard",
                                             $Conf{'DBDatabase'},
                                             $Conf{'DBTableRaw'}));
    $DBQuery->execute($Month.'-%')
      or &Bleat(2,sprintf("Can't get groups data for %s from %s.%s: ".
                          "$DBI::errstr\n",$Month,
                          $Conf{'DBDatabase'},$Conf{'DBTableRaw'}));

    # count postings per group
    my %Postings;
    while (($_) = $DBQuery->fetchrow_array) {
      # get list oft newsgroups and hierarchies from Newsgroups:
      my %Newsgroups = ListNewsgroups($_,$TLH,
                                      $OptCheckgroupsFile ? \%ValidGroups : '');
      # count each newsgroup and hierarchy once
      foreach (sort keys %Newsgroups) {
        $Postings{$_}++;
      };
    };

    # add valid but empty groups if --checkgroups is set
    if (%ValidGroups) {
      foreach (sort keys %ValidGroups) {
        if (!defined($Postings{$_})) {
          $Postings{$_} = 0 ;
          warn (sprintf("ADDED: %s as empty group\n",$_));
        }
      };
    };

    # delete old data for that month
    if (!$OptTest) {
      $DBQuery = $DBHandle->do(sprintf("DELETE FROM %s.%s WHERE month = ?",
                                       $Conf{'DBDatabase'},$Conf{'DBTableGrps'}),
                                       undef,$Month)
        or &Bleat(2,sprintf("Can't delete old groups data for %s from %s.%s: ".
                            "$DBI::errstr\n",$Month,
                            $Conf{'DBDatabase'},$Conf{'DBTableGrps'}));
    };

    print "----- GroupStats -----\n" if $OptDebug;
    foreach my $Newsgroup (sort keys %Postings) {
      print "$Newsgroup => $Postings{$Newsgroup}\n" if $OptDebug;
      if (!$OptTest) {
        # write to database
        $DBQuery = $DBHandle->prepare(sprintf("INSERT INTO %s.%s ".
                                              "(month,newsgroup,postings) ".
                                              "VALUES (?, ?, ?)",
                                              $Conf{'DBDatabase'},
                                              $Conf{'DBTableGrps'}));
        $DBQuery->execute($Month, $Newsgroup, $Postings{$Newsgroup})
          or &Bleat(2,sprintf("Can't write groups data for %s/%s to %s.%s: ".
                              "$DBI::errstr\n",$Month,$Newsgroup,
                              $Conf{'DBDatabase'},$Conf{'DBTableGrps'}));
        $DBQuery->finish;
      };
    };
  } else {
    # other types of information go here - later on
  };
};

### close handles
$DBHandle->disconnect;

__END__

################################ Documentation #################################

=head1 NAME

gatherstats - process statistical data from a raw source

=head1 SYNOPSIS

B<gatherstats> [B<-Vhdt>] [B<-m> I<YYYY-MM> | I<YYYY-MM:YYYY-MM>] [B<-s> I<stats] [B<-c> I<checkgroups file>]] [B<--hierarchy> I<TLH>] [B<--rawdb> I<database table>] [B<-groupsdb> I<database table>] [B<--clientsdb> I<database table>] [B<--hostsdb> I<database table>]

=head1 REQUIREMENTS

See L<doc/README>.

=head1 DESCRIPTION

This script will extract and process statistical information from a
database table which is fed from F<feedlog.pl> for a given time period
and write its results to (an)other database table(s). Entries marked
with I<'disregard'> in the database will be ignored; currently, you
have to set this flag yourself, using your database management tools.
You can exclude erroneous entries that way (e.g. automatic reposts
(think of cancels flood and resurrectors); spam; ...).

The time period to act on defaults to last month; you can assign
another time period or a single month via the B<--month> option (see
below).

By default B<gatherstats> will process all types of information; you
can change that using the B<--stats> option and assigning the type of
information to process. Currently that doesn't matter yet as only
processing of the number of postings per group per month is
implemented anyway.

Possible information types include:

=over 3

=item B<groups> (postings per group per month)

B<gatherstats> will examine Newsgroups: headers. Crosspostings will be
counted for each single group they appear in. Groups not in I<TLH>
will be ignored.

B<gatherstats> will also add up the number of postings for each
hierarchy level, but only count each posting once. A posting to
de.alt.test will be counted for de.alt.test, de.alt.ALL and de.ALL,
respectively. A crossposting to de.alt.test and de.alt.admin, on the
other hand, will be counted for de.alt.test and de.alt.admin each, but
only once for de.alt.ALL and de.ALL.

Data is written to I<DBTableGrps> (see L<doc/INSTALL>); you can
override that default through the B<--groupsdb> option.

=back

=head2 Configuration

B<gatherstats> will read its configuration from F<newsstats.conf>
which should be present in the same directory via Config::Auto.

See L<doc/INSTALL> for an overview of possible configuration options.

You can override configuration options via the B<--hierarchy>,
B<--rawdb>, B<--groupsdb>, B<--clientsdb> and B<--hostsdb> options,
respectively.

=head1 OPTIONS

=over 3

=item B<-V>, B<--version>

Print out version and copyright information and exit.

=item B<-h>, B<--help>

Print this man page and exit.

=item B<-d>, B<--debug>

Output debugging information to STDOUT while processing (number of
postings per group).

=item B<-t>, B<--test>

Do not write results to database. You should use B<--debug> in
conjunction with B<--test> ... everything else seems a bit pointless.

=item B<-m>, B<--month> I<YYYY-MM[:YYYY-MM]>

Set processing period to a single month in YYYY-MM format or to a time
period between two month in YYYY-MM:YYYY-MM format (two month, separated
by a colon). 


=item B<-s>, B<--stats> I<type>

Set processing type to one of I<all> and I<groups>. Defaults to all
(and is currently rather pointless as only I<groups> has been
implemented).

=item B<-c>, B<--checkgroups> I<filename>

Check each group against a list of valid newsgroups read from
I<filename>, one group on each line and ignoring everything after the
first whitespace (so you can use a file in checkgroups format or (part
of) your INN active file).

Newsgroups not found in I<filename> will be dropped (and logged to
STDERR), and newsgroups found in I<filename> but having no postings
will be added with a count of 0 (and logged to STDERR).

=item B<--hierarchy> I<TLH> (newsgroup hierarchy)

Override I<TLH> from F<newsstats.conf>.

=item B<--rawdb> I<table> (raw data table)

Override I<DBTableRaw> from F<newsstats.conf>.

=item B<--groupsdb> I<table> (postings per group table)

Override I<DBTableGrps> from F<newsstats.conf>.

=item B<--clientsdb> I<table> (client data table)

Override I<DBTableClnts> from F<newsstats.conf>.

=item B<--hostsdb> I<table> (host data table)

Override I<DBTableHosts> from F<newsstats.conf>.

=back

=head1 INSTALLATION

See L<doc/INSTALL>.

=head1 EXAMPLES

Process all types of information for lasth month:

    gatherstats

Do a dry run, showing results of processing:

    gatherstats --debug --test

Process all types of information for January of 2010:

    gatherstats --month 2010-01

Process only number of postings for the year of 2010,
checking against checkgroups-2010.txt:

    gatherstats -m 2010-01:2010-12 -s groups -c checkgroups-2010.txt

=head1 FILES

=over 4

=item F<gatherstats.pl>

The script itself.

=item F<NewsStats.pm>

Library functions for the NewsStats package.

=item F<newsstats.conf>

Runtime configuration file.

=back

=head1 BUGS

Please report any bugs or feature requests to the author or use the
bug tracker at L<http://bugs.th-h.de/>!

=head1 SEE ALSO

=over 2

=item -

L<doc/README>

=item -

L<doc/INSTALL>

=back

This script is part of the B<NewsStats> package.

=head1 AUTHOR

Thomas Hochstein <thh@inter.net>

=head1 COPYRIGHT AND LICENSE

Copyright (c) 2010-2012 Thomas Hochstein <thh@inter.net>

This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.

=cut
Commit	Line	Data
2832c235 TH	1	#! /usr/bin/perl -W
	2	#
	3	# gatherstats.pl
	4	#
	5	# This script will gather statistical information from a database
	6	# containing headers and other information from a INN feed.
	7	#
	8	# It is part of the NewsStats package.
	9	#
880c3eb2	10	# Copyright (c) 2010-2012 Thomas Hochstein <thh@inter.net>
2832c235 TH	11	#
	12	# It can be redistributed and/or modified under the same terms under
	13	# which Perl itself is published.
	14
	15	BEGIN {
	16	our $VERSION = "0.01";
	17	use File::Basename;
	18	push(@INC, dirname($0));
	19	}
	20	use strict;
	21
ad609792	22	use NewsStats qw(:DEFAULT :TimePeriods ListNewsgroups ReadGroupList);
2832c235 TH	23
2832c235 TH	24	use DBI;
880c3eb2 TH	25	use Getopt::Long qw(GetOptions);
880c3eb2 TH	26	Getopt::Long::config ('bundling');
2832c235 TH	27
	28	################################# Definitions ##################################
	29
	30	# define types of information that can be gathered
	31	# all / groups (/ clients / hosts)
880c3eb2 TH	32	my %LegalStats;
880c3eb2 TH	33	@LegalStats{('all','groups')} = ();
2832c235 TH	34
	35	################################# Main program #################################
	36
	37	### read commandline options
880c3eb2 TH	38	my ($OptCheckgroupsFile,$OptClientsDB,$OptDebug,$OptGroupsDB,$OptTLH,
	39	$OptHostsDB,$OptMonth,$OptRawDB,$OptStatsType,$OptTest);
	40	GetOptions ('c\|checkgroups=s' => \$OptCheckgroupsFile,
	41	'clientsdb=s' => \$OptClientsDB,
	42	'd\|debug!' => \$OptDebug,
	43	'groupsdb=s' => \$OptGroupsDB,
	44	'hierarchy=s' => \$OptTLH,
	45	'hostsdb=s' => \$OptHostsDB,
	46	'm\|month=s' => \$OptMonth,
	47	'rawdb=s' => \$OptRawDB,
	48	's\|stats=s' => \$OptStatsType,
	49	't\|test!' => \$OptTest,
	50	'h\|help' => \&ShowPOD,
	51	'V\|version' => \&ShowVersion) or exit 1;
2832c235 TH	52
2832c235 TH	53	### read configuration
880c3eb2	54	my %Conf = %{ReadConfig($HomePath.'/newsstats.conf')};
2832c235 TH	55
	56	### override configuration via commandline options
	57	my %ConfOverride;
880c3eb2 TH	58	$ConfOverride{'DBTableRaw'} = $OptRawDB if $OptRawDB;
	59	$ConfOverride{'DBTableGrps'} = $OptGroupsDB if $OptGroupsDB;
	60	$ConfOverride{'DBTableClnts'} = $OptClientsDB if $OptClientsDB;
	61	$ConfOverride{'DBTableHosts'} = $OptHostsDB if $OptHostsDB;
	62	$ConfOverride{'TLH'} = $OptTLH if $OptTLH;
2832c235 TH	63	&OverrideConfig(\%Conf,\%ConfOverride);
	64
	65	### get type of information to gather, defaulting to 'all'
880c3eb2 TH	66	$OptStatsType = 'all' if !$OptStatsType;
	67	&Bleat(2, sprintf("Unknown type '%s'!", $OptStatsType))
	68	if !exists($LegalStats{$OptStatsType});
2832c235	69
880c3eb2 TH	70	### get time period from --month
	71	# get verbal description of time period, drop SQL code
	72	my ($Period) = &GetTimePeriod($OptMonth);
	73	&Bleat(2,"--month option has an invalid format - please use 'YYYY-MM' or ".
	74	"'YYYY-MM:YYYY-MM'!") if (!$Period or $Period eq 'all time');
2832c235	75
17ffbeba TH	76	### reformat $Conf{'TLH'}
	77	my $TLH;
	78	if ($Conf{'TLH'}) {
	79	# $Conf{'TLH'} is parsed as an array by Config::Auto;
	80	# make a flat list again, separated by :
	81	if (ref($TLH) eq 'ARRAY') {
	82	$TLH = join(':',@{$Conf{'TLH'}});
	83	} else {
	84	$TLH = $Conf{'TLH'};
	85	}
	86	# strip whitespace
	87	$TLH =~ s/\s//g;
	88	# check for illegal characters
880c3eb2 TH	89	&Bleat(2,'Config error - illegal characters in TLH definition!')
880c3eb2 TH	90	if ($TLH !~ /^[a-zA-Z0-9:]+$/);
17ffbeba	91	if ($TLH =~ /:/) {
880c3eb2 TH	92	# reformat $TLH from a:b to (a)\|(b),
880c3eb2 TH	93	# e.g. replace '.' by '\|'
17ffbeba TH	94	$TLH =~ s/:/)\|(/g;
	95	$TLH = '(' . $TLH . ')';
	96	};
	97	};
	98
880c3eb2 TH	99	# read list of newsgroups from --checkgroups
	100	# into a hash
	101	my %ValidGroups = %{ReadGroupList($OptCheckgroupsFile)} if $OptCheckgroupsFile;
ad609792	102
2832c235 TH	103	### init database
	104	my $DBHandle = InitDB(\%Conf,1);
	105
	106	### get data for each month
880c3eb2 TH	107	&Bleat(1,'Test mode. Database is not updated.') if $OptTest;
880c3eb2 TH	108	foreach my $Month (&ListMonth($Period)) {
2832c235	109
880c3eb2	110	print "---------- $Month ----------\n" if $OptDebug;
2832c235	111
880c3eb2	112	if ($OptStatsType eq 'all' or $OptStatsType eq 'groups') {
2832c235 TH	113	### ----------------------------------------------
	114	### get groups data (number of postings per group)
	115	# get groups data from raw table for given month
880c3eb2 TH	116	my $DBQuery = $DBHandle->prepare(sprintf("SELECT newsgroups FROM %s.%s ".
	117	"WHERE day LIKE ? AND NOT disregard",
	118	$Conf{'DBDatabase'},
	119	$Conf{'DBTableRaw'}));
	120	$DBQuery->execute($Month.'-%')
	121	or &Bleat(2,sprintf("Can't get groups data for %s from %s.%s: ".
	122	"$DBI::errstr\n",$Month,
	123	$Conf{'DBDatabase'},$Conf{'DBTableRaw'}));
2832c235 TH	124
	125	# count postings per group
	126	my %Postings;
2832c235 TH	127	while (($_) = $DBQuery->fetchrow_array) {
2832c235 TH	128	# get list oft newsgroups and hierarchies from Newsgroups:
880c3eb2 TH	129	my %Newsgroups = ListNewsgroups($_,$TLH,
880c3eb2 TH	130	$OptCheckgroupsFile ? \%ValidGroups : '');
2832c235 TH	131	# count each newsgroup and hierarchy once
2832c235 TH	132	foreach (sort keys %Newsgroups) {
2832c235 TH	133	$Postings{$_}++;
	134	};
	135	};
	136
880c3eb2	137	# add valid but empty groups if --checkgroups is set
ad609792 TH	138	if (%ValidGroups) {
	139	foreach (sort keys %ValidGroups) {
	140	if (!defined($Postings{$_})) {
	141	$Postings{$_} = 0 ;
	142	warn (sprintf("ADDED: %s as empty group\n",$_));
	143	}
	144	};
	145	};
	146
71f0178b	147	# delete old data for that month
880c3eb2 TH	148	if (!$OptTest) {
	149	$DBQuery = $DBHandle->do(sprintf("DELETE FROM %s.%s WHERE month = ?",
	150	$Conf{'DBDatabase'},$Conf{'DBTableGrps'}),
	151	undef,$Month)
	152	or &Bleat(2,sprintf("Can't delete old groups data for %s from %s.%s: ".
	153	"$DBI::errstr\n",$Month,
	154	$Conf{'DBDatabase'},$Conf{'DBTableGrps'}));
71f0178b TH	155	};
71f0178b TH	156
880c3eb2	157	print "----- GroupStats -----\n" if $OptDebug;
2832c235	158	foreach my $Newsgroup (sort keys %Postings) {
880c3eb2 TH	159	print "$Newsgroup => $Postings{$Newsgroup}\n" if $OptDebug;
880c3eb2 TH	160	if (!$OptTest) {
2832c235	161	# write to database
880c3eb2 TH	162	$DBQuery = $DBHandle->prepare(sprintf("INSERT INTO %s.%s ".
	163	"(month,newsgroup,postings) ".
	164	"VALUES (?, ?, ?)",
	165	$Conf{'DBDatabase'},
	166	$Conf{'DBTableGrps'}));
	167	$DBQuery->execute($Month, $Newsgroup, $Postings{$Newsgroup})
	168	or &Bleat(2,sprintf("Can't write groups data for %s/%s to %s.%s: ".
	169	"$DBI::errstr\n",$Month,$Newsgroup,
	170	$Conf{'DBDatabase'},$Conf{'DBTableGrps'}));
2832c235 TH	171	$DBQuery->finish;
	172	};
	173	};
	174	} else {
	175	# other types of information go here - later on
	176	};
	177	};
	178
	179	### close handles
	180	$DBHandle->disconnect;
	181
	182	__END__
	183
	184	################################ Documentation #################################
	185
	186	=head1 NAME
	187
	188	gatherstats - process statistical data from a raw source
	189
	190	=head1 SYNOPSIS
	191
880c3eb2	192	B<gatherstats> [B<-Vhdt>] [B<-m> I<YYYY-MM> \| I<YYYY-MM:YYYY-MM>] [B<-s> I<stats] [B<-c> I<checkgroups file>]] [B<--hierarchy> I<TLH>] [B<--rawdb> I<database table>] [B<-groupsdb> I<database table>] [B<--clientsdb> I<database table>] [B<--hostsdb> I<database table>]
2832c235 TH	193
	194	=head1 REQUIREMENTS
	195
880c3eb2	196	See L<doc/README>.
2832c235 TH	197
	198	=head1 DESCRIPTION
	199
	200	This script will extract and process statistical information from a
	201	database table which is fed from F<feedlog.pl> for a given time period
313610f6	202	and write its results to (an)other database table(s). Entries marked
880c3eb2 TH	203	with I<'disregard'> in the database will be ignored; currently, you
	204	have to set this flag yourself, using your database management tools.
	205	You can exclude erroneous entries that way (e.g. automatic reposts
	206	(think of cancels flood and resurrectors); spam; ...).
2832c235 TH	207
2832c235 TH	208	The time period to act on defaults to last month; you can assign
880c3eb2 TH	209	another time period or a single month via the B<--month> option (see
880c3eb2 TH	210	below).
2832c235 TH	211
2832c235 TH	212	By default B<gatherstats> will process all types of information; you
880c3eb2 TH	213	can change that using the B<--stats> option and assigning the type of
	214	information to process. Currently that doesn't matter yet as only
	215	processing of the number of postings per group per month is
	216	implemented anyway.
2832c235 TH	217
	218	Possible information types include:
	219
	220	=over 3
	221
	222	=item B<groups> (postings per group per month)
	223
	224	B<gatherstats> will examine Newsgroups: headers. Crosspostings will be
	225	counted for each single group they appear in. Groups not in I<TLH>
	226	will be ignored.
	227
	228	B<gatherstats> will also add up the number of postings for each
	229	hierarchy level, but only count each posting once. A posting to
	230	de.alt.test will be counted for de.alt.test, de.alt.ALL and de.ALL,
	231	respectively. A crossposting to de.alt.test and de.alt.admin, on the
	232	other hand, will be counted for de.alt.test and de.alt.admin each, but
	233	only once for de.alt.ALL and de.ALL.
	234
880c3eb2 TH	235	Data is written to I<DBTableGrps> (see L<doc/INSTALL>); you can
880c3eb2 TH	236	override that default through the B<--groupsdb> option.
2832c235 TH	237
	238	=back
	239
	240	=head2 Configuration
	241
880c3eb2	242	B<gatherstats> will read its configuration from F<newsstats.conf>
2832c235 TH	243	which should be present in the same directory via Config::Auto.
2832c235 TH	244
880c3eb2	245	See L<doc/INSTALL> for an overview of possible configuration options.
2832c235	246
880c3eb2 TH	247	You can override configuration options via the B<--hierarchy>,
	248	B<--rawdb>, B<--groupsdb>, B<--clientsdb> and B<--hostsdb> options,
	249	respectively.
2832c235 TH	250
	251	=head1 OPTIONS
	252
	253	=over 3
	254
880c3eb2	255	=item B<-V>, B<--version>
2832c235	256
880c3eb2	257	Print out version and copyright information and exit.
2832c235	258
880c3eb2	259	=item B<-h>, B<--help>
2832c235 TH	260
	261	Print this man page and exit.
	262
880c3eb2	263	=item B<-d>, B<--debug>
2832c235 TH	264
	265	Output debugging information to STDOUT while processing (number of
	266	postings per group).
	267
880c3eb2	268	=item B<-t>, B<--test>
2832c235	269
880c3eb2 TH	270	Do not write results to database. You should use B<--debug> in
880c3eb2 TH	271	conjunction with B<--test> ... everything else seems a bit pointless.
2832c235	272
880c3eb2	273	=item B<-m>, B<--month> I<YYYY-MM[:YYYY-MM]>
2832c235	274
880c3eb2 TH	275	Set processing period to a single month in YYYY-MM format or to a time
	276	period between two month in YYYY-MM:YYYY-MM format (two month, separated
	277	by a colon).
2832c235	278
2832c235	279
880c3eb2	280	=item B<-s>, B<--stats> I<type>
2832c235 TH	281
	282	Set processing type to one of I<all> and I<groups>. Defaults to all
	283	(and is currently rather pointless as only I<groups> has been
	284	implemented).
	285
880c3eb2	286	=item B<-c>, B<--checkgroups> I<filename>
ad609792 TH	287
	288	Check each group against a list of valid newsgroups read from
	289	I<filename>, one group on each line and ignoring everything after the
	290	first whitespace (so you can use a file in checkgroups format or (part
	291	of) your INN active file).
	292
	293	Newsgroups not found in I<filename> will be dropped (and logged to
	294	STDERR), and newsgroups found in I<filename> but having no postings
	295	will be added with a count of 0 (and logged to STDERR).
	296
880c3eb2	297	=item B<--hierarchy> I<TLH> (newsgroup hierarchy)
2832c235 TH	298
	299	Override I<TLH> from F<newsstats.conf>.
	300
880c3eb2	301	=item B<--rawdb> I<table> (raw data table)
2832c235 TH	302
	303	Override I<DBTableRaw> from F<newsstats.conf>.
	304
880c3eb2	305	=item B<--groupsdb> I<table> (postings per group table)
2832c235 TH	306
	307	Override I<DBTableGrps> from F<newsstats.conf>.
	308
880c3eb2	309	=item B<--clientsdb> I<table> (client data table)
2832c235 TH	310
	311	Override I<DBTableClnts> from F<newsstats.conf>.
	312
880c3eb2	313	=item B<--hostsdb> I<table> (host data table)
2832c235 TH	314
	315	Override I<DBTableHosts> from F<newsstats.conf>.
	316
	317	=back
	318
	319	=head1 INSTALLATION
	320
880c3eb2	321	See L<doc/INSTALL>.
2832c235 TH	322
	323	=head1 EXAMPLES
	324
	325	Process all types of information for lasth month:
	326
	327	gatherstats
	328
	329	Do a dry run, showing results of processing:
	330
880c3eb2	331	gatherstats --debug --test
2832c235 TH	332
	333	Process all types of information for January of 2010:
	334
880c3eb2	335	gatherstats --month 2010-01
2832c235	336
ad609792 TH	337	Process only number of postings for the year of 2010,
ad609792 TH	338	checking against checkgroups-2010.txt:
2832c235	339
880c3eb2	340	gatherstats -m 2010-01:2010-12 -s groups -c checkgroups-2010.txt
2832c235 TH	341
	342	=head1 FILES
	343
	344	=over 4
	345
	346	=item F<gatherstats.pl>
	347
	348	The script itself.
	349
	350	=item F<NewsStats.pm>
	351
	352	Library functions for the NewsStats package.
	353
	354	=item F<newsstats.conf>
	355
880c3eb2	356	Runtime configuration file.
2832c235 TH	357
	358	=back
	359
	360	=head1 BUGS
	361
	362	Please report any bugs or feature requests to the author or use the
	363	bug tracker at L<http://bugs.th-h.de/>!
	364
	365	=head1 SEE ALSO
	366
	367	=over 2
	368
	369	=item -
	370
880c3eb2	371	L<doc/README>
2832c235 TH	372
	373	=item -
	374
880c3eb2	375	L<doc/INSTALL>
2832c235 TH	376
	377	=back
	378
	379	This script is part of the B<NewsStats> package.
	380
	381	=head1 AUTHOR
	382
	383	Thomas Hochstein <thh@inter.net>
	384
	385	=head1 COPYRIGHT AND LICENSE
	386
880c3eb2	387	Copyright (c) 2010-2012 Thomas Hochstein <thh@inter.net>
2832c235 TH	388
	389	This program is free software; you may redistribute it and/or modify it
	390	under the same terms as Perl itself.
	391
	392	=cut