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>.

