1Mail::DKIM::TextWrap(3)User Contributed Perl DocumentatioMnail::DKIM::TextWrap(3)
2
3
4

NAME

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

SYNOPSIS (FOR MAIL::DKIM USERS)

9         use Mail::DKIM::TextWrap;
10
11       Just add the above line to any program that uses Mail::DKIM::Signer and
12       your signatures will automatically be wrapped to 72 characters.
13

SYNOPSIS (FOR OTHER USERS)

15         my $output = "";
16         my $tw = Mail::DKIM::TextWrap->new(
17                         Margin => 10,
18                         Output => \$output,
19                     );
20         $tw->add("Mary had a little lamb, whose fleece was white as snow.\n");
21         $tw->finish;
22
23         print $output;
24

DESCRIPTION

26       This is a general-purpose text-wrapping module that I wrote because I
27       had some specific needs with Mail::DKIM that none of the contemporary
28       text-wrapping modules offered.
29
30       Specifically, it offers the ability to change wrapping options in the
31       middle of a paragraph. For instance, with a DKIM signature:
32
33         DKIM-Signature: a=rsa; c=simple; h=first:second:third:fourth;
34                 b=Xr2mo2wmb1LZBwmEJElIPezal7wQQkRQ8WZtxpofkNmXTjXf8y2f0
35
36       the line-breaks can be inserted next to any of the colons of the h=
37       tag, or any character of the b= tag. The way I implemented this was to
38       serialize the signature one element at a time, changing the text-
39       wrapping options at the start and end of each tag.
40

TEXT WRAPPING OPTIONS

42       Text wrapping options can be specified when calling new(), or by simply
43       changing the property as needed. For example, to change the number of
44       characters allowed per line:
45
46         $tw->{Margin} = 20;
47
48       Break
49           a regular expression matching characters where a line break can be
50           inserted. Line breaks are inserted AFTER a matching substring.  The
51           default is "/\s/".
52
53       BreakBefore
54           a regular expression matching characters where a line break can be
55           inserted. Line breaks are inserted BEFORE a matching substring.
56           Usually, you want to use Break, rather than BreakBefore.  The
57           default is "undef".
58
59       Margin
60           specifies how many characters to allow per line.  The default is
61           72. If no place to line-break is found on a line, the line will
62           extend beyond this margin.
63
64       Separator
65           the text to insert when a linebreak is needed.  The default is
66           "\n". If you want to set a following-line indent (e.g. all lines
67           but the first begin with four spaces), use something like "\n    ".
68
69       Swallow
70           a regular expression matching characters that can be omitted when a
71           line break occurs. For example, if you insert a line break between
72           two words, then you are replacing a "space" with the line break, so
73           you are omitting the space. On the other hand, if you insert a line
74           break between two parts of a hyphenated word, then you are breaking
75           at the hyphen, but you still want to display the hyphen.  The
76           default is "/\s/".
77

CONSTRUCTOR

79   new() - create a new text-wrapping object
80         my $tw = Mail::DKIM::TextWrap->new(
81                             Output => \$output,
82                             %wrapping_options,
83                         );
84
85       The text-wrapping object encapsulates the current options and the
86       current state of the text stream. In addition to specifying text
87       wrapping options as described in the section above, the following
88       options are recognized:
89
90       Output
91           a scalar reference, or a glob reference, to specify where the
92           "wrapped" text gets output to. If not specified, the default of
93           STDOUT is used.
94

METHODS

96   add() - process some text that can be wrapped
97         $tw->add("Mary had a little lamb.\n");
98
99       You can add() all the text at once, or add() the text in parts by
100       calling add() multiple times.
101
102   finish() - call when no more text is to be added
103         $tw->finish;
104
105       Call this when finished adding text, so that any remaining text in
106       TextWrap's buffers will be output.
107
108   flush() - output the current partial word, if any
109         $tw->flush;
110
111       Call this whenever changing TextWrap's parameters in the middle of a
112       string of words. It explicitly allows a line-break at the current
113       position in the string, regardless of whether it matches the current
114       break pattern.
115
116
117
118perl v5.30.1                      2020-01-30           Mail::DKIM::TextWrap(3)
Impressum