NAME
Mail::Alias::Reader - Read aliases(5) and ~/.forward declarations
SYNOPSIS
my $reader = Mail::Alias::Reader->open(
'handle' => \*STDIN,
'mode' => 'aliases'
);
while (my ($name, $destinations) = $reader->read) {
my @addresses = grep { $_->is_address } @{$destinations};
print "$name: " . join(', ', map { $_->to_string } @addresses) . "\n";
}
$reader->close;
DESCRIPTION
Mail::Alias::Reader is a small but oddly flexible module that
facilitates the reading of aliases(5)-style mail alias and ~/.forward
declarations. It does not directly provide support for the writing and
in-memory manipulation of these files as a whole, however its limited
feature set may be considered to be a virtue.
The module can read mail aliases or ~/.forward declarations from a file,
or from an arbitrary file handle, as specified at the time of file
reader instantiation. The destination objects returned are the same
parser tokens used internally, keeping code footprint low without being
too much of a hassle.
STARTING UP THE MODULE
Mail::Alias::Reader->open(%opts)
Open a file ("file") or stream ("handle") based on the values
provided in %opts, returning a mail alias reader as a result. A
parsing "mode" can be supplied; by default, *aliases* are expected,
whereas a "mode" of *forward* can be specified as well.
READING DECLARATIONS
$reader->read()
Seeks the current file stream for the next available declaration,
and passes it through the parser, returning the data given by the
parser, without any further manipulation.
Depending on the parsing mode, the nature of the returned data will
differ. Each of the following modes will cause "$reader->read()" to
operate in the following manners:
"aliases"
When Mail::Alias::Reader is set to read in "aliases" mode, a
plain scalar value reflecting the name of the alias, followed by
an "ARRAY" reference containing mail destinations, is returned,
in list context.
my ($name, $destinations) = $reader->read;
"forward"
my $destinations = $reader->read;
When Mail::Alias::Reader is set to read in "forward" mode, an
"ARRAY" reference containing mail destinations is returned in a
single scalar.
THE MAIL DESTINATION TOKEN
Mail destination objects returned by "$reader->read()" are "HASH"
objects bless()ed into the Mail::Alias::Reader::Token package, and
contain a small handful of data attributes, but can be inspected with a
variety of helper functions in the form of instance methods. Please see
the Mail::Alias::Reader::Token documentation for a listing of these
helper functions.
The mail destination attributes include:
"type"
The type of token dealt with. This can be one of *T_ADDRESS*,
*T_COMMAND*, *T_FILE*, or *T_DIRECTIVE*.
*T_ADDRESS*
A mail destination token of type *T_ADDRESS* may indicate either
a full mail address, or a local part.
*T_COMMAND*
A destination token of type *T_COMMAND* indicates that mail
destined for the current alias is to be pipe()d to the specified
command.
*T_FILE*
Any mail destined for the current alias will be appended to the
file indicated by this destination token.
*T_DIRECTIVE*
Indicates any special destination in the format of
":directive:*argument*". These are of course specific to the
system's configured mail transfer agent. In this case, the name
of the directive is captured in the token object's "name"
attribute.
"value"
The textual value of the mail destination, parsed, cleansed of
escape sequences that may have been present in the source file,
containing only the data that is uniquely specified by the type of
mail destination token given. As an example, *T_COMMAND*
destinations do not include the pipe ('|') symbol as a prefix; this
is implied in the destination token type, rather.
"name"
Only appears in the prsence of a token typed *T_DIRECTIVE* When a
mail alias destination in the form of ":directive:*argument*" is
parsed, this contains the name of the '"directive"' portion. Of
course, the value in the '*argument*' portion is contained in the
token's "value" field.
CLOSING THE STREAM
$reader->close()
Close the current file stream. Any subsequent "$reader->read()"
calls will return nothing.
ERROR HANDLING
Carp::confess() is used internally for passing any error conditions
detected during the runtime of this module.
AUTHOR
Written and maintained by Erin Schoenhals .
COPYRIGHT AND LICENSE
This software is released under the same license as Perl itself. Please see
the COPYRIGHT and LICENSE files for further details.