This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: News/NNTPClient, Next: News/Newsrc, Prev: News/Gateway, Up: Module List Perl 5 module to talk to NNTP (RFC977) server ********************************************* 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.36 $. 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(''); $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 one optional argument that can be used indicate the type of list desired. List type depends on server. 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 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 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 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.  File: pm.info, Node: News/Newsrc, Next: News/Scan, Prev: News/NNTPClient, Up: Module List manage newsrc files ******************* NAME ==== News::Newsrc - manage newsrc files SYNOPSIS ======== use News::Newsrc; $newsrc = new News::Newsrc; $ok = $newsrc->load; $ok = $newsrc->load ($file); $newsrc->import_rc ( @lines); $newsrc->import_rc (\@lines); $newsrc->save; $newsrc->save_as ($file); @lines = $newsrc->export_rc; $ok = $newsrc-> add_group ($group, %options); $ok = $newsrc->move_group ($group, %options); $ok = $newsrc-> del_group ($group); $newsrc-> subscribe ($group, %options); $newsrc->unsubscribe ($group, %options); $newsrc->mark ($group, $article , %options); $newsrc->mark_list ($group, \@articles, %options); $newsrc->mark_range ($group, $from, $to, %options); $newsrc->unmark ($group, $article , %options); $newsrc->unmark_list ($group, \@articles, %options); $newsrc->unmark_range ($group, $from, $to, %options); ... if $newsrc->exists ($group); ... if $newsrc->subscribed ($group); ... if $newsrc->marked ($group, $article); $n = $newsrc-> num_groups; @groups = $newsrc-> groups; @groups = $newsrc-> sub_groups; @groups = $newsrc->unsub_groups; @articles = $newsrc-> marked_articles($group, %options); @articles = $newsrc->unmarked_articles($group, $from, $to, %options); $articles = $newsrc->get_articles ($group, %options); $ok = $newsrc->set_articles ($group, $articles, %options); REQUIRES ======== Perl 5.004, Set::IntSpan 1.07 EXPORTS ======= Nothing DESCRIPTION =========== `News::Newsrc' manages newsrc files, of the style alt.foo: 1-21,28,31-34 alt.bar! 3,5,9-2900,2902 Methods are provided for * reading and writing newsrc files * adding and removing newsgroups * changing the order of newsgroups * subscribing and unsubscribing from newsgroups * testing whether groups exist and are subscribed * marking and unmarking articles * testing whether articles are marked * returning lists of newsgroups * returning lists of articles NEWSRC FILES ============ A newsrc file is an ASCII file that lists newsgroups and article numbers. Each line of a newsrc file describes a single newsgroup. Each line is divided into three fields: a group, a *subscription mark* and an *article list*. Lines containing only whitespace are ignored. Whitespace within a line is ignored. Group The group is the name of the newsgroup. A group name may not contain colons (:) or exclamation points (!). Group names must be unique within a newsrc file. The group name is required. Subscription mark The *subscription mark* is either a colon (:), for subscribed groups, or an exclamation point (!), for unsubscribed groups. The subscription mark is required. Article list The *article list* is a comma-separated list of positive integers. The integers must be listed in increasing order. Runs of consecutive integers may be abbreviated a-b, where a is the first integer in the run and b is the last. The article list may be empty. NEWSGROUP ORDER =============== `News::Newsrc' preserves the order of newsgroups in a newsrc file: if a file is loaded and then saved, the newsgroup order will be unchanged. Methods that add or move newsgroups affect the newsgroup order. By default, these methods put newsgroups at the end of the newsrc file. Other locations may be specified by passing an %options hash with a where key to the method. Recognized locations are: where => `'first'' Put the newsgroup first. where => `'last'' Put the newsgroup last. where => `'alpha'' Put the newsgroup in alphabetical order. If the other newsgroups are not sorted alphabetically, put the group at an arbitrary location. where => [ before => *$group* ] Put the group immediately before *$group*. If *$group* does not exist, put the group last. where => [ after => *$group* ] Put the group immediately after *$group*. If *$group* does not exist, put the group last. where => [ number => $n ] Put the group at position $n in the group list. Indices are zero-based. Negative indices count backwards from the end of the list. METHODS ======= $newsrc = new `News::Newsrc' Creates and returns a `News::Newsrc' object. The object contains no newsgroups. $ok = $newsrc->load $ok = $newsrc->load($file) Loads the newsgroups in $file into $newsrc. If $file is omitted, reads `$ENV{HOME}/.newsrc'. Any existing data in $newsrc is discarded. Returns true on success. If $file can't be opened, load discards existing data from $newsrc and returns null. If $file contains invalid lines, load will die. When this happens, the state of $newsrc is undefined. $newsrc->`import_rc'(*@lines*) $newsrc->`import_rc'([*@lines*]) Imports the newsgroups in *@lines* into $newsrc. Any existing data in $newsrc is discarded. Each line in *@lines* describes a single newsgroup, and must have the format described in `"NEWSRC FILES"' in this node. If *@lines* contains invalid lines, `import_rc' will die. When this happens, the state of $newsrc is undefined. `import_rc' accepts either an array or an array reference. $newsrc->save Writes the contents of $newsrc back to the file from which it was loaded. If load has not been called, writes to `$ENV{HOME}/.newsrc'. In either case, if the destination file exists, it is renamed to file`.bak'. save will die if there is an error writing the file. $newsrc->`save_as'($file) Writes the contents of $newsrc to $file. If $file exists, it is renamed to $file`.bak'. Subsequent calls to save will write to $file. `save_as' will die if there is an error writing the file. *@lines* = $newsrc->`export_rc' Returns the contents of $newsrc as a list of lines. Each line describes a single newsgroup, and has the format described in `"NEWSRC FILES"' in this node. In scalar context, returns an array reference. $ok = $newsrc->add_group(*$group*, %options) Adds *$group* to the list of newsgroups in $newsrc. *$group* is initially subscribed. The article list for *$group* is initially empty. By default, *$group* is added to the end of the list of newsgroups. Other locations may be specified in %options; see `"NEWSGROUP ORDER"' in this node for details. By default, add_group does nothing if *$group* already exists. If the replace => 1 option is provided, then add_group will delete *$group* if it exists, and then add it. add_group returns true iff *$group* was added. $ok = $newsrc->`move_group'(*$group*, %options) Changes the position of *$group* in $newsrc according to %options. See `"NEWSGROUP ORDER"' in this node for details. If *$group* does not exist, `move_group' does nothing and returns false. Otherwise, it returns true. $ok = $newsrc->`del_group'(*$group*) If *$group* exists in $newsrc, `del_group' removes it and returns true. The article list for *$group* is lost. If *$group* does not exist in $newsrc, `del_group' does nothing and returns false. $newsrc->`subscribe'(*$group*, %options) Subscribes to *$group*. *$group* will be created if it does not exist. Its location may be specified in %options; see `"NEWSGROUP ORDER"' in this node for details. $newsrc->`unsubscribe'(*$group*, %options) Unsubscribes from *$group*. *$group* will be created if it does not exist. Its location may be specified in %options; see `"NEWSGROUP ORDER"' in this node for details. $newsrc->mark(*$group*, *$article*, %options) Adds *$article* to the article list for *$group*. *$group* will be created if it does not exist. Its location may be specified in %options; see `"NEWSGROUP ORDER"' in this node for details. $newsrc->`mark_list'(*$group*, *\@articles*, %options) Adds *@articles* to the article list for *$group*. *$group* will be created if it does not exist. Its location may be specified in %options; see `"NEWSGROUP ORDER"' in this node for details. $newsrc->`mark_range'(*$group*, *$from*, *$to*, %options) Adds all the articles from *$from* to *$to*, inclusive, to the article list for *$group*. *$group* will be created if it does not exist. Its location may be specified in %options; see `"NEWSGROUP ORDER"' in this node for details. $newsrc->unmark(*$group*, *$article*, %options) Removes *$article* from the article list for *$group*. *$group* will be created if it does not exist. Its location may be specified in %options; see `"NEWSGROUP ORDER"' in this node for details. $newsrc->`unmark_list'(*$group*, *\@articles*, %options) Removes *@articles* from the article list for *$group*. *$group* will be created if it does not exist. Its location may be specified in %options; see `"NEWSGROUP ORDER"' in this node for details. $newsrc->`unmark_range'(*$group*, *$from*, *$to*, %options) Removes all the articles from *$from* to *$to*, inclusive, from the article list for *$group*. *$group* will be created if it does not exist. Its location may be specified in %options; see `"NEWSGROUP ORDER"' in this node for details. $newsrc->exists(*$group*) Returns true iff *$group* exists in $newsrc. $newsrc->`subscribed'(*$group*) Returns true iff *$group* exists and is subscribed. $newsrc->marked(*$group*, *$article*) Returns true iff *$group* exists and its article list contains *$article*. $n = $newsrc->`num_groups' Returns the number of groups in $newsrc. *@groups* = $newsrc->groups Returns the list of groups in $newsrc, in newsrc order. In scalar context, returns an array reference. *@groups* = $newsrc->`sub_groups' Returns the list of subscribed groups in $newsrc, in newsrc order. In scalar context, returns an array reference. *@groups* = $newsrc->`unsub_groups' Returns the list of unsubscribed groups in $newsrc, in newsrc order. In scalar context, returns an array reference. *@articles* = $newsrc->`marked_articles'(*$group*) Returns the list of articles in the article list for *$group*. In scalar context, returns an array reference. *$group* will be created if it does not exist. Its location may be specified in %options; see `"NEWSGROUP ORDER"' in this node for details. *@articles* = $newsrc->`unmarked_articles'(*$group*, *$from*, *$to*, %options) Returns the list of articles from *$from* to *$to*, inclusive, that do not appear in the article list for *$group*. In scalar context, returns an array reference. *$group* will be created if it does not exist. Its location may be specified in %options; see `"NEWSGROUP ORDER"' in this node for details. $articles = $newsrc->`get_articles'(*$group*, %options) Returns the article list for *$group* as a string, in the format described in `"NEWSRC FILES"' in this node. *$group* will be created if it does not exist. Its location may be specified in %options; see `"NEWSGROUP ORDER"' in this node for details. If you plan to do any nontrivial processing on the article list, consider converting it to a `Set::IntSpan' object: $articles = Set::IntSpan->new($newsrc->get_articles('alt.foo')) $ok = $newsrc->`set_articles'(*$group*, $articles, %options) Sets the article list for $group. Any existing article list is lost. $articles is a string, as described in `"NEWSRC FILES"' in this node. *$group* will be created if it does not exist. Its location may be specified in %options; see `"NEWSGROUP ORDER"' in this node for details. If $articles does not have the format described in `"NEWSRC FILES"' in this node, `set_articles' does nothing and returns false. Otherwise, it returns true. DIAGNOSTICS =========== Bad newsrc line A line in the newsrc file does not have the format described in `"NEWSRC FILES"' in this node. Bad article list The article list for a newsgroup does not have the format described in `"NEWSRC FILES"' in this node. News::Newsrc::save_as: Can't rename $file, $file.bak: $! News::Newsrc::save_as: Can't open $file: $! News::Newsrc::format: Can't write $file: $! NOTES ===== Error Handling -------------- "Don't test for errors that you can't handle." load returns null if it can't open the newsrc file, and dies if the newsrc file contains invalid data. This isn't as schizophrenic as it seems. There are several ways a program could handle an open failure on the newsrc file. It could prompt the user to reenter the file name. It could assume that the user doesn't have a newsrc file yet. If it doesn't want to handle the error, it could go ahead and die. On the other hand, it is very difficult for a program to do anything sensible if the newsrc file opens successfully and then turns out to contain invalid data. Was there a disk error? Is the file corrupt? Did the user accidentally specify his kill file instead of his newsrc file? And what are you going to do about it? Rather than try to handle an error like this, it's probably better to die and let the user sort things out. By the same rational, save and `save_as' die on failure. Programs that must retain control can use eval{...} to protect calls that may die. For example, Perl/Tk runs all callbacks inside an eval{...}. If a callback dies, Perl/Tk regains control and displays $@ in a dialog box. The user can then decide whether to continue or quit from the program. `import_rc'/`export_rc' ----------------------- I was going to call these methods import and export, but import turns out not to be a good name for a method, because use also calls import, and expects different semantics. I added the `_rc' suffix to import to avoid this conflict. It's reasonably short and somewhat mnemonic (the module manages news*rc* files). I added the same suffix to export for symmetry. AUTHOR ====== Steven McDougall, swmcd@world.std.com SEE ALSO ======== perl(1), Set::IntSpan COPYRIGHT ========= Copyright 1996-1998 by Steven McDougall. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: News/Scan, Next: News/Scan/Article, Prev: News/Newsrc, Up: Module List gather and report Usenet newsgroup statistics ********************************************* NAME ==== News::Scan - gather and report Usenet newsgroup statistics SYNOPSIS ======== use News::Scan; my $scan = News::Scan->new; DESCRIPTION =========== This module provides a class whose objects can be used to gather and report Usenet newsgroup statistics. CONSTRUCTOR =========== new ( [ OPTIONS ] ) OPTIONS is a list of named parameters (i.e. given in key-value pairs). Valid options are Group The value of this option is the name of the newsgroup you wish to scan. From The value of this option should be either `'spool'' or `'NNTP'' (case is not significant). Any other value will produce an error (see the error method description below). A value of `'spool'' indicates that you would like to scan articles in a spool (see the Spool option below). A value of `'NNTP'' indicates that articles should be retrieved from your NNTP server (see the NNTPServer option below). 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 From is `'spool''. NNTPServer The value of this option (in the form server:port, with both being optional-see *Note Net/NNTP: Net/NNTP, for the semantics of omitting one or both of these parameters) indicates the NNTP server from which to retrieve articles. This option is ignored unless From is `'NNTP''. See the description of the NNTPAuthLogin and NNTPAuthPasswd options below. NNTPAuthLogin The value of this option should be a valid NNTP authentication login for your NNTP server. This option is only necessary if your NNTP server requires authentication. NNTPAuthPasswd The value of this option should be the password corresponding to the login in NNTPAuthLogin. Having this hardcoded in a script is evil, and there should be a much better way. 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. 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 `^\s{0,3}(?:'|:|\S+>|\+\+)>. 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. 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. `alias =' 'real@address'>. METHODS ======= configure ( [ OPTIONS ] ) OPTIONS is a list of named parameters identical to those accepted by new. Re-configure-ing an object after scanning is probably a bad idea. This method returns undef if it encounters an error. The following methods are the actual underlying methods used to set and retrieve the configuration options of the same name (modulo case): 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 can be used to retrieve information from the `News::Scan' object or ask it to perform some action. error ( [ MESSAGE ] ) Use this method to determine whether an object has encountered an error condition. The return value of error is guaranteed to be 0 after any method completes successfully (except error). (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. If provided, `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 which has been determined to be original (see QuoteRE). Note that original traffic is a subset of body traffic. orig_lines Returns the number of lines that are 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 method to determine the date (in seconds since the Epoch) that the oldest article found within the period was posted to Usenet. If TIME is given, it is treated as a candidate for the earliest article. If TIME is successful (i.e. is less than the previous earliest), this method returns 1, else 0. 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. If TIME is given, it is treated as a candidate for the latest article. If TIME is successful (i.e. is greater than the previous latest), this method returns 1, else 0. excludes Returns the list of regular expressions used to determine 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 *Note News/Scan/Poster: 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 *Note News/Scan/Thread: 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. EXAMPLES ======== See the `eg/' directory in the *News-Scan* distribution, available from the CPAN-`http://www.perl.com/CPAN/'. SEE ALSO ======== *Note Perlre: (perl.info)perlre,, *Note News/Scan/Poster: News/Scan/Poster,, *Note News/Scan/Thread: News/Scan/Thread,, *Note News/Scan/Article: News/Scan/Article,, *Note Net/NNTP: Net/NNTP, AUTHOR ====== Greg Bacon 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.  File: pm.info, Node: News/Scan/Article, Next: News/Scan/Poster, Prev: News/Scan, Up: Module List collect information about news articles *************************************** NAME ==== News::Scan::Article - collect information about news articles SYNOPSIS ======== use News::Scan::Article; my $art = News::Scan::Article->new( ARG, [ OPTIONS, ] SCAN ); DESCRIPTION =========== This module provides a derived class of Mail::Internet whose objects are suitable for digesting Usenet news articles. CONSTRUCTOR =========== new ( ARG, [ OPTIONS, ] SCAN-OBJ ) The ARG and OPTIONS parameters are identical to those required by Mail::Internet, except ARG is required. See *Note Mail/Internet: Mail/Internet,. The `SCAN' parameter should be a `News::Scan' object. See *Note News/Scan: News/Scan,. If the article falls into the period of interest for `SCAN', the object is returned, else undef. METHODS ======= group ( [ SCAN-OBJ ] ) Sets or returns an object's group depending on whether `SCAN-OBJ' is present. author Returns the article's author represented as a `Mail::Address' object. message_id Returns the article's Message-ID. subject Returns the article's subject. newsgroups Returns the list of newsgroups this article was posted to. size Returns the size of this article in bytes. header_size Returns the size of this article's header in bytes. header_lines Returns the number of lines consumed in this article by headers. body_size Returns the size of this article's body in bytes. body_lines Returns the number of lines consumed in this article by the body. orig_size Returns the size of this article's original content in bytes. See `"QuoteRE"', *Note News/Scan: News/Scan,. orig_lines Returns the number of lines consumed in this article by original content. Keep in mind that original content is a subset of the body. sig_size Returns the size of this article'ss signature in bytes. sig_lines Returns the number of lines consumed in this article by the signature. SEE ALSO ======== *Note News/Scan: News/Scan,, *Note Mail/Internet: Mail/Internet,, *Note Mail/Address: Mail/Address, AUTHOR ====== Greg Bacon 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.  File: pm.info, Node: News/Scan/Poster, Next: News/Scan/Thread, Prev: News/Scan/Article, Up: Module List keep track of posters to a newsgroup ************************************ NAME ==== News::Scan::Poster - keep track of posters to a newsgroup SYNOPSIS ======== use News::Scan::Poster; my $poster = News::Scan::Poster->new($news_scan_article_obj); DESCRIPTION =========== This module provides a class whose objects can be used to keep track of cumulative statistics for posters to a Usenet newsgroup such as header volume or signature lines. CONSTRUCTOR =========== new ( ARTICLE ) `ARTICLE' should be a `News::Scan::Article' object or inherit from the `News::Scan::Article' class. new performs some initialization and returns a `News::Scan::Poster' object. METHODS ======= address ( [ ADDRESS ] ) Returns the address of this poster represented as a Mail::Internet object. If present, `ADDRESS' tells the object that the Mail::Internet object in `ADDRESS' is its address. idea. attrib ( [ ATTRIBUTION ] ) Returns some nice attribution for this poster. If present, `ATTRIBUTION' tells the object how it shall identify itself when asked. message_ids ( [ MESSAGE-ID ] ) Returns a list of Message-IDs attributed to this poster. If present, `MESSAGE-ID' is added to this list of this poster's articles. volume Returns the volume in bytes of the traffic generated by this poster. articles Returns the number of articles attributed to this poster. posted_to Returns a hash whose keys are newsgroup names and whose values are the number of times this poster has crossposted to the group of interest and the corresponding newsgroup. crossposts Returns the total number of crossposts this poster has sent through the group of interest. header_volume Returns the volume in bytes generated by this poster's headers. header_lines Returns the number of header lines generated by this poster. body_volume Returns the volume in bytes generated by this poster's message bodies. body_lines Returns the number of body lines generated by this poster. orig_volume Returns the volume in bytes of original content generated by this poster. orig_lines Returns the number of original lines generated by this poster. sig_volume Returns the volume in bytes generated by this poster's signatures. sig_lines Returns the number of signature lines generated by this poster. SEE ALSO ======== *Note News/Scan: News/Scan,, *Note Mail/Address: Mail/Address,, *Note News/Scan/Article: News/Scan/Article, AUTHOR ====== Greg Bacon 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.