---
name: "Mail::SPF::MacroString"
section: "3pm"
platform: "linux"
package: "perl-mail-spf"
version: "3.20260331-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Mail::SPF::MacroString"
---

# Mail::SPF::MacroString(3pm)

SPF record macro string class

## NAME

Mail::SPF::MacroString - SPF record macro string class

## VERSION

version 3.20260331

## SYNOPSIS

### Providing the expansion context early

```
    use Mail::SPF::MacroString;
    my $macrostring = Mail::SPF::MacroString->new(
        text    => '%{ir}.%{v}._spf.%{d2}',
        server  => $server,
        request => $request
    );
    my $expanded = $macrostring->expand;
```

### Providing the expansion context late

```
    use Mail::SPF::MacroString;
    my $macrostring = Mail::SPF::MacroString->new(
        text    => '%{ir}.%{v}._spf.%{d2}'
    );
    my $expanded1 = $macrostring->expand($server, $request1);
    $macrostring->context($server, $request2);
    my $expanded2 = $macrostring->expand;
```

## DESCRIPTION

An object of class **Mail::SPF::MacroString** represents a macro string that can be expanded to a plain string in the context of an SPF request.

### Constructor

The following constructor is provided:

- **new(%options)**: returns *Mail::SPF::MacroString*

  Creates a new SPF record macro string object.

  `%options` is a list of key/value pairs representing any of the following options:

  - **text**

    *Required*.  The unexpanded text of the new macro string.

  - **server**

    The *Mail::SPF::Server* 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 `"expand"` method.

  - **request**

    The *Mail::SPF::Request* 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 `"expand"` method.

  - **is\_explanation**

    A *boolean* denoting whether the macro string is an explanation string obtained via an `"exp"` modifier.  If **true**, the `"c"`, `"r"`, and `"t"` macros may appear in the macro string, otherwise they may not, and if they do, a *Mail::SPF::EInvalidMacro* exception will be thrown when the macro string is expanded.  Defaults to **false**.

### Instance methods

The following instance methods are provided:

- **text**: returns *string*

  Returns the unexpanded text of the macro string.

- **context($server, $request)**: throws *Mail::SPF::EOptionRequired*

  Attaches the given *Mail::SPF::Server* and *Mail::SPF::Request* objects as the context for the macro string.

- **expand**: returns *string*; throws *Mail::SPF::EMacroExpansionCtxRequired*, *Mail::SPF::EInvalidMacroString*, *Mail::SPF::Result::PermError*

  - **expand($server, $request)**: returns *string*; throws *Mail::SPF::EMacroExpansionCtxRequired*, *Mail::SPF::EInvalidMacroString*, *Mail::SPF::Result::PermError*

  Expands the text of the macro string using either the context specified through an earlier call to the `context()` method, or the given context, and returns the resulting string.  See RFC 4408, 8, for how macros are expanded.

- **is\_explanation**: returns *boolean*

  Returns **true** if the macro string is an explanation string obtained via an `"exp"` modifier.  See the description of the "new" constructor's `"is_explanation"` option.

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

## OVERLOADING

If a Mail::SPF::MacroString object is used as a *string*, the `"stringify"` method is used to convert the object into a string.

## SEE ALSO

Mail::SPF, Mail::SPF::Record, Mail::SPF::Server, Mail::SPF::Request

\<http://tools.ietf.org/html/rfc4408\>

For availability, support, and license information, see the README file included with Mail::SPF.

## AUTHORS

Julian Mehnle \<julian@mehnle.net\>, Shevek \<cpan@anarres.org\>