This file is indexed.

/usr/share/perl5/Mail/DKIM/TextWrap.pm is in libmail-dkim-perl 0.44-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;