6 @EXPORT = qw(wrap fill);
7 @EXPORT_OK = qw($columns $break $huge);
9 $VERSION = 2005.0824_01;
11 use vars qw($VERSION $columns $debug $break $huge $unexpand $tabstop
12 $separator $separator2);
16 $columns = 76; # <= screen width
19 $huge = 'wrap'; # alternatively: 'die' or 'overflow'
26 use Text::Tabs qw(expand unexpand);
30 my ($ip, $xp, @t) = @_;
32 local($Text::Tabs::tabstop) = $tabstop;
35 my $t = expand(join("", (map { /\s+\z/ ? ( $_ ) : ($_, ' ') } @t), $tail));
37 my $ll = $columns - length(expand($ip)) - 1;
39 my $nll = $columns - length(expand($xp)) - 1;
46 while ($t !~ /\G\s*\Z/gc) {
47 if ($t =~ /\G([^\n]{0,$ll})($break|\n*\z)/xmgc) {
49 ? unexpand($nl . $lead . $1)
52 } elsif ($huge eq 'wrap' && $t =~ /\G([^\n]{$ll})/gc) {
54 ? unexpand($nl . $lead . $1)
56 $remainder = defined($separator2) ? $separator2 : $separator;
57 } elsif ($huge eq 'overflow' && $t =~ /\G([^\n]*?)($break|\z)/xmgc) {
59 ? unexpand($nl . $lead . $1)
62 } elsif ($huge eq 'die') {
63 die "couldn't wrap '$t'";
65 die "This shouldn't happen";
70 $nl = defined($separator2)
78 print "-----------$r---------\n" if $debug;
80 print "Finish up with '$lead'\n" if $debug;
82 $r .= $lead . substr($t, pos($t), length($t)-pos($t))
83 if pos($t) ne length($t);
85 print "-----------$r---------\n" if $debug;;
92 my ($ip, $xp, @raw) = @_;
96 for $pp (split(/\n\s+/, join("\n",@raw))) {
98 my $x = wrap($ip, $xp, $pp);
102 # if paragraph_indent is the same as line_indent,
103 # separate paragraphs with blank lines
105 my $ps = ($ip eq $xp) ? "\n\n" : "\n";
106 return join ($ps, @para);
114 Text::Wrap - line wrapping to form simple paragraphs
122 $initial_tab = "\t"; # Tab before first line
123 $subsequent_tab = ""; # All other lines flush left
125 print wrap($initial_tab, $subsequent_tab, @text);
126 print fill($initial_tab, $subsequent_tab, @text);
128 $lines = wrap($initial_tab, $subsequent_tab, @text);
130 @paragraphs = fill($initial_tab, $subsequent_tab, @text);
134 use Text::Wrap qw(wrap $columns $huge);
136 $columns = 132; # Wrap at 132 characters
145 $Text::Wrap::columns = 72;
146 print wrap('', '', @text);
150 C<Text::Wrap::wrap()> is a very simple paragraph formatter. It formats a
151 single paragraph at a time by breaking lines at word boundaries.
152 Indentation is controlled for the first line (C<$initial_tab>) and
153 all subsequent lines (C<$subsequent_tab>) independently. Please note:
154 C<$initial_tab> and C<$subsequent_tab> are the literal strings that will
155 be used: it is unlikely you would want to pass in a number.
157 Text::Wrap::fill() is a simple multi-paragraph formatter. It formats
158 each paragraph separately and then joins them together when it's done. It
159 will destroy any whitespace in the original text. It breaks text into
160 paragraphs by looking for whitespace after a newline. In other respects
165 C<Text::Wrap::wrap()> has a number of variables that control its behavior.
166 Because other modules might be using C<Text::Wrap::wrap()> it is suggested
167 that you leave these variables alone! If you can't do that, then
168 use C<local($Text::Wrap::VARIABLE) = YOURVALUE> when you change the
169 values so that the original value is restored. This C<local()> trick
170 will not work if you import the variable into your own namespace.
172 Lines are wrapped at C<$Text::Wrap::columns> columns. C<$Text::Wrap::columns>
173 should be set to the full width of your output device. In fact,
174 every resulting line will have length of no more than C<$columns - 1>.
176 It is possible to control which characters terminate words by
177 modifying C<$Text::Wrap::break>. Set this to a string such as
178 C<'[\s:]'> (to break before spaces or colons) or a pre-compiled regexp
179 such as C<qr/[\s']/> (to break before spaces or apostrophes). The
180 default is simply C<'\s'>; that is, words are terminated by spaces.
181 (This means, among other things, that trailing punctuation such as
182 full stops or commas stay with the word they are "attached" to.)
184 Beginner note: In example 2, above C<$columns> is imported into
185 the local namespace, and set locally. In example 3,
186 C<$Text::Wrap::columns> is set in its own namespace without importing it.
188 C<Text::Wrap::wrap()> starts its work by expanding all the tabs in its
189 input into spaces. The last thing it does it to turn spaces back
190 into tabs. If you do not want tabs in your results, set
191 C<$Text::Wrap::unexpand> to a false value. Likewise if you do not
192 want to use 8-character tabstops, set C<$Text::Wrap::tabstop> to
193 the number of characters you do want for your tabstops.
195 If you want to separate your lines with something other than C<\n>
196 then set C<$Text::Wrap::separator> to your preference. This replaces
197 all newlines with C<$Text::Wrap::separator>. If you just to preserve
198 existing newlines but add new breaks with something else, set
199 C<$Text::Wrap::separator2> instead.
201 When words that are longer than C<$columns> are encountered, they
202 are broken up. C<wrap()> adds a C<"\n"> at column C<$columns>.
203 This behavior can be overridden by setting C<$huge> to
204 'die' or to 'overflow'. When set to 'die', large words will cause
205 C<die()> to be called. When set to 'overflow', large words will be
208 Historical notes: 'die' used to be the default value of
209 C<$huge>. Now, 'wrap' is the default value.
213 print wrap("\t","","This is a bit of text that forms
214 a normal book-style paragraph");
218 David Muir Sharnoff <muir@idiom.com> with help from Tim Pierce and
219 many many others. Copyright (C) 1996-2002 David Muir Sharnoff.
220 This module may be modified, used, copied, and redistributed at
221 your own risk. Publicly redistributed modified versions must use