1Mail::DKIM::TextWrap(3)User Contributed Perl DocumentatioMnail::DKIM::TextWrap(3)
2
6 Mail::DKIM::TextWrap - text wrapping module written for use with DKIM
7
9 my $output = "";
10 my $tw = Mail::DKIM::TextWrap->new(
11 Margin => 10,
12 Output => \$output,
13 );
14 $tw->add("Mary had a little lamb, whose fleece was white as snow.\n");
15 $tw->finish;
16 print $output;
18
20 This is a general-purpose text-wrapping module that I wrote because I
21 had some specific needs with Mail::DKIM that none of the contemporary
22 text-wrapping modules offered.
23 Specifically, it offers the ability to change wrapping options in the
25 middle of a paragraph. For instance, with a DKIM signature:
26 DKIM-Signature: a=rsa; c=simple; h=first:second:third:fourth;
28 b=Xr2mo2wmb1LZBwmEJElIPezal7wQQkRQ8WZtxpofkNmXTjXf8y2f0
29 the line-breaks can be inserted next to any of the colons of the h=
31 tag, or any character of the b= tag. The way I implemented this was to
32 serialize the signature one element at a time, changing the text-
33 wrapping options at the start and end of each tag.
34
36 Text wrapping options can be specified when calling new(), or by simply
37 changing the property as needed. For example, to change the number of
38 characters allowed per line:
39 $tw->{Margin} = 20;
41 Break
43 a regular expression matching characters where a line break can be
44 inserted. Line breaks are inserted AFTER a matching substring. The
45 default is "/\s/".
46 BreakBefore
48 a regular expression matching characters where a line break can be
49 inserted. Line breaks are inserted BEFORE a matching substring.
50 Usually, you want to use Break, rather than BreakBefore. The
51 default is "undef".
52 Margin
54 specifies how many characters to allow per line. The default is
55 72. If no place to line-break is found on a line, the line will
56 extend beyond this margin.
57 Separator
59 the text to insert when a linebreak is needed. The default is
60 "\n". If you want to set a following-line indent (e.g. all lines
61 but the first begin with four spaces), use something like "\n ".
62 Swallow
64 a regular expression matching characters that can be omitted when a
65 line break occurs. For example, if you insert a line break between
66 two words, then you are replacing a "space" with the line break, so
67 you are omitting the space. On the other hand, if you insert a line
68 break between two parts of a hyphenated word, then you are breaking
69 at the hyphen, but you still want to display the hyphen. The
70 default is "/\s/".
71
73 new() - create a new text-wrapping object
74 my $tw = Mail::DKIM::TextWrap->new(
75 Output => \$output,
76 %wrapping_options,
77 );
78 The text-wrapping object encapsulates the current options and the
80 current state of the text stream. In addition to specifying text
81 wrapping options as described in the section above, the following
82 options are recognized:
83 Output
85 a scalar reference, or a glob reference, to specify where the
86 "wrapped" text gets output to. If not specified, the default of
87 STDOUT is used.
88
90 add() - process some text that can be wrapped
91 $tw->add("Mary had a little lamb.\n");
92 You can add() all the text at once, or add() the text in parts by
94 calling add() multiple times.
95 finish() - call when no more text is to be added
97 $tw->finish;
98 Call this when finished adding text, so that any remaining text in
100 TextWrap's buffers will be output.
101 flush() - output the current partial word, if any
103 $tw->flush;
104 Call this whenever changing TextWrap's parameters in the middle of a
106 string of words. It explicitly allows a line-break at the current
107 position in the string, regardless of whether it matches the current
108 break pattern.
109perl v5.10.1 2009-07-30 Mail::DKIM::TextWrap(3)