NAME
Mail::DKIM2::HeaderParser - Streaming message parser base for Signer and Verifier
SYNOPSIS
# As a user of a Signer or Verifier:
$obj->PRINT($chunk) for @chunks; # CRLF line endings
$obj->CLOSE;
$obj->load($message); # one shot; LF is normalised
tie *FH, 'Mail::DKIM2::Verifier', SkipTimestampCheck => 1;
print FH $message;
close FH;
my $verifier = tied *FH;
# As a subclass:
package My::Parser;
use parent 'Mail::DKIM2::HeaderParser';
sub known_options { qw(Thing) }
sub handle_header { my ($self, $name, $value, $raw) = @_; ... }
sub finish_header { my $self = shift; ... }
sub finish_body { my $self = shift; ... }DESCRIPTION
Collects a message fed in pieces, splits it into header fields and body, and calls the subclass at each stage. Mail::DKIM2::Signer and Mail::DKIM2::Verifier are built on it; the conventions it implements are described in "CONVENTIONS" in Mail::DKIM2.
CONSTRUCTOR
new(%options)
Croaks on an option the class's known_options does not list, then calls init.
TIEHANDLE
tie *FH, $class, %options constructs an object; tie *FH, $class, $object uses an existing one. print FH, printf FH, syswrite FH and close FH then call PRINT, PRINTF, WRITE and CLOSE.
METHODS
PRINT(@bytes)
Feeds message data, in chunks of any size, with CRLF line endings exactly as the message has them; several arguments are concatenated. When the blank line ending the headers has been seen, the header fields are parsed and finish_header is called. Body data is kept until CLOSE unless the subclass has called stop.
CLOSE()
Ends the message. Parses the headers if no blank line was seen, then calls finish_body unless stop was called.
load($input)
PRINT and CLOSE in one call. $input is the message as a string, a reference to one, a filehandle (read to the end), or an Email::MIME; any other reference croaks. Bare LF line endings are normalised to CRLF first, since every DKIM2 hash is defined over CRLF. Returns the object.
stop()
For a subclass that has reached its result from the headers alone, called from finish_header: the rest of the message is discarded unread and CLOSE does not call finish_body.
stopped()
True after stop.
SUBCLASS INTERFACE
known_options()
The list of CamelCase option names new accepts. Default none.
init()
Called by new after the options are stored in the object hash. Sets up the buffer and $self->{headers}, the arrayref of raw header lines in message order. A subclass that overrides it calls $self->SUPER::init.
handle_header($name, $value, $raw)
Called for each header field: its name, its value without the trailing line ending, and its complete raw text including any continuation lines.
finish_header()
Called once all header fields have been parsed.
finish_body()
Called from CLOSE, with the body in $self->{_buf}.
AUTHOR
Bron Gondwana <brong@fastmailteam.com>
COPYRIGHT AND LICENSE
Copyright (c) 2025-2026 Fastmail Pty Ltd. This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.