.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mail::DKIM::TextWrap 3"
.TH Mail::DKIM::TextWrap 3 "2012-11-28" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::DKIM::TextWrap \- text wrapping module written for use with DKIM
.SH "SYNOPSIS (FOR MAIL::DKIM USERS)"
.IX Header "SYNOPSIS (FOR MAIL::DKIM USERS)"
.Vb 1
\&  use Mail::DKIM::TextWrap;
.Ve
.PP
Just add the above line to any program that uses Mail::DKIM::Signer
and your signatures will automatically be wrapped to 72 characters.
.SH "SYNOPSIS (FOR OTHER USERS)"
.IX Header "SYNOPSIS (FOR OTHER USERS)"
.Vb 7
\&  my $output = "";
\&  my $tw = Mail::DKIM::TextWrap\->new(
\&                  Margin => 10,
\&                  Output => \e$output,
\&              );
\&  $tw\->add("Mary had a little lamb, whose fleece was white as snow.\en");
\&  $tw\->finish;
\&
\&  print $output;
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
Specifically, it offers the ability to change wrapping options
in the middle of a paragraph. For instance, with a \s-1DKIM\s0 signature:
.PP
.Vb 2
\&  DKIM\-Signature: a=rsa; c=simple; h=first:second:third:fourth;
\&          b=Xr2mo2wmb1LZBwmEJElIPezal7wQQkRQ8WZtxpofkNmXTjXf8y2f0
.Ve
.PP
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.
.SH "TEXT WRAPPING OPTIONS"
.IX Header "TEXT WRAPPING OPTIONS"
Text wrapping options can be specified when calling \fInew()\fR, or
by simply changing the property as needed. For example, to change
the number of characters allowed per line:
.PP
.Vb 1
\&  $tw\->{Margin} = 20;
.Ve
.IP "Break" 4
.IX Item "Break"
a regular expression matching characters where a line break
can be inserted. Line breaks are inserted \s-1AFTER\s0 a matching substring.
The default is \f(CW\*(C`/\es/\*(C'\fR.
.IP "BreakBefore" 4
.IX Item "BreakBefore"
a regular expression matching characters where a line break
can be inserted. Line breaks are inserted \s-1BEFORE\s0 a matching substring.
Usually, you want to use Break, rather than BreakBefore.
The default is \f(CW\*(C`undef\*(C'\fR.
.IP "Margin" 4
.IX 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.
.IP "Separator" 4
.IX Item "Separator"
the text to insert when a linebreak is needed.
The default is \*(L"\en\*(R". If you want to set a following-line indent
(e.g. all lines but the first begin with four spaces),
use something like \*(L"\en    \*(R".
.IP "Swallow" 4
.IX 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 \*(L"space\*(R" 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 \f(CW\*(C`/\es/\*(C'\fR.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "\fInew()\fP \- create a new text-wrapping object"
.IX Subsection "new() - create a new text-wrapping object"
.Vb 4
\&  my $tw = Mail::DKIM::TextWrap\->new(
\&                      Output => \e$output,
\&                      %wrapping_options,
\&                  );
.Ve
.PP
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:
.IP "Output" 4
.IX Item "Output"
a scalar reference, or a glob reference, to specify where the
\&\*(L"wrapped\*(R" text gets output to. If not specified, the default of
\&\s-1STDOUT\s0 is used.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fIadd()\fP \- process some text that can be wrapped"
.IX Subsection "add() - process some text that can be wrapped"
.Vb 1
\&  $tw\->add("Mary had a little lamb.\en");
.Ve
.PP
You can \fIadd()\fR all the text at once, or \fIadd()\fR the text in parts by calling
\&\fIadd()\fR multiple times.
.SS "\fIfinish()\fP \- call when no more text is to be added"
.IX Subsection "finish() - call when no more text is to be added"
.Vb 1
\&  $tw\->finish;
.Ve
.PP
Call this when finished adding text, so that any remaining text
in TextWrap's buffers will be output.
.SS "\fIflush()\fP \- output the current partial word, if any"
.IX Subsection "flush() - output the current partial word, if any"
.Vb 1
\&  $tw\->flush;
.Ve
.PP
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.