3 use warnings::register;
7 @EXPORT = qw(wrap fill);
8 @EXPORT_OK = qw($columns $break $huge);
12 use vars qw($VERSION $columns $debug $break $huge $unexpand $tabstop
13 $separator $separator2);
17 $columns = 76; # <= screen width
20 $huge = 'wrap'; # alternatively: 'die' or 'overflow'
27 use Text::Tabs qw(expand unexpand);
31 my ($ip, $xp, @t) = @_;
33 local($Text::Tabs::tabstop) = $tabstop;
36 my $t = expand(join("", (map { /\s+\z/ ? ( $_ ) : ($_, ' ') } @t), $tail));
38 my $ll = $columns - length(expand($ip)) - 1;
40 my $nll = $columns - length(expand($xp)) - 1;
47 while ($t !~ /\G(?:$break)*\Z/gc) {
48 if ($t =~ /\G([^\n]{0,$ll})($break|\n+|\z)/xmgc) {
50 ? unexpand($nl . $lead . $1)
53 } elsif ($huge eq 'wrap' && $t =~ /\G([^\n]{$ll})/gc) {
55 ? unexpand($nl . $lead . $1)
57 $remainder = defined($separator2) ? $separator2 : $separator;
58 } elsif ($huge eq 'overflow' && $t =~ /\G([^\n]*?)($break|\n+|\z)/xmgc) {
60 ? unexpand($nl . $lead . $1)
63 } elsif ($huge eq 'die') {
64 die "couldn't wrap '$t'";
65 } elsif ($columns < 2) {
66 warnings::warnif "Increasing \$Text::Wrap::columns from $columns to 2";
68 return ($ip, $xp, @t);
70 die "This shouldn't happen";
75 $nl = defined($separator2)
83 print "-----------$r---------\n" if $debug;
85 print "Finish up with '$lead'\n" if $debug;
87 $r .= $lead . substr($t, pos($t), length($t)-pos($t))
88 if pos($t) ne length($t);
90 print "-----------$r---------\n" if $debug;;
97 my ($ip, $xp, @raw) = @_;
101 for $pp (split(/\n\s+/, join("\n",@raw))) {
103 my $x = wrap($ip, $xp, $pp);
107 # if paragraph_indent is the same as line_indent,
108 # separate paragraphs with blank lines
110 my $ps = ($ip eq $xp) ? "\n\n" : "\n";
111 return join ($ps, @para);
119 Text::Wrap - line wrapping to form simple paragraphs
127 $initial_tab = "\t"; # Tab before first line
128 $subsequent_tab = ""; # All other lines flush left
130 print wrap($initial_tab, $subsequent_tab, @text);
131 print fill($initial_tab, $subsequent_tab, @text);
133 $lines = wrap($initial_tab, $subsequent_tab, @text);
135 @paragraphs = fill($initial_tab, $subsequent_tab, @text);
139 use Text::Wrap qw(wrap $columns $huge);
141 $columns = 132; # Wrap at 132 characters
150 $Text::Wrap::columns = 72;
151 print wrap('', '', @text);
155 C<Text::Wrap::wrap()> is a very simple paragraph formatter. It formats a
156 single paragraph at a time by breaking lines at word boundaries.
157 Indentation is controlled for the first line (C<$initial_tab>) and
158 all subsequent lines (C<$subsequent_tab>) independently. Please note:
159 C<$initial_tab> and C<$subsequent_tab> are the literal strings that will
160 be used: it is unlikely you would want to pass in a number.
162 Text::Wrap::fill() is a simple multi-paragraph formatter. It formats
163 each paragraph separately and then joins them together when it's done. It
164 will destroy any whitespace in the original text. It breaks text into
165 paragraphs by looking for whitespace after a newline. In other respects
168 Both C<wrap()> and C<fill()> return a single string.
172 C<Text::Wrap::wrap()> has a number of variables that control its behavior.
173 Because other modules might be using C<Text::Wrap::wrap()> it is suggested
174 that you leave these variables alone! If you can't do that, then
175 use C<local($Text::Wrap::VARIABLE) = YOURVALUE> when you change the
176 values so that the original value is restored. This C<local()> trick
177 will not work if you import the variable into your own namespace.
179 Lines are wrapped at C<$Text::Wrap::columns> columns. C<$Text::Wrap::columns>
180 should be set to the full width of your output device. In fact,
181 every resulting line will have length of no more than C<$columns - 1>.
183 It is possible to control which characters terminate words by
184 modifying C<$Text::Wrap::break>. Set this to a string such as
185 C<'[\s:]'> (to break before spaces or colons) or a pre-compiled regexp
186 such as C<qr/[\s']/> (to break before spaces or apostrophes). The
187 default is simply C<'\s'>; that is, words are terminated by spaces.
188 (This means, among other things, that trailing punctuation such as
189 full stops or commas stay with the word they are "attached" to.)
191 Beginner note: In example 2, above C<$columns> is imported into
192 the local namespace, and set locally. In example 3,
193 C<$Text::Wrap::columns> is set in its own namespace without importing it.
195 C<Text::Wrap::wrap()> starts its work by expanding all the tabs in its
196 input into spaces. The last thing it does it to turn spaces back
197 into tabs. If you do not want tabs in your results, set
198 C<$Text::Wrap::unexpand> to a false value. Likewise if you do not
199 want to use 8-character tabstops, set C<$Text::Wrap::tabstop> to
200 the number of characters you do want for your tabstops.
202 If you want to separate your lines with something other than C<\n>
203 then set C<$Text::Wrap::separator> to your preference. This replaces
204 all newlines with C<$Text::Wrap::separator>. If you just to preserve
205 existing newlines but add new breaks with something else, set
206 C<$Text::Wrap::separator2> instead.
208 When words that are longer than C<$columns> are encountered, they
209 are broken up. C<wrap()> adds a C<"\n"> at column C<$columns>.
210 This behavior can be overridden by setting C<$huge> to
211 'die' or to 'overflow'. When set to 'die', large words will cause
212 C<die()> to be called. When set to 'overflow', large words will be
215 Historical notes: 'die' used to be the default value of
216 C<$huge>. Now, 'wrap' is the default value.
222 print wrap("\t","",<<END);
223 This is a bit of text that forms
224 a normal book-style indented paragraph
229 " This is a bit of text that forms
230 a normal book-style indented paragraph
235 $Text::Wrap::columns=20;
236 $Text::Wrap::separator="|";
237 print wrap("","","This is a bit of text that forms a normal book-style paragraph");
241 "This is a bit of|text that forms a|normal book-style|paragraph"
245 David Muir Sharnoff <muir@idiom.com> with help from Tim Pierce and
246 many many others. Copyright (C) 1996-2006 David Muir Sharnoff.
247 This module may be modified, used, copied, and redistributed at
248 your own risk. Publicly redistributed modified versions must use