Provided by: libnews-nntpclient-perl_0.37-8_all 
NAME
News::NNTPClient - Perl 5 module to talk to NNTP (RFC977) server
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);
DESCRIPTION
This module implements a client interface to NNTP, enabling a Perl 5 application to talk
to NNTP servers. It uses the OOP (Object Oriented Programming) interface introduced with
Perl 5.
NNTPClient exports nothing.
A new NNTPClient object must be created with the new method. Once this has been done, all
NNTP commands are accessed through this object.
Here are a couple of short examples. The first prints all 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__
This example prints the body of all articles in the "test" newsgroup 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__
NNTPClient Commands
These commands are used to manipulate the NNTPClient object, and aren't directly related
to commands available on any NNTP server.
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 (""), looks for environment variable NNTPPORT,
service "nntp", or uses 119.
If host is omitted or empty (""), looks for environment variable NNTPSERVER or
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.
initialize
Calls port, host, connect, and response, in that order. If any of these fail,
initialization is aborted.
connect Connects to current host/port. Not normally needed, as the new method does this
for you. Closes any existing connection. Sets the posting status. See the
postok method.
host Sets the host that will be used on the next connect. Not normally needed, as
the new method does this for you.
Without an argument, returns current host.
Argument can be hostname or dotted quad, for example, "15.2.174.218".
Returns fully qualified host name.
port Sets the port that will be used on the next connect. Not normally needed, as
the new method does this for you.
Without an argument, returns current port.
Argument can be port number or name. If it is a name, it must be a valid
service.
Returns port number.
debug Sets the debug level.
Without an argument, returns 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.
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 old debug value.
ok Returns boolean status of most recent command. NNTP return codes less than 400
are considered OK. Not often needed as most commands return false upon failure
anyway.
okprint Returns boolean status of most recent command. NNTP return codes less than 400
are considered OK. Prints an error message for return codes of 400 or greater
unless 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.
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.
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 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.
gmt Sets GMT mode. Returns 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 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 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.
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.
mode_reader
Some servers require this command to process NNTP client commands. Sets postok
status. See postok.
Returns OK status.
article Retrieves an article from the server. This is the main command for fetching
articles. Expects a single argument, an article number or 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 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 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 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. Also sets the current group in the NNTPClient
object, which is used by the newnews and xindex commands.
Returns (first, last) in list context, or "first-last" in scalar context, where
first and last are the first and last article numbers as reported by the group
command. Returns false if there is an error.
It is an error to attempt to select a non-existent news group.
If the estimated article count is needed, it can be extracted from the message.
See message.
list Accepts two optional arguments. The first can be used indicate the type of list
desired. List type depends on server. The second is a pattern that is use by
some list types.
Examples:
print $c->list();
print $c->list('active');
print $c->list('active', 'local.*');
print $c->list('newsgroups');
With an argument of "active" or with no arguments, this command returns a list
of valid newsgroups and associated information. 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 flag
indicating if posting is allowed. A 'y' flag is an indication that posting is
allowed.
Other possible arguments are: 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 representing the date/time in seconds, or in
"YYYYMMDD HHMMSS [GMT]" format. The GMT part is optional. If you wish to use
GMT with the seconds format, first call gmt. Remaining arguments are used as
distributions.
Example, print all new groups in the "comp" and/or "news" hierarchy as of one
hour ago:
print $c->newgroups(time() - 3600, "comp", "news");
Returns 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 looks for new news in that group, and
the date/time is the second argument. If the first argument represents the
date/time in seconds or in "YYYYMMDD HHMMSS [GMT]" format, then the group is is
last group set via the group command. If no group command has been issued then
the group is "*", representing all groups. If you wish to use GMT in seconds
format for the time, first call gmt. Remaining arguments are use to restrict
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 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 will be concatenated together and send as
a distribution list. The distribution list will limit articles to those that
have a Distribution: header containing one of the distributions 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 any server help information. The format of the information is highly
dependent on the server, but usually contains a list of NNTP commands recognized
by the server.
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 Post an article. Expects 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 the object created by News::NNTPClient::new
is destroyed. It calls quit to close the connection.
quit Send the NNTP quit command and close the connection. The connection can be then
be re-opened with the connect method. Quit will automatically be called when
the object is destroyed, so there is no need to explicitly call quit before
exiting your program.
Extended NNTP Commands
These commands also directly correlate NNTP server commands, but are not mentioned in
RFC977, and are not part of the standard. However, many servers implement them, so they
are included as part of this package for your convenience. If a command is not 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 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 Fetch header for a range of articles matching one or more patterns. First
argument is name of header to fetch. If omitted or blank, default to Subject.
Second argument is start of article range. If omitted, defaults to 1. Next
argument is end of range. Remaining arguments are patterns to match. Some
servers use "*" for wildcard.
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 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 Expects an article number or a starting and ending article number representing a
range of articles.
Returns overview information for each 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.
Xover generally returns items separated by tabs. Here is an example that prints
out the xover fields from all messages in the "test" news group.
#!/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__
#
=item I<xthread>
Expects zero or one argument. Value of argument doesn't matter. If present,
dbinit command is sent. If absent, thread command is sent.
Returns binary data as a scalar value.
Format of data returned is unknown at this time.
xindex Expects one argument, a group name. If omitted, defaults to the group set by
last group command. If there hasn't been a group command, it returns an error;
Returns index information for 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.
xsearch Expects a query as an array of lines which are sent to the server, much like
post. Returns the result of the search as an array of lines or a reference to
same.
Format of query is unknown at this time.
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.