NNTPClient(3pm)

🦋 NNTPClient(3pm) 🦋

okay bestie, sit DOWN, because we're about to make your Perl talk to a news server and it's gonna be iconic. this is the manual page for News::NNTPClient (a Perl 5 module to talk to NNTP (RFC977) server, no cap).

---

✨ SYNOPSIS ✨

use News::NNTPClient;

$c = new News::NNTPClient;
$c = new News::NNTPClient($server);
$c = new News::NNTPClient($server, $port);
$c = new News::NNTPClient($server, $port, $debug);

like. look at that. four whole ways to show up. 💅

---

💖 DESCRIPTION 💖

so this module implements a client interface to NNTP, which means it lets a Perl 5 application talk to NNTP servers. it uses the OOP (Object Oriented Programming) interface that came along with Perl 5. very main character, very "i have methods."

NNTPClient exports nothing. literally nothing. it gives, but it does not export. periodt.

you HAVE to make a new NNTPClient object with the new method first. once that's done, every single NNTP command gets accessed through this object. that's the whole vibe.

here are a couple of short examples. the first one prints all the articles in the "test" newsgroup:

#!/usr/local/bin/perl -w

use News::NNTPClient;

$c = new News::NNTPClient;

($first, $last) = ($c->group("test"));

for (; $first <= $last; $first++) {
    print $c->article($first);
}

__END__

and this next one prints the body of all articles in the "test" newsgroup that are newer than one hour:

#!/usr/local/bin/perl -w

require News::NNTPClient;

$c = new News::NNTPClient;

foreach ($c->newnews("test", time - 3600)) {
    print $c->body($_);
}

__END__

ate. 🍓

---

🎀 NNTPClient Commands 🎀

these commands are the ones that mess with the NNTPClient object itself. they're not directly related to any commands available on an NNTP server, okay? they're the ~behind the scenes~ girls.

new

use this to create a new NNTP connection. it takes three arguments: a hostname, a port, and a debug flag. it calls initialize. use an empty argument to specify defaults.

if port is omitted or blank (""), it looks for environment variable NNTPPORT, then service "nntp", or else uses 119.

if host is omitted or empty (""), it looks for environment variable NNTPSERVER or else uses "news".

examples:

$c = new News::NNTPClient;

or

$c = new News::NNTPClient("newsserver.some.where");

or

$c = new News::NNTPClient("experimental", 9999);

or

# Specify debug but use defaults.
$c = new News::NNTPClient("", "", 2);

returns a blessed reference, representing a new NNTP connection. a whole new bb, blessed and everything. 🫶

initialize

calls port, host, connect, and response, in that exact order. if any of these fail, initialization is aborted. no partial slay allowed.

connect

connects to the current host/port. not normally needed, because the new method already does this for you. it closes any existing connection (bye bestie) and sets the posting status. see the postok method.

host

sets the host that will be used on the next connect. not normally needed, because the new method does this for you.

without an argument, it returns the current host.

the argument can be a hostname or a dotted quad, for example, "15.2.174.218".

returns the fully qualified host name.

port

sets the port that will be used on the next connect. not normally needed, because the new method does this for you.

without an argument, it returns the current port.

the argument can be a port number or a name. if it's a name, it must be a valid service.

returns the port number.

debug

sets the debug level.

without an argument, it returns the current debug level.

there are currently three debug levels: level 0, level 1, and level 2.

at level 0, the messages described for level 1 are not produced. debug level 0 is a way of turning off messages produced by the default debug level 1. serious error messages, such as EOF (End Of File) on the file handle, are still produced — those ones still pull up. 💀

at level 1, any NNTP command that results in a result code of 400 or greater prints a warning message. this is the default.

at level 2, in addition to level 1 messages, status messages are printed to indicate actions taking place.

returns the old debug value.

ok

returns boolean status of the most recent command. NNTP return codes less than 400 are considered OK. not often needed, since most commands return false upon failure anyway.

okprint

returns boolean status of the most recent command. NNTP return codes less than 400 are considered OK. it prints an error message for return codes of 400 or greater, unless the debug level is set to zero (0).

this method is used internally by most commands, and could be considered to be "for internal use only". you should use the return status of commands directly to determine pass-fail, or if needed the ok method can be used to check status later. lowkey it's giving backstage crew energy.

message

returns the NNTP response message of the most recent command.

example, as returned by NNTP server version 1.5.11t:

$c->slave;
print $c->message;

Kinky, kinky.  I don't support such perversions.

iconic server behaviour honestly. 😭

code

returns the NNTP response code of the most recent command.

example:

$c->article(1);
print $c->code, "\n";

412

postok

returns the post-ability status that was reported upon connection or after the mode_reader command.

eol

