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

VERSION

9       version 1.20230630
10

DESCRIPTION

12       This is a general-purpose text-wrapping module that I wrote because I
13       had some specific needs with Mail::DKIM that none of the contemporary
14       text-wrapping modules offered.
15
16       Specifically, it offers the ability to change wrapping options in the
17       middle of a paragraph. For instance, with a DKIM signature:
18
19         DKIM-Signature: a=rsa; c=simple; h=first:second:third:fourth;
20                 b=Xr2mo2wmb1LZBwmEJElIPezal7wQQkRQ8WZtxpofkNmXTjXf8y2f0
21
22       the line-breaks can be inserted next to any of the colons of the h=
23       tag, or any character of the b= tag. The way I implemented this was to
24       serialize the signature one element at a time, changing the text-
25       wrapping options at the start and end of each tag.
26

SYNOPSIS (FOR MAIL::DKIM USERS)

28         use Mail::DKIM::TextWrap;
29
30       Just add the above line to any program that uses Mail::DKIM::Signer and
31       your signatures will automatically be wrapped to 72 characters.
32

SYNOPSIS (FOR OTHER USERS)

34         my $output = "";
35         my $tw = Mail::DKIM::TextWrap->new(
36                         Margin => 10,
37                         Output => \$output,
38                     );
39         $tw->add("Mary had a little lamb, whose fleece was white as snow.\n");
40         $tw->finish;
41
42         print $output;
43

TEXT WRAPPING OPTIONS

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

CONSTRUCTOR

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

METHODS

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

AUTHORS

120       •   Jason Long <jason@long.name>
121
122       •   Marc Bradshaw <marc@marcbradshaw.net>
123
124       •   Bron Gondwana <brong@fastmailteam.com> (ARC)
125

THANKS

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

131       •   Copyright (C) 2013 by Messiah College
132
133       •   Copyright (C) 2010 by Jason Long
134
135       •   Copyright (C) 2017 by Standcore LLC
136
137       •   Copyright (C) 2020 by FastMail Pty Ltd
138
139       This library is free software; you can redistribute it and/or modify it
140       under the same terms as Perl itself, either Perl version 5.8.6 or, at
141       your option, any later version of Perl 5 you may have available.
142
143
144
145perl v5.38.0                      2023-07-24           Mail::DKIM::TextWrap(3)
Impressum