Provided by: libnews-nntpclient-perl_0.37-8_all bug

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.