sets the End-Of-Line termination for text returned from the server.

returns the old EOL value.

default is \n.

to set EOL to nothing, pass it the empty string.

to query the current EOL without setting it, call with no arguments.

example:

$old_eol = $c->eol();     # Get original.
$c->eol("");              # Set EOL to nothing.
@article = $c->article(); # Fetch an article.
$c->eol($old_eol);        # Restore value.

save your settings bestie, always restore. 🌸

gmt

sets GMT mode. returns the old value. to query GMT mode without setting it, call with no arguments.

a true value means that GMT mode is used in the newgroups and newnews functions. a false value means that local time is used.

fourdigityear

sets four digit year mode. returns the old value. to query four digit year mode without setting it, call with no arguments.

a true value means that four digit years are used in the newgroups and newnews functions. a false value means that an RFC977 compliant two digit year is used.

this function is available for news servers that implemented four digit years rather than deal with non-y2k compliment two digit years. RFC977 does not allow four digit years, and instead chooses the century closest. i quote:

The closest century is assumed as part of the year (i.e., 86
specifies 1986, 30 specifies 2030, 99 is 1999, 00 is 2000).

version

returns the version number.

this document represents @(#) $Revision: 0.37 $.

---

🔥 NNTP Commands 🔥

these commands directly correlate to NNTP server commands. they return a false value upon failure, true upon success. the truth value is usually some bit of useful information. for example, the stat command returns Message-ID if it is successful. giving useful info AND being honest? we love a multi-talented king.

some commands return multiple lines. these lines are returned as an array in array context, and as a reference to an array in scalar context. for example, if you do this:

@lines = $c->article(14);

then @lines will contain the article, one line per array element. however, if you do this:

$lines = $c->article(14);

then $lines will contain a reference to an array. this feature is for those that don't like passing arrays from routine to routine. iykyk. 🙈

mode_reader

some servers require this command to process NNTP client commands. it sets the postok status. see postok.

returns OK status.

article

retrieves an article from the server. this is THE main command for fetching articles. it expects a single argument: an article number or a Message-ID. if you use an article number, you must be in a news group. see group.

returns the header, a separating blank line, and the body of the article as an array of lines terminated by the current EOL.

in scalar context, a reference to the array is returned instead of the array itself.

examples:

print $c->article('<art1234@soom.oom>');

$c->group("test");

print $c->article(99);

body

expects a single argument: an article number or a Message-ID.

returns the body of an article as an array of lines terminated by the current EOL.

in scalar context, a reference to the array is returned instead of the array itself.

see article.

head

expects a single argument: an article number or a Message-ID.

returns the head of the article as an array of lines terminated by the current EOL.

in scalar context, a reference to the array is returned instead of the array itself.

see article.

stat

expects a single argument: an article number or a Message-ID.

the STAT command is like the ARTICLE command, except that it does not return any text. it can be used to set the "current article pointer" if passed an article number, or to validate a Message-ID if passed a Message-ID.

returns Message-ID if successful, otherwise returns false.

last

the "current article pointer" maintained by the server is moved to the previous article in the current news group.

returns Message-ID if successful, otherwise returns false.

next

the "current article pointer" maintained by the server is moved to the next article in the current news group.

returns Message-ID if successful, otherwise returns false.

group

expects a single argument: the name of a valid news group.

this command sets the current news group as maintained by the server. it also sets the server maintained "current article pointer" to the first article in the group. this enables the use of certain other server commands, such as article, head, body, stat, last, and next. it also sets the current group in the NNTPClient object, which is used by the newnews and xindex commands.

---

and that's where we're pausing bestie, because there is MORE coming — part 2 is right around the corner and it's gonna be even more unhinged. don't go anywhere. 💜

Returns (first, last) in list context, or "first-last" in scalar context, where first and last are literally the first and last article numbers as reported by the group command. Returns false if there's an error. 😭

Trying to select a newsgroup that doesn't exist? That's an error, bestie. Not the vibe. 🚫

And if you need the estimated article count, you can pull it out of the message — see message. 💅

---

list

Takes two optional arguments. The first one tells it what kind of list you want, and which kinds even exist depends on your server. The second is a pattern, used by some list types.

Examples:

print $c->list();
print $c->list('active');
print $c->list('active', 'local.*');
print $c->list('newsgroups');

Give it "active", or give it nothing at all, and it hands back a list of valid newsgroups plus their info. The format is:

group last first p

where group is the news group name, last is the article number of the last article, first is the article number of the first article, and p is a flag telling you whether posting is allowed. A 'y' flag means posting is allowed. ✅

Other arguments you can pass: newsgroups, distributions, subscriptions for B-News, and active.times, distributions, distrib.pats, newsgroups, overview.fmt for INN.

Returns an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of the array itself. 🎀

newgroups

Expects at least one argument standing in for the date/time, either in seconds or in "YYYYMMDD HHMMSS [GMT]" format. The GMT part is optional. If you wanna use GMT with the seconds format, call gmt first. The remaining arguments get used as distributions.

Example — print every new group in the comp and/or news hierarchy as of one hour ago:

print $c->newgroups(time() - 3600, "comp", "news");

Returns a list of new news group names as an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of the array itself. ✨

newnews

Expects one, two, or more arguments.

If the first argument is a group name, it goes looking for new news in that group, and the date/time is the second argument. If the first argument is the date/time in seconds or in "YYYYMMDD HHMMSS [GMT]" format, then the group is the last group set via the group command. And if no group command has ever been issued? Then the group is "*", which means all groups. If you wanna use GMT in seconds format for the time, call gmt first. The remaining arguments restrict the search to certain distribution(s).

Returns a list of Message-IDs of articles that have been posted or received since the specified time.

Examples:

# Hour old news in news group "test".
$c->newnews("test", time() - 3600);

or

# Hour old in all groups.
$c->newnews(time() - 3600);

or

$c->newnews("*", time() - 3600);

or

# Hour old news in news group "test".
$c->group("test");
$c->newnews(time() - 3600);

The group argument can include an asterisk "*" to specify a range of news groups. It can also include multiple news groups, separated by a comma ",".

Example:

$c->newnews("comp.*.sources,alt.sources", time() - 3600);

An exclamation point "!" may be used to negate the selection of certain groups.

Example:

$c->newnews("*sources*,!*.d,!*.wanted", time() - 3600);

Any additional distribution arguments get concatenated together and sent as a distribution list. That distribution list limits articles to the ones that have a Distribution: header containing one of the distributions you passed.

Example:

$c->newnews("*", time() - 3600, "local", "na");

Returns Message-IDs of new articles as an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of the array itself. 🦋

help

Returns whatever server help information exists. The format is super dependent on the server, but it usually contains a list of NNTP commands the server recognizes.

Returns an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of the array itself. 💖

post

Posts an article. Expects the data to be posted as an array of lines. Most servers expect, at a minimum, Newsgroups and Subject headers. Be sure to separate the header from the body with a neck, er blank line. 😭

Example:

@header = ("Newsgroups: test", "Subject: test", "From: tester");
@body   = ("This is the body of the article");

$c->post(@header, "", @body);

There aren't really three arguments. Perl folds all arguments into a single list. You could also do this:

@article = ("Newsgroups: test", "Subject: test", "From: tester", "", "Body");
$c->post(@article);

or even this:

$c->post("Newsgroups: test", "Subject: test", "From: tester", "", "Body");

Any "\n" characters at the end of a line will be trimmed.

Returns status.

ihave

Transfer an article. Expects an article Message-ID and the article to be sent as an array of lines.

Example:

# Fetch article from server on $c
@article = $c->article($artid);

# Send to server on $d
if ($d->ihave($artid, @article)) {
    print "Article transfered\n";
} else {
    print "Article rejected: ", $d->message, "\n";
}

slave

Doesn't do anything on most servers. Included for completeness. 🙈

DESTROY

This method is called whenever the object created by News::NNTPClient::new is destroyed. It calls quit to close the connection.

quit

Sends the NNTP quit command and closes the connection. The connection can then be re-opened with the connect method. quit will automatically be called when the object is destroyed, so there's no need to explicitly call quit before exiting your program. 👑

---

🌈 Extended NNTP Commands 🌈

These commands also directly correlate to NNTP server commands, but they're not mentioned in RFC977, and they're not part of the standard. However, many servers implement them, so they're included as part of this package for your convenience. If a command isn't recognized by a server, the server usually returns code 500, command unrecognized. 💀

authinfo

Expects two arguments, user and password.

date

Returns server date in "YYYYMMDDhhmmss" format.

listgroup

Expects one argument, a group name. Default is the current group.

Returns article numbers as an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of the array itself. ✨

xmotd

Expects one argument of unix time in seconds or as a string in the form "YYYYMMDD HHMMSS".

Returns the news servers "Message Of The Day" as an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of the array itself.

For example, the following will always print the message of the day, if there is any:

print $c->xmotd(1);
NNTP Server News2

News administrator is Joseph Blough <joeblo@news.foo.com>

xgtitle

Expects one argument of a group pattern. Default is current group.

Returns group titles an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of the array itself.

Example:

print $c->xgtitle("bit.listserv.v*");

bit.listserv.valert-l   Virus Alert List. (Moderated)
bit.listserv.vfort-l    VS-Fortran Discussion List.
bit.listserv.vm-util    VM Utilities Discussion List.
bit.listserv.vmesa-l    VM/ESA Mailing List.
bit.listserv.vmslsv-l   VAX/VMS LISTSERV Discussion List.
bit.listserv.vmxa-l     VM/XA Discussion List.
bit.listserv.vnews-l    VNEWS Discussion List.
bit.listserv.vpiej-l    Electronic Publishing Discussion

xpath

Expects one argument of an article Message-ID. Returns the path name of the file on the server.

Example:

print print $c->xpath(q(<43bq5l$7b5@news.dtc.hp.com>))'
hp/test/4469

xhdr

Fetch header for a range of articles. First argument is name of header to fetch. If omitted or blank, default to Message-ID. Second argument is start of article range. If omitted, defaults to 1. Third argument is end of range. If omitted, defaults to "". The second argument can also be a Message-ID.

Returns headers as an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of the array itself.

Examples:

# Fetch Message-ID of article 1.
$c->xhdr();

# Fetch Subject of article 1.
$c->xhdr("Subject");

# Fetch Subject of article 3345.
$c->xhdr("Subject", 3345);

# Fetch Subjects of articles 3345-9873
$c->xhdr("Subject", 3345, 9873);

# Fetch Message-ID of articles 3345-9873
$c->xhdr("", 3345,9873);

# Fetch Subject for article with Message-ID
$c->xhdr("Subject", '<797t0g$25f10@foo.com>');

🗂️ xpat

Okay so this one fetches the header for a range of articles that match one or more patterns. First argument = the name of the header you wanna fetch. Leave it out or leave it blank and it defaults to Subject. Second argument = start of the article range; skip it and it defaults to 1. Next argument = the end of the range. Remaining arguments = the patterns you're matching against. Little heads-up bestie: some servers use "*" for the wildcard. 🦋

It hands you back the headers as an array of lines, each one terminated by the current EOL.

And if you call it in scalar context, you get a reference to that array instead of the array itself. Iconic.

Examples, no cap:

# Fetch Subject header of article 1.
$c->xpat();

# Fetch "From" header of article 1.
$c->xpat("From");

# Fetch "From" of article 3345.
$c->xpat("From", 3345);

# Fetch "From" of articles 3345-9873 matching *foo*
$c->xpat("From", 3345, 9873, "*foo*");

# Fetch "Subject" of articles 3345-9873 matching
# *foo*, *bar*, *and*, *stuff*
$c->xpat("", 3345,9873, qw(*foo* *bar* *and* *stuff*));

---

📋 xover

This one expects either a single article number, or a starting and ending article number that represents a range of articles. 💅

It returns overview info for each article, as an array of lines terminated by the current EOL.

In scalar context, again, you get a reference to the array instead of the array itself. Same energy every time, we love consistency.

Quick fact: Xover generally returns items separated by tabs. Here's an example that prints out the xover fields from every message in the "test" news group — yes, it's a whole little script, she's giving main character:

#!/usr/local/bin/perl

require News::NNTPClient;

$c = new News::NNTPClient;

@fields = qw(numb subj from date mesg refr char line xref);

foreach $xover ($c->xover($c->group("test"))) {
    %fields = ();
    @fields{@fields} = split /\t/, $xover;
    print map { "$_: $fields{$_}\n" } @fields;
    print "\n";
}

__END__
                              #

---

🧵 xthread

Real talk: the source literally has a leftover POD line right here — it says =item I<xthread> — so that's what I'm showing you, fr fr. We're keeping it, we don't edit history. 💀

Expects zero or one argument. The value of the argument genuinely doesn't matter. If it's present, the dbinit command gets sent. If it's absent, the thread command gets sent.

Returns binary data as a scalar value.

Format of the data returned is unknown at this time. 🙈

---

🔎 xindex

Expects one argument: a group name. If you omit it, it defaults to the group set by the last group command. And if there hasn't even been a group command? It returns an error. Periodt. 😭

Returns index information for the group as an array of lines terminated by the current EOL.

In scalar context a reference to the array is returned instead of the array itself. (You already knew that, you're a genius.)

---

🔍 xsearch

Expects a query as an array of lines, which get sent to the server — much like post. It returns the result of the search as an array of lines, or a reference to the same. 🫶

Format of the query is unknown at this time. Mystery behaviour, we stan an enigma, but also pls don't guess at it.

---

👑 AUTHOR

Rodger Anderson <rodger@boi.hp.com>

---

📜 COPYRIGHT

Copyright 1995 Rodger Anderson. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🌈

---

And that's the whole page, bestie!! 🎀 This beauty shipped as part of perl v5.36.0 and got dated 2022-12-10, living under the name NNTPClient(3pm). Go forth and fetch some headers, you absolute legend. 💖✨