/ 
Gateway-0.42
River stage zero No dependents
/ News::Gateway

NAME

News::Gateway - Tools for gatewaying messages between news and mail.

SYNOPSIS

use News::Gateway;
my $gateway = News::Gateway->new (1, 'user@example.com');
$gateway->modules ('headers', mailtonews => ['misc.test']);
$gateway->config_file ('/path/to/config/file');
$gateway->read (\*STDIN);
my $error = $gateway->apply ();
if ($error) { $gateway->error ($error) }
$error = $gateway->post ();
if ($error) { $gateway->error ($error) }

DESCRIPTION

This module is a collection of tools to allow gatewaying of mail messages into newsgroups or vice versa. It's written to be extremely modular and extendable, so that any modification or check of incoming messages can be dropped in. It's intended to be usable for both a straight gateway or a robomoderator, or even as the front end and supporting tool set for human moderation.

The module is intended to take input from three different sources: an incoming message, a set of modules that contain checks or modifications to be performed to that message, and a configuration file that affects the behavior of the modules. Each module can list one or more configuration directives that it takes, and then when those directives are encountered in the configuration file, they're parsed and and handed off to the module. Then, after the message has been read in, its headers and body are given to each module in turn, so that they can perform whatever tests and make whatever modifications they were designed to do.

A message is represented internally as a News::Article object that each module has access to, allowing the headers or body to be read and manipulated.

CONSTRUCTOR

new (INTERACTIVE [, MAINTAINER [, SENDER]])

This builds a new News::Gateway object. INTERACTIVE is a true/false flag specifying whether the program is running interactively. If true, the error() method will call die in the event of an error; otherwise, it will attempt to send mail to the maintainer and the sender of the message. MAINTAINER is the e-mail address of the maintainer of the gateway, defaulting to the user the program is running as if not supplied. SENDER is the envelope sender which should be used for all mail sent through News::Gateway, defaulting to MAINTAINER if not supplied.

METHODS

First, the standard methods in the order in which they are normally called. Some of these methods, like modules(), are normally called only once, while others, like read(), may be called multiple times for multiple incoming messages. You'll almost certainly also want to read about the config(), config_file(), and post() directives below in "UTILITY MODULES".

modules (MODULE [ => ARGUMENTS ] [, ...])

Sets the list of modules that should be applied to each incoming message. The list of modules is cumulative; in other words, modules() can be called multiple times to add more modules to the list of ones which will be applied. This method both adds each supplied module name to the list of modules that will be run if apply() is called with no arguments and sets up callbacks so that any configuration directives that MODULE is interested in will be passed along to it when configuration directives are processed.

Some modules may take arguments; if so, they can be passed in as an anonymous array associated with the module. For example:

$gateway->modules (mailtonews => ['misc.test']);

adds mailtonews to the list of modules and passes in misc.test as an argument to it.

Modules will be run in the order they are given to modules().

modules() should always be called before any call to apply(), config(), or config_file() that those modules are supposed to affect.

read (SOURCE [, MAXSIZE [, MAXHEAD]])

Reads in a new message from the supplied source, which can be a file name, a file handle, or even an anonymous sub which will be called repeatedly for each line of the message until it returns undef. MAXSIZE, if given, specifies the maximum size in bytes of the article body, and MAXHEAD, if given, specifies the maximum size in bytes of the article headers. MAXSIZE defaults to 256KB and MAXHEAD defaults to 8KB.

This method returns the total number of bytes read if successful, or undef in the case of an error.

This method constructs a new News::Article object and calls its method, so it will always support essentially the same arguments as the corresponding News::Article read() method.

apply (MODULES)

This method hands the message off to each module given (if no modules are given, the message is given to each module registered by modules() in the order in which they were given to modules()) and lets them do whatever they wish with the article. If a module returns undef, it's presumed to be successful and the message is given to the next module. If a module returns a string, it's considered to be a failure message and apply() stops.

If all modules succeed, apply() returns undef or the empty list. If a module fails, apply() returns a list consisting of the module which failed and the message it failed with in a list context; or a string consisting of the name of the module, a colon, a space, and the message it failed with in a scalar context.

The calling script should then look at the failure message and take the appropriate action.

The following additional methods are also supplied, some of which are mostly intended for internal use.

error (ERROR)

Handles a fatal error. If the INTERACTIVE flag passed to new() was true, this method just calls die with the error message. Otherwise, it calls mail_error() (part of the standard mail module), which attempts to mail the maintainer and the sender of the message. If that fails, for whatever reason, News::Gateway calls exit with the right status code for a mail bounce.

This method should be used only for fatal, unrecoverable errors, particularly when INTERACTIVE isn't true, since it could bounce mail or notify the wrong person of problems. It's a last resort that goes to great lengths to try to keep the message from being lost.

get_article ()

An accessor method that returns the underlying News::Article object.

set_article (ARTICLE)

Takes a News::Article object and makes that the underlying message in that instance of News::Gateway, discarding the old one if any.

REWRITE MODULES

The following modules to perform checks or rewrites of messages are part of the standard distribution. To use them with a News::Gateway object, pass them (along with anonymous arrays for their options, if any) to the modules() method.

@@ rewrite: This section is automatically generated from pod/*.pod

UTILITY MODULES

The following modules are also part of the standard distribution. Rather than rewrite or check messages, they provide additional methods that can be used by programs, other modules, even or the News::Gateway core code. Methods supplied by utility modules can be called like any other News::Gateway method.

@@ utility: This section is automatically generated from pod/*.pod

DIAGNOSTICS

In addition to the failure messages generated by modules (listed above), the following messages may be generated by the News::Gateway core code and would be passed to the error() method.

Autoload of %s failed: %s

A method was called that doesn't exist in the core code and was unable to be loaded from a module. Chances are you made a typo when referring to a News::Gateway method.

Cannot open file %s: %s

News::Gateway attempted to open a file (probably the configuration file) and failed for the given reason.

Unable to load %s: %s

One of the modules (either rewrite or utility) you used requires an external Perl module and was unable to load it.

Unknown module %s

You told modules() to load a module that has no hooks registered. News::Gateway has to know about every module that it can use; you can't just copy in a new module with the others and have it work. Instead, put the module in the modules directory before the build process.

BUGS

Many. This is an alpha release, with all that's implied by that in terms of bugs, interface instability, and other such concerns. Use at your own risk, but if you encounter a bug please let me know. Patches in particular are gratefully accepted.

NOTES

If you are interested in being notified of new releases, helping with development, developing, testing, or using new modules, or even just getting tips on how to use this module, there is a mailing list available. To subscribe, send mail to majordomo@eyrie.org with:

subscribe gateway-users

in the body.

New patches and modules are always welcome, whether from people on the list or not, and can be mailed to the address listed below.

SEE ALSO

News::Article

AUTHOR

Russ Allbery <rra@stanford.edu>.

HISTORY

News::Gateway started as a simple mail to news Perl script, written right after the cs.utexas.edu mail to news gateway closed and just a quick hack for the use of people who had previously used that gateway to post to rec.arts.comics.creative and alt.comics.lnh. Over time, it became a general mail to news gateway with a fairly broad set of features.

Eventually, it became obvious that it really should have been a module rather than a script, and it also became clear that it could be used as the core of a robomoderator. Since there was no real general-purpose robomoderation software around that was nearly as flexible as I thought a package should be, I decided to be ambitious and try to solve the general problem.

Then I took a complete detour to rewrite the entire thing again to use Andrew Gierth's News::Article class, which is what I should have been doing from the beginning. And now, finally, it's getting closer to what I'd envisioned.