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 <[email protected]>.

COPYRIGHT AND LICENSE
   This software is released under the same license as Perl itself.  Please see
   the COPYRIGHT and LICENSE files for further details.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.