config

This module contains the code for reading and parsing configuration directives and calling the appropriate module callback hooks. Nearly all News::Gateway programs will make use of this module.

WARNING: Information in configuration directives is trusted by modules, and modules may go so far as to eval things from configuration directives as Perl code. This means that anyone who has access to the configuration directives read by this module has as much control over what a program does as someone who can edit the source. Any necessary sanity or security checking on the content of configuration directives must be done before they are passed off to modules, and config_file() does no such checking.

config (DIRECTIVE, ARGUMENT [, ARGUMENT ...])

Calls the registered module callbacks for all modules who have expressed an interest in DIRECTIVE. This bypasses any parsing, and the arguments are given to the callbacks exactly as passed in. DIRECTIVE is case-insensitive.

config_file (FILE | HANDLE)

Reads in configuration directives from the supplied file name or file handle (which can be either an object reference or a reference to a typeglob) until end of file is reached.

Blank lines and lines beginning with a # are ignored. All other lines are parsed into a directive (the first whitespace-separated word) and some number of arguments, and then the parse results are passed along to the module which has registered interest in that directive. If an argument contains embedded whitespace, it can be enclosed in double quotes. A backslash will escape the next character, whatever it is. A line is considered to be continued on the next line if it ends in a backslash, and if the line continuation occurs inside double quotes, a literal newline will be part of the string.

For example, the following configuration directive tells the headers module to add a new header named X-Comment with the content "This is a long comment about this newsgroup":

    header x-comment add \
           "This is a long comment about this newsgroup"

Multiple configuration files can be read by calling config_file() multiple times. One handy trick for simple scripts using News::Gateway is to put the configuration lines at the end of the script after an __END__ and then pass them to News::Gateway with:

    $gateway->config_file (\*DATA);

config_file() should be called before any apply() it is supposed to affect.

config_line (LINE)

Parses and handles a single configuration line, just as if it were read from a file (in fact, config_file() calls this method for each non-blank, non-comment line). This can be used to feed individual configuration lines to the News::Gateway object without having to give it a file or file handle.

config_parse (LINE)

Parses a configuration file line, returning the results as an array. This is the method used by config_file() and config_line() to parse configuration files. This probably isn't generally useful.

These methods adds two additional fatal error messages, which may be passed to error().

Parse error in %s

A configuration line was unable to be parsed. The most likely cause is unbalanced double quotes.

Unknown configuration directive %s

News::Gateway encountered a configuration directive that no module had expressed interest in. Chances are you made a typo in your configuration file or forgot to register a module with modules() that you were planning on using.