/usr/share/perl5/Mail/DKIM/TextWrap.pm is in libmail-dkim-perl 0.39-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 | #!/usr/bin/perl
use strict;
use warnings;
package Mail::DKIM::TextWrap;
use Carp;
=head1 NAME
Mail::DKIM::TextWrap - text wrapping module written for use with DKIM
=head1 SYNOPSIS (FOR MAIL::DKIM USERS)
use Mail::DKIM::TextWrap;
Just add the above line to any program that uses L<Mail::DKIM::Signer>
and your signatures will automatically be wrapped to 72 characters.
=head1 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;
=head1 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.
=head1 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;
=over
=item Break
a regular expression matching characters where a line break
can be inserted. Line breaks are inserted AFTER a matching substring.
The default is C</\s/>.
=item 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 C<undef>.
=item 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.
=item 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 ".
=item 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 C</\s/>.
=back
=head1 CONSTRUCTOR
=head2 new() - create a new text-wrapping object
my $tw = Mail::DKIM::TextWrap->new(
Output => \$output,
%wrapping_options,
);
The text-wrapping object encapsulates the current options and the
current state of the text stream. In addition to specifying text
wrapping options as described in the section above, the following
options are recognized:
=over
=item Output
a scalar reference, or a glob reference, to specify where the
"wrapped" text gets output to. If not specified, the default of
STDOUT is used.
=back
=cut
sub new
{
my $class = shift;
my %args = @_;
my $self = {
Margin => 72,
Break => qr/\s/,
BreakBefore => undef,
Swallow => qr/\s/,
Separator => "\n",
cur => 0,
may_break => 0,
soft_space => "",
word => "",
%args,
};
$self->{Output} ||= \*STDOUT;
return bless $self, $class;
}
# Internal properties:
#
# cur - the last known column position
#
# may_break - nonzero if the current location allows a linebreak
#
# soft_space - contains added text that will not be printed if a linebreak
# occurs
#
# word - contains the current word
# Internal methods:
#
# _calculate_new_column() - determine where cur would be after adding some text
#
# my $new_cur = _calculate_new_column($cur, "some additional\ntext");
#
sub _calculate_new_column
{
my ($cur, $text) = @_;
confess "invalid argument" unless defined($text);
while ($text =~ /^(.*?)([\n\r\t])(.*)$/s)
{
$cur += length($1);
if ($2 eq "\t")
{
$cur = (int($cur / 8) + 1) * 8;
}
else
{
$cur = 0;
}
$text = $3;
}
$cur += length($text);
return $cur;
}
=head1 METHODS
=head2 add() - process some text that can be wrapped
$tw->add("Mary had a little lamb.\n");
You can add() all the text at once, or add() the text in parts by calling
add() multiple times.
=cut
sub add
{
my ($self, $text) = @_;
my $break_after = $self->{Break};
my $break_before = $self->{BreakBefore};
my $swallow = $self->{Swallow};
$self->{word} .= $text;
while (length $self->{word})
{
my $word;
if (defined($break_before) and $self->{word} =~ s/^(.+?)($break_before)/$2/s)
{
# note- $1 should have at least one character
$word = $1;
}
elsif (defined($break_after) and $self->{word} =~ s/^(.*?)($break_after)//s)
{
$word = $1 . $2;
}
elsif ($self->{NoBuffering})
{
$word = $self->{word};
$self->{word} = "";
}
else
{
last;
}
die "assertion failed" unless length($word) >= 1;
my $next_soft_space;
if (defined($swallow) && $word =~ s/($swallow)$//s)
{
$next_soft_space = $1;
}
else
{
$next_soft_space = "";
}
my $to_print = $self->{soft_space} . $word;
my $new_pos = _calculate_new_column($self->{cur}, $to_print);
if ($new_pos > $self->{Margin} && $self->{may_break})
{
# what would happen if we put the separator in?
my $w_sep = _calculate_new_column($self->{cur},
$self->{Separator});
if ($w_sep < $self->{cur})
{
# inserting the separator gives us more room,
# so do it
$self->output($self->{Separator});
$self->{soft_space} = "";
$self->{cur} = $w_sep;
$self->{word} = $word . $next_soft_space . $self->{word};
next;
}
}
$self->output($to_print);
$self->{soft_space} = $next_soft_space;
$self->{cur} = $new_pos;
$self->{may_break} = 1;
}
}
=head2 finish() - call when no more text is to be added
$tw->finish;
Call this when finished adding text, so that any remaining text
in TextWrap's buffers will be output.
=cut
sub finish
{
my $self = shift;
$self->flush;
$self->reset;
}
=head2 flush() - output the current partial word, if any
$tw->flush;
Call this whenever changing TextWrap's parameters in the middle
of a string of words. It explicitly allows a line-break at the
current position in the string, regardless of whether it matches
the current break pattern.
=cut
sub flush
{
my $self = shift;
local $self->{NoBuffering} = 1;
local $self->{Swallow} = undef;
$self->add("");
}
sub output
{
my $self = shift;
my $to_print = shift;
my $out = $self->{Output};
if (UNIVERSAL::isa($out, "GLOB"))
{
print $out $to_print;
}
elsif (UNIVERSAL::isa($out, "SCALAR"))
{
$$out .= $to_print;
}
}
sub reset
{
my $self = shift;
$self->{cur} = 0;
$self->{soft_space} = "";
$self->{word} = "";
}
1;
|