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 <erin@cpanel.net>. COPYRIGHT AND LICENSE This software is released under the same license as Perl itself. Please see the COPYRIGHT and LICENSE files for further details.