.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mail::Alias::Reader 3"
.TH Mail::Alias::Reader 3 "2012-08-16" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::Alias::Reader \- Read aliases(5) and ~/.forward declarations
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&    my $reader = Mail::Alias::Reader\->open(
\&        \*(Aqhandle\*(Aq => \e*STDIN,
\&        \*(Aqmode\*(Aq   => \*(Aqaliases\*(Aq
\&    );
\&
\&    while (my ($name, $destinations) = $reader\->read) {
\&        my @addresses = grep { $_\->is_address } @{$destinations};
\&
\&        print "$name: " . join(\*(Aq, \*(Aq, map { $_\->to_string } @addresses) . "\en";
\&    }
\&
\&    $reader\->close;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Mail::Alias::Reader is a small but oddly flexible module that facilitates the
reading of \fIaliases\fR\|(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.
.PP
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.
.SH "STARTING UP THE MODULE"
.IX Header "STARTING UP THE MODULE"
.IP "Mail::Alias::Reader\->open(%opts)" 4
.IX Item "Mail::Alias::Reader->open(%opts)"
Open a file (\f(CW\*(C`file\*(C'\fR) or stream (\f(CW\*(C`handle\*(C'\fR) based on the values provided in
\&\f(CW%opts\fR, returning a mail alias reader as a result.  A parsing \f(CW\*(C`mode\*(C'\fR can be
supplied; by default, \fIaliases\fR are expected, whereas a \f(CW\*(C`mode\*(C'\fR of \fIforward\fR
can be specified as well.
.SH "READING DECLARATIONS"
.IX Header "READING DECLARATIONS"
.ie n .IP "$reader\->\fIread()\fR" 4
.el .IP "\f(CW$reader\fR\->\fIread()\fR" 4
.IX Item "$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.
.Sp
Depending on the parsing mode, the nature of the returned data will differ.
Each of the following modes will cause \f(CW\*(C`$reader\->read()\*(C'\fR to operate in the
following manners:
.RS 4
.ie n .IP """aliases""" 4
.el .IP "\f(CWaliases\fR" 4
.IX Item "aliases"
When Mail::Alias::Reader is set to read in \f(CW\*(C`aliases\*(C'\fR mode, a plain scalar
value reflecting the name of the alias, followed by an \f(CW\*(C`ARRAY\*(C'\fR reference
containing mail destinations, is returned, in list context.
.Sp
.Vb 1
\&    my ($name, $destinations) = $reader\->read;
.Ve
.ie n .IP """forward""" 4
.el .IP "\f(CWforward\fR" 4
.IX Item "forward"
.Vb 1
\&    my $destinations = $reader\->read;
.Ve
.Sp
When Mail::Alias::Reader is set to read in \f(CW\*(C`forward\*(C'\fR mode, an \f(CW\*(C`ARRAY\*(C'\fR
reference containing mail destinations is returned in a single scalar.
.RE
.RS 4
.RE
.SH "THE MAIL DESTINATION TOKEN"
.IX Header "THE MAIL DESTINATION TOKEN"
Mail destination objects returned by \f(CW\*(C`$reader\->read()\*(C'\fR are \f(CW\*(C`HASH\*(C'\fR objects
\&\fIbless()\fRed 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.
.PP
The mail destination attributes include:
.ie n .IP """type""" 4
.el .IP "\f(CWtype\fR" 4
.IX Item "type"
The type of token dealt with.  This can be one of \fIT_ADDRESS\fR, \fIT_COMMAND\fR,
\&\fIT_FILE\fR, or \fIT_DIRECTIVE\fR.
.RS 4
.IP "\fIT_ADDRESS\fR" 4
.IX Item "T_ADDRESS"
A mail destination token of type \fIT_ADDRESS\fR may indicate either a full mail
address, or a local part.
.IP "\fIT_COMMAND\fR" 4
.IX Item "T_COMMAND"
A destination token of type \fIT_COMMAND\fR indicates that mail destined for the
current alias is to be \fIpipe()\fRd to the specified command.
.IP "\fIT_FILE\fR" 4
.IX Item "T_FILE"
Any mail destined for the current alias will be appended to the file indicated
by this destination token.
.IP "\fIT_DIRECTIVE\fR" 4
.IX Item "T_DIRECTIVE"
Indicates any special destination in the format of \f(CW\*(C`:directive:\f(CIargument\f(CW\*(C'\fR.
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
\&\f(CW\*(C`name\*(C'\fR attribute.
.RE
.RS 4
.RE
.ie n .IP """value""" 4
.el .IP "\f(CWvalue\fR" 4
.IX Item "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, \fIT_COMMAND\fR destinations do not include the pipe ('|') symbol as a
prefix; this is implied in the destination token type, rather.
.ie n .IP """name""" 4
.el .IP "\f(CWname\fR" 4
.IX Item "name"
Only appears in the prsence of a token typed \fIT_DIRECTIVE\fR  When a mail alias
destination in the form of \f(CW\*(C`:directive:\f(CIargument\f(CW\*(C'\fR is parsed, this contains
the name of the '\f(CW\*(C`directive\*(C'\fR' portion.  Of course, the value in the
\&'\fIargument\fR' portion is contained in the token's \f(CW\*(C`value\*(C'\fR field, but is
considered optional, especially in the presence of a directive such as \f(CW\*(C`:fail\*(C'\fR.
.SH "CLOSING THE STREAM"
.IX Header "CLOSING THE STREAM"
.ie n .IP "$reader\->\fIclose()\fR" 4
.el .IP "\f(CW$reader\fR\->\fIclose()\fR" 4
.IX Item "$reader->close()"
Close the current file stream.  Any subsequent \f(CW\*(C`$reader\->read()\*(C'\fR calls will
return nothing.
.SH "ERROR HANDLING"
.IX Header "ERROR HANDLING"
\&\fICarp::confess()\fR is used internally for passing any error conditions detected
during the runtime of this module.
.SH "AUTHOR"
.IX Header "AUTHOR"
Written and maintained by Erin Schoenhals <erin@cpanel.net>.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2012, cPanel, Inc.
All rights reserved.
http://cpanel.net/
.PP
This is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.  See the \s-1LICENSE\s0 file for further details.