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.
malformed_header()
True once the header section has held a line that is not a header field: one with no colon, with nothing or white space before its colon, or a first line that starts with white space. Such a line is in no header hash, so a verifier must not pass the message and a signer must not sign it.
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 a piece at a time, to the end or until the parser has stopped), 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.