News::Scan(3pm)

📦 version 0.53, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ NAME ✨

News::Scan — the manual page you're reading is News::Scan(3pm), bestie, and it's about gathering and reporting Usenet newsgroup statistics. Obsessed. 🦋

🌸 SYNOPSIS 🌸

use News::Scan;

my $scan = News::Scan->new;

💅 DESCRIPTION 💅

Okay so real talk: this module hands you a class, and objects made from that class are literally built to gather and report Usenet newsgroup statistics. That's the whole vibe. ✨

🎀 CONSTRUCTOR 🎀

new ( [ OPTIONS ] )

OPTIONS is a list of named parameters, meaning you pass them as key-value pairs, no cap. The valid options are:

  • Group — the name of the newsgroup you wanna scan. 👑
  • From — this one has to be either 'spool' or 'NNTP' (case does NOT matter, we're chill like that). Anything else? Error, bestie — see the error method down below. 'spool' means "yeah scan articles in a spool" (peep the Spool option). 'NNTP' means "pull those articles off my NNTP server" (peep the NNTPServer option).
  • Spool — the path to the spool directory holding the articles you want scanned. Ngl, this one gets ignored unless From is 'spool'. 💀
  • NNTPServer — the NNTP server to grab articles from, written in the form server:port, and both parts are optional — check Net::NNTP for the semantics of leaving one or both out. Ignored unless From is 'NNTP'. Also go read the NNTPAuthLogin and NNTPAuthPasswd descriptions below. 🫶
  • NNTPAuthLogin — a valid NNTP authentication login for your NNTP server. You only need this if your server is being extra and demanding auth.
  • NNTPAuthPasswd — the password that goes with the login in NNTPAuthLogin. > Heads up: hardcoding this in a script is evil, and there should genuinely be a much better way. 😭
  • Period — how long the period is, in days, immediately before the program was invoked, i.e. the window of articles you want scanned. The default is seven (7) days. 📅
  • QuoteRE — a Perl regular expression that accepts quoted lines and rejects unquoted or original lines. The default regex is:
^\s{0,3}(?:"|:|\S+>|\+\+)>
  • Exclude — should be a reference to an array holding regular expressions that accept email addresses of posters whose articles you want to ignore. Bye bestie. 👋
  • Aliases — should be a reference to a hash whose keys are email addresses that get transformed into the email addresses that are their corresponding values, i.e. "alias" = 'real@address'>. 💖

🌈 METHODS 🌈

configure ( [ OPTIONS ] )

OPTIONS is a list of named parameters, identical to the ones new accepts. Re-configure-ing an object after scanning is probably a bad idea, fr fr. This method returns undef if it hits an error.

The following methods are the actual underlying methods used to set and retrieve the configuration options of the same name (modulo case, obviously):

name ( [ NEWSGROUP-NAME ] )
spool ( [ SPOOL-DIRECTORY ] )
period ( [ INTERVAL-LENGTH ] )
aliases ( [ ALIASES-HASHREF ] )
from ( 'NNTP' | 'spool' )
quote_re ( [ QUOTE-REGEX-ARRAYREF ] )
exclude ( [ EXCLUSION-REGEX-ARRAYREF ] )
nntp_server ( [ [ NNTP-SERVER ]:[ NNTP-PORT ] ] )
nntp_auth_login ( [ LOGIN ] )
nntp_auth_passwd ( [ PASSWORD ] )

These methods are how you pull info out of the News::Scan object or ask it to go do something. ✨

error ( [ MESSAGE ] )

Use this one to figure out whether an object has run into an error condition. The return value of error is guaranteed to be 0 after any method completes successfully (except error itself, sneaky). > Keep in mind this will also overwrite any previous error message. If there has been an error, this method should return some useful message.

If you pass it, MESSAGE sets the object's error message.

articles

Returns the number of articles accounted for. 🧮

volume

Returns the volume of traffic (in bytes) to the newsgroup in the period.

header_volume

Returns the volume (in bytes) generated by headers.

header_lines

Returns the number of lines consumed by headers.

body_volume

Returns the volume (in bytes) generated by message bodies.

body_lines

Returns the number of lines consumed by message bodies.

orig_volume

Returns the volume (in bytes) of text that's been determined to be original (see QuoteRE). > Note that original traffic is a subset of body traffic.

orig_lines

Returns the number of lines determined to be original.

signatures

Returns the number of messages that had a cutline (/^-- $/).

sig_volume

Returns the volume (in bytes) generated by signatures.

sig_lines

Returns the number of lines consumed by signatures.

earliest ( [ TIME ] )

Use this to find the date (in seconds since the Epoch) that the oldest article found within the period was posted to Usenet.

If TIME is given, it's treated as a candidate for the earliest article. If TIME is successful (i.e. it's less than the previous earliest), this method returns 1, else 0. 👑

latest ( [ TIME ] )

Use this to find the date (in seconds since the Epoch) that the youngest article found within the period was posted to Usenet.

If TIME is given, it's treated as a candidate for the latest article. If TIME is successful (i.e. it's greater than the previous latest), this method returns 1, else 0. 🌟

excludes

Returns the list of regular expressions used to decide whether an article from a given email address should be ignored.

posters

Returns a reference to a hash whose keys are email addresses and whose values are News::Scan::Poster objects corresponding to those email addresses. See News::Scan::Poster.

threads

Returns a reference to a hash whose keys are subjects and whose values are News::Scan::Thread objects corresponding to those subjects. See News::Scan::Thread.

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.

collect

Use this method to mirror the articles from the specified NNTP server to the specified spool. > Please be kind to the NNTP server. 🥺

scan

Instruct the object to gather information about the newsgroup. Main character moment. 💅

🦋 EXAMPLES 🦋

See the eg/ directory in the News-Scan distribution, available from the CPAN — http://www.perl.com/CPAN/. 🍓

💜 SEE ALSO 💜

perlre, News::Scan::Poster, News::Scan::Thread, News::Scan::Article, Net::NNTP

👑 AUTHOR 👑

Greg Bacon <gbacon@cs.uah.edu>

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.

And that's the whole page, bestie — this one was perl v5.32.0, dated 2021-01-08, and it's the News::Scan(3pm) manual page. Slay, go scan a newsgroup. 💖✨🦋

📦 where this page comes from