.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "Qpsmtpd::Address 3pm"
.TH Qpsmtpd::Address 3pm "2009-04-02" "perl v5.14.2" "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"
Qpsmtpd::Address \- Lightweight E\-Mail address objects
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Based originally on cut and paste from Mail::Address and including 
every jot and tittle from \s-1RFC\-2821/2822\s0 on what is a legal e\-mail 
address for use during the \s-1SMTP\s0 transaction.
.SH "USAGE"
.IX Header "USAGE"
.Vb 1
\&  my $rcpt = Qpsmtpd::Address\->new(\*(Aq<email.address@example.com>\*(Aq);
.Ve
.PP
The objects created can be used as is, since they automatically 
stringify to a standard form, and they have an overloaded comparison 
for easy testing of values.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fInew()\fP"
.IX Subsection "new()"
Can be called two ways:
.IP "\(bu" 4
Qpsmtpd::Address\->new('<full_address@example.com>')
.Sp
The normal mode of operation is to pass the entire contents of the 
\&\s-1RCPT\s0 \s-1TO:\s0 command from the \s-1SMTP\s0 transaction.  The value will be fully 
parsed via the canonify method, using the full \s-1RFC\s0 2821 rules.
.IP "\(bu" 4
Qpsmtpd::Address\->new(\*(L"user\*(R", \*(L"host\*(R")
.Sp
If the caller has already split the address from the domain/host,
this mode will not canonify the input values.  This is not 
recommended in cases of user-generated input for that reason.  This 
can be used to generate Qpsmtpd::Address objects for accounts like 
\&\*(L"<postmaster>\*(R" or indeed for the bounce address \*(L"<>\*(R".
.PP
The resulting objects can be stored in arrays or used in plugins to 
test for equality (like in badmailfrom).
.SS "\fIcanonify()\fP"
.IX Subsection "canonify()"
Primarily an internal method, it is used only on the path portion of
an e\-mail message, as defined in \s-1RFC\-2821\s0 (this is the part inside the
angle brackets and does not include the \*(L"human readable\*(R" portion of an
address).  It returns a list of (local-part, domain).
.SS "\fIparse()\fP"
.IX Subsection "parse()"
Retained as a compatibility method, it is completely equivalent
to \fInew()\fR called with a single parameter.
.SS "\fIaddress()\fP"
.IX Subsection "address()"
Can be used to reset the value of an existing Q::A object, in which
case it takes a parameter with or without the angle brackets.
.PP
Returns the stringified representation of the address.  \s-1NOTE:\s0 does
not escape any of the characters that need escaping, nor does it
include the surrounding angle brackets.  For that purpose, see
format.
.SS "\fIformat()\fP"
.IX Subsection "format()"
Returns the canonical stringified representation of the address.  It
does escape any characters requiring it (per \s-1RFC\-2821/2822\s0) and it
does include the surrounding angle brackets.  It is also the default
stringification operator, so the following are equivalent:
.PP
.Vb 2
\&  print $rcpt\->format();
\&  print $rcpt;
.Ve
.SS "user([$user])"
.IX Subsection "user([$user])"
Returns the \*(L"localpart\*(R" of the address, per \s-1RFC\-2821\s0, or the portion
before the '@' sign.
.PP
If called with one parameter, the localpart is set and the new value is
returned.
.SS "host([$host])"
.IX Subsection "host([$host])"
Returns the \*(L"domain\*(R" part of the address, per \s-1RFC\-2821\s0, or the portion
after the '@' sign.
.PP
If called with one parameter, the domain is set and the new value is
returned.
.SS "notes($key[,$value])"
.IX Subsection "notes($key[,$value])"
Get or set a note on the address. This is a piece of data that you wish
to attach to the address and read somewhere else. For example you can
use this to pass data between plugins.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2004\-2005 Peter J. Holzer.  See the \s-1LICENSE\s0 file for more 
information.