.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "News::Scan 3pm"
.TH News::Scan 3pm "2021-01-08" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
News::Scan \- gather and report Usenet newsgroup statistics
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use News::Scan;
\&
\&    my $scan = News::Scan\->new;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a class whose objects can be used to gather and
report Usenet newsgroup statistics.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new ( [ \s-1OPTIONS\s0 ] )" 4
.IX Item "new ( [ OPTIONS ] )"
\&\f(CW\*(C`OPTIONS\*(C'\fR is a list of named parameters (i.e. given in key-value pairs).
Valid options are
.IP "\fBGroup\fR" 8
.IX Item "Group"
The value of this option is the name of the newsgroup you wish to scan.
.IP "\fBFrom\fR" 8
.IX Item "From"
The value of this option should be either \f(CW\*(Aqspool\*(Aq\fR or \f(CW\*(AqNNTP\*(Aq\fR (case is
not significant).  Any other value will produce an error (see the \f(CW\*(C`error\*(C'\fR
method description below).  A value of \f(CW\*(Aqspool\*(Aq\fR indicates that you would
like to
scan articles in a spool (see the \fBSpool\fR option below).  A value of
\&\f(CW\*(AqNNTP\*(Aq\fR indicates that articles should be retrieved from your \s-1NNTP\s0
server (see the \fBNNTPServer\fR option below).
.IP "\fBSpool\fR" 8
.IX Item "Spool"
The value of this option should be the path to the spool directory that
contains the articles you would like to scan.  This option is ignored
unless the value of \fBFrom\fR is \f(CW\*(Aqspool\*(Aq\fR.
.IP "\fBNNTPServer\fR" 8
.IX Item "NNTPServer"
The value of this option (in the form \fIserver\fR:\fIport\fR, with both being
optional\*(--see Net::NNTP for the semantics of omitting one or both of
these parameters) indicates the \s-1NNTP\s0 server from which to retrieve
articles.  This option is ignored unless \fBFrom\fR is \f(CW\*(AqNNTP\*(Aq\fR.  See the
description of the \fBNNTPAuthLogin\fR and \fBNNTPAuthPasswd\fR options below.
.IP "\fBNNTPAuthLogin\fR" 8
.IX Item "NNTPAuthLogin"
The value of this option should be a valid \s-1NNTP\s0 authentication login for
your \s-1NNTP\s0 server.  This option is only necessary if your \s-1NNTP\s0 server
requires authentication.
.IP "\fBNNTPAuthPasswd\fR" 8
.IX Item "NNTPAuthPasswd"
The value of this option should be the password corresponding to the
login in \fBNNTPAuthLogin\fR.  Having this hardcoded in a script is evil,
and there should be a much better way.
.IP "\fBPeriod\fR" 8
.IX Item "Period"
The value of this option indicates the length of the period (in days)
immediately prior to invocation of the program from which you would like
to scan articles.  The default period is seven (7) days.
.IP "\fBQuoteRE\fR" 8
.IX Item "QuoteRE"
The value of this option is a Perl regular expression that accepts quoted
lines and rejects unquoted or original lines.  The default regular
expression is \f(CW\*(C`^\es{0,3}(?:\*(C'\fR|:|\eS+>|\e+\e+)>.
.IP "\fBExclude\fR" 8
.IX Item "Exclude"
The value of this option should be a reference to an array containing
regular expressions that accept email addresses of posters whose articles
you wish to ignore.
.IP "\fBAliases\fR" 8
.IX Item "Aliases"
The value of this option should be a reference to a hash whose keys
are email addresses that should be transformed into the email addresses
that are their corresponding values, i.e. \f(CW\*(C`alias =\*(C'\fR 'real@address'>.
.SH "METHODS"
.IX Header "METHODS"
.IP "configure ( [ \s-1OPTIONS\s0 ] )" 4
.IX Item "configure ( [ OPTIONS ] )"
\&\f(CW\*(C`OPTIONS\*(C'\fR is a list of named parameters identical to those accepted by
\&\f(CW\*(C`new\*(C'\fR.  Re\-\f(CW\*(C`configure\*(C'\fR\-ing an object after scanning is probably a bad
idea.  This method returns \f(CW\*(C`undef\*(C'\fR if it encounters an error.
.PP
The following methods are the actual underlying methods used to set
and retrieve the configuration options of the same name (modulo case):
.IP "name ( [ NEWSGROUP-NAME ] )" 4
.IX Item "name ( [ NEWSGROUP-NAME ] )"
.PD 0
.IP "spool ( [ SPOOL-DIRECTORY ] )" 4
.IX Item "spool ( [ SPOOL-DIRECTORY ] )"
.IP "period ( [ INTERVAL-LENGTH ] )" 4
.IX Item "period ( [ INTERVAL-LENGTH ] )"
.IP "aliases ( [ ALIASES-HASHREF ] )" 4
.IX Item "aliases ( [ ALIASES-HASHREF ] )"
.ie n .IP "from ( \*(AqNNTP\*(Aq | \*(Aqspool\*(Aq )" 4
.el .IP "from ( \f(CW\*(AqNNTP\*(Aq\fR | \f(CW\*(Aqspool\*(Aq\fR )" 4
.IX Item "from ( NNTP | spool )"
.IP "quote_re ( [ QUOTE-REGEX-ARRAYREF ] )" 4
.IX Item "quote_re ( [ QUOTE-REGEX-ARRAYREF ] )"
.IP "exclude ( [ EXCLUSION-REGEX-ARRAYREF ] )" 4
.IX Item "exclude ( [ EXCLUSION-REGEX-ARRAYREF ] )"
.IP "nntp_server ( [ [ NNTP-SERVER ]:[ NNTP-PORT ] ] )" 4
.IX Item "nntp_server ( [ [ NNTP-SERVER ]:[ NNTP-PORT ] ] )"
.IP "nntp_auth_login ( [ \s-1LOGIN\s0 ] )" 4
.IX Item "nntp_auth_login ( [ LOGIN ] )"
.IP "nntp_auth_passwd ( [ \s-1PASSWORD\s0 ] )" 4
.IX Item "nntp_auth_passwd ( [ PASSWORD ] )"
.PD
.PP
These methods can be used to retrieve information from the
\&\f(CW\*(C`News::Scan\*(C'\fR object or ask it to perform some action.
.IP "error ( [ \s-1MESSAGE\s0 ] )" 4
.IX Item "error ( [ MESSAGE ] )"
Use this method to determine whether an object has encountered an error
condition.  The return value of \f(CW\*(C`error\*(C'\fR is guaranteed to be \f(CW0\fR
after any method completes successfully (except \f(CW\*(C`error\*(C'\fR).  (Keep in
mind that this will also overwrite any previous error message.)  If there
has been an error, this method should return some useful message.
.Sp
If provided, \f(CW\*(C`MESSAGE\*(C'\fR sets the object's error message.
.IP "articles" 4
.IX Item "articles"
Returns the number of articles accounted for.
.IP "volume" 4
.IX Item "volume"
Returns the volume of traffic (in bytes) to the newsgroup in the period.
.IP "header_volume" 4
.IX Item "header_volume"
Returns the volume (in bytes) generated by headers.
.IP "header_lines" 4
.IX Item "header_lines"
Returns the number of lines consumed by headers.
.IP "body_volume" 4
.IX Item "body_volume"
Returns the volume (in bytes) generated by message bodies.
.IP "body_lines" 4
.IX Item "body_lines"
Returns the number of lines consumed by message bodies.
.IP "orig_volume" 4
.IX Item "orig_volume"
Returns the volume (in bytes) of text which has been determined to be
original (see \fBQuoteRE\fR).  Note that original traffic is a subset of
body traffic.
.IP "orig_lines" 4
.IX Item "orig_lines"
Returns the number of lines that are determined to be original.
.IP "signatures" 4
.IX Item "signatures"
Returns the number of messages that had a cutline (/^\-\- $/).
.IP "sig_volume" 4
.IX Item "sig_volume"
Returns the volume (in bytes) generated by signatures.
.IP "sig_lines" 4
.IX Item "sig_lines"
Returns the number of lines consumed by signatures.
.IP "earliest ( [ \s-1TIME\s0 ] )" 4
.IX Item "earliest ( [ TIME ] )"
Use this method to determine the date (in seconds since the Epoch) that
the oldest article found within the period was posted to Usenet.
.Sp
If \f(CW\*(C`TIME\*(C'\fR is given, it is treated as a candidate for the earliest
article.  If \f(CW\*(C`TIME\*(C'\fR is successful (i.e. is less than the previous
earliest), this method returns \f(CW1\fR, else \f(CW0\fR.
.IP "latest ( [ \s-1TIME\s0 ] )" 4
.IX Item "latest ( [ TIME ] )"
Use this method to determine the date (in seconds since the Epoch) that
the youngest article found within the period was posted to Usenet.
.Sp
If \f(CW\*(C`TIME\*(C'\fR is given, it is treated as a candidate for the latest
article.  If \f(CW\*(C`TIME\*(C'\fR is successful (i.e. is greater than the previous
latest), this method returns \f(CW1\fR, else \f(CW0\fR.
.IP "excludes" 4
.IX Item "excludes"
Returns the list of regular expressions used to determine
whether an article from a given email address should be ignored.
.IP "posters" 4
.IX Item "posters"
Returns a reference to a hash whose keys are email addresses and whose
values are \f(CW\*(C`News::Scan::Poster\*(C'\fR objects corresponding to those email
addresses.  See News::Scan::Poster.
.IP "threads" 4
.IX Item "threads"
Returns a reference to a hash whose keys are subjects and whose values
are \f(CW\*(C`News::Scan::Thread\*(C'\fR objects corresponding to those subjects.  See
News::Scan::Thread.
.IP "crossposts" 4
.IX Item "crossposts"
Returns a reference to a hash whose keys are newsgroup names and whose
values are the number of times the corresponding groups have been
crossposted to.
.IP "collect" 4
.IX Item "collect"
Use this method to mirror the articles from the specified  \s-1NNTP\s0 server
to the specified spool.  Please be kind to the \s-1NNTP\s0 server.
.IP "scan" 4
.IX Item "scan"
Instruct the object to gather information about the newsgroup.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
See the \fIeg/\fR directory in the \fINews-Scan\fR distribution, available
from the CPAN\*(--\fIhttp://www.perl.com/CPAN/\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
perlre, News::Scan::Poster, News::Scan::Thread,
News::Scan::Article, Net::NNTP
.SH "AUTHOR"
.IX Header "AUTHOR"
Greg Bacon <gbacon@cs.uah.edu>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1997 Greg Bacon.  All Rights Reserved.
This library is free software.  You may distribute and/or modify it under
the same terms as Perl itself.