.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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
.\" ========================================================================
.\"
.IX Title "Mail::SPF::MacroString 3pm"
.TH Mail::SPF::MacroString 3pm 2023-07-25 "perl v5.38.0" "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::SPF::MacroString \- SPF record macro string class
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.SS "Providing the expansion context early"
.IX Subsection "Providing the expansion context early"
.Vb 1
\&    use Mail::SPF::MacroString;
\&
\&    my $macrostring = Mail::SPF::MacroString\->new(
\&        text    => \*(Aq%{ir}.%{v}._spf.%{d2}\*(Aq,
\&        server  => $server,
\&        request => $request
\&    );
\&
\&    my $expanded = $macrostring\->expand;
.Ve
.SS "Providing the expansion context late"
.IX Subsection "Providing the expansion context late"
.Vb 1
\&    use Mail::SPF::MacroString;
\&
\&    my $macrostring = Mail::SPF::MacroString\->new(
\&        text    => \*(Aq%{ir}.%{v}._spf.%{d2}\*(Aq
\&    );
\&
\&    my $expanded1 = $macrostring\->expand($server, $request1);
\&
\&    $macrostring\->context($server, $request2);
\&    my $expanded2 = $macrostring\->expand;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
An object of class \fBMail::SPF::MacroString\fR represents a macro string that
can be expanded to a plain string in the context of an SPF request.
.SS Constructor
.IX Subsection "Constructor"
The following constructor is provided:
.IP "\fBnew(%options)\fR: returns \fIMail::SPF::MacroString\fR" 4
.IX Item "new(%options): returns Mail::SPF::MacroString"
Creates a new SPF record macro string object.
.Sp
\&\f(CW%options\fR is a list of key/value pairs representing any of the following
options:
.RS 4
.IP \fBtext\fR 4
.IX Item "text"
\&\fIRequired\fR.  The unexpanded text of the new macro string.
.IP \fBserver\fR 4
.IX Item "server"
The \fIMail::SPF::Server\fR object that is to be used when expanding the macro
string.  A server object need not be attached statically to the macro string;
it can be specified dynamically when calling the \f(CW\*(C`expand\*(C'\fR method.
.IP \fBrequest\fR 4
.IX Item "request"
The \fIMail::SPF::Request\fR object that is to be used when expanding the macro
string.  A request object need not be attached statically to the macro string;
it can be specified dynamically when calling the \f(CW\*(C`expand\*(C'\fR method.
.IP \fBis_explanation\fR 4
.IX Item "is_explanation"
A \fIboolean\fR denoting whether the macro string is an explanation string
obtained via an \f(CW\*(C`exp\*(C'\fR modifier.  If \fBtrue\fR, the \f(CW\*(C`c\*(C'\fR, \f(CW\*(C`r\*(C'\fR, and \f(CW\*(C`t\*(C'\fR macros
may appear in the macro string, otherwise they may not, and if they do, a
\&\fIMail::SPF::EInvalidMacro\fR exception will be thrown when the macro string is
expanded.  Defaults to \fBfalse\fR.
.RE
.RS 4
.RE
.SS "Instance methods"
.IX Subsection "Instance methods"
The following instance methods are provided:
.IP "\fBtext\fR: returns \fIstring\fR" 4
.IX Item "text: returns string"
Returns the unexpanded text of the macro string.
.ie n .IP "\fBcontext($server, \fR\fB$request\fR\fB)\fR: throws \fIMail::SPF::EOptionRequired\fR" 4
.el .IP "\fBcontext($server, \fR\f(CB$request\fR\fB)\fR: throws \fIMail::SPF::EOptionRequired\fR" 4
.IX Item "context($server, $request): throws Mail::SPF::EOptionRequired"
Attaches the given \fIMail::SPF::Server\fR and \fIMail::SPF::Request\fR objects as
the context for the macro string.
.IP "\fBexpand\fR: returns \fIstring\fR; throws \fIMail::SPF::EMacroExpansionCtxRequired\fR, \fIMail::SPF::EInvalidMacroString\fR, \fIMail::SPF::Result::PermError\fR" 4
.IX Item "expand: returns string; throws Mail::SPF::EMacroExpansionCtxRequired, Mail::SPF::EInvalidMacroString, Mail::SPF::Result::PermError"
.PD 0
.ie n .IP "\fBexpand($server, \fR\fB$request\fR\fB)\fR: returns \fIstring\fR; throws \fIMail::SPF::EMacroExpansionCtxRequired\fR, \fIMail::SPF::EInvalidMacroString\fR, \fIMail::SPF::Result::PermError\fR" 4
.el .IP "\fBexpand($server, \fR\f(CB$request\fR\fB)\fR: returns \fIstring\fR; throws \fIMail::SPF::EMacroExpansionCtxRequired\fR, \fIMail::SPF::EInvalidMacroString\fR, \fIMail::SPF::Result::PermError\fR" 4
.IX Item "expand($server, $request): returns string; throws Mail::SPF::EMacroExpansionCtxRequired, Mail::SPF::EInvalidMacroString, Mail::SPF::Result::PermError"
.PD
Expands the text of the macro string using either the context specified through
an earlier call to the \f(CWcontext()\fR method, or the given context, and returns
the resulting string.  See RFC 4408, 8, for how macros are expanded.
.IP "\fBis_explanation\fR: returns \fIboolean\fR" 4
.IX Item "is_explanation: returns boolean"
Returns \fBtrue\fR if the macro string is an explanation string obtained via an
\&\f(CW\*(C`exp\*(C'\fR modifier.  See the description of the "new" constructor's
\&\f(CW\*(C`is_explanation\*(C'\fR option.
.IP "\fBstringify\fR: returns \fIstring\fR" 4
.IX Item "stringify: returns string"
Returns the expanded text of the macro string if a context is attached to the
object.  Returns the unexpanded text otherwise.  You can simply use a
Mail::SPF::MacroString object as a string for the same effect, see
"OVERLOADING".
.SH OVERLOADING
.IX Header "OVERLOADING"
If a Mail::SPF::MacroString object is used as a \fIstring\fR, the \f(CW\*(C`stringify\*(C'\fR
method is used to convert the object into a string.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mail::SPF, Mail::SPF::Record, Mail::SPF::Server, Mail::SPF::Request
.PP
<http://tools.ietf.org/html/rfc4408>
.PP
For availability, support, and license information, see the README file
included with Mail::SPF.
.SH AUTHORS
.IX Header "AUTHORS"
Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>