NAME¶

Mail::DKIM::TextWrap - text wrapping module written for use with DKIM

VERSION¶

version 1.20240619

DESCRIPTION¶

This is a general-purpose text-wrapping module that I wrote because I had some specific needs with Mail::DKIM that none of the contemporary text-wrapping modules offered.

Specifically, it offers the ability to change wrapping options in the middle of a paragraph. For instance, with a DKIM signature:

  DKIM-Signature: a=rsa; c=simple; h=first:second:third:fourth;
          b=Xr2mo2wmb1LZBwmEJElIPezal7wQQkRQ8WZtxpofkNmXTjXf8y2f0

the line-breaks can be inserted next to any of the colons of the h= tag, or any character of the b= tag. The way I implemented this was to serialize the signature one element at a time, changing the text-wrapping options at the start and end of each tag.

SYNOPSIS (FOR MAIL::DKIM USERS)¶

  use Mail::DKIM::TextWrap;

Just add the above line to any program that uses Mail::DKIM::Signer and your signatures will automatically be wrapped to 72 characters.

SYNOPSIS (FOR OTHER USERS)¶

  my $output = "";
  my $tw = Mail::DKIM::TextWrap->new(
                  Margin => 10,
                  Output => \$output,
              );
  $tw->add("Mary had a little lamb, whose fleece was white as snow.\n");
  $tw->finish;
  print $output;

TEXT WRAPPING OPTIONS¶

Text wrapping options can be specified when calling new(), or by simply changing the property as needed. For example, to change the number of characters allowed per line:

  $tw->{Margin} = 20;

Break

a regular expression matching characters where a line break can be inserted. Line breaks are inserted AFTER a matching substring. The default is "/\s/".

BreakBefore

a regular expression matching characters where a line break can be inserted. Line breaks are inserted BEFORE a matching substring. Usually, you want to use Break, rather than BreakBefore. The default is "undef".

Margin

specifies how many characters to allow per line. The default is 72. If no place to line-break is found on a line, the line will extend beyond this margin.

Separator

the text to insert when a linebreak is needed. The default is "\n". If you want to set a following-line indent (e.g. all lines but the first begin with four spaces), use something like "\n ".

Swallow

a regular expression matching characters that can be omitted when a line break occurs. For example, if you insert a line break between two words, then you are replacing a "space" with the line break, so you are omitting the space. On the other hand, if you insert a line break between two parts of a hyphenated word, then you are breaking at the hyphen, but you still want to display the hyphen. The default is "/\s/".

CONSTRUCTOR¶

  my $tw = Mail::DKIM::TextWrap->new(
                      Output => \$output,
                      %wrapping_options,
                  );

METHODS¶

  $tw->add("Mary had a little lamb.\n");

  $tw->finish;

  $tw->flush;

AUTHORS¶

• Jason Long <jason@long.name>
• Marc Bradshaw <marc@marcbradshaw.net>
• Bron Gondwana <brong@fastmailteam.com> (ARC)

THANKS¶

Work on ensuring that this module passes the ARC test suite was generously sponsored by Valimail (https://www.valimail.com/)

COPYRIGHT AND LICENSE¶

• Copyright (C) 2013 by Messiah College
• Copyright (C) 2010 by Jason Long
• Copyright (C) 2017 by Standcore LLC
• Copyright (C) 2020 by FastMail Pty Ltd

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.