6 @EXPORT = qw(wrap fill);
7 @EXPORT_OK = qw($columns $break $huge);
11 use vars qw($VERSION $columns $debug $break $huge $unexpand $tabstop
16 $columns = 76; # <= screen width
19 $huge = 'wrap'; # alternatively: 'die' or 'overflow'
25 use Text::Tabs qw(expand unexpand);
29 my ($ip, $xp, @t) = @_;
31 local($Text::Tabs::tabstop) = $tabstop;
34 my $t = expand(join("", (map { /\s+\z/ ? ( $_ ) : ($_, ' ') } @t), $tail));
36 my $ll = $columns - length(expand($ip)) - 1;
38 my $nll = $columns - length(expand($xp)) - 1;
45 while ($t !~ /\G\s*\Z/gc) {
46 if ($t =~ /\G([^\n]{0,$ll})($break|\n*\z)/xmgc) {
48 ? unexpand($nl . $lead . $1)
51 } elsif ($huge eq 'wrap' && $t =~ /\G([^\n]{$ll})/gc) {
53 ? unexpand($nl . $lead . $1)
55 $remainder = $separator;
56 } elsif ($huge eq 'overflow' && $t =~ /\G([^\n]*?)($break|\z)/xmgc) {
58 ? unexpand($nl . $lead . $1)
61 } elsif ($huge eq 'die') {
62 die "couldn't wrap '$t'";
64 die "This shouldn't happen";
73 print "-----------$r---------\n" if $debug;
75 print "Finish up with '$lead'\n" if $debug;
77 $r .= $lead . substr($t, pos($t), length($t)-pos($t))
78 if pos($t) ne length($t);
80 print "-----------$r---------\n" if $debug;;
87 my ($ip, $xp, @raw) = @_;
91 for $pp (split(/\n\s+/, join("\n",@raw))) {
93 my $x = wrap($ip, $xp, $pp);
97 # if paragraph_indent is the same as line_indent,
98 # separate paragraphs with blank lines
100 my $ps = ($ip eq $xp) ? "\n\n" : "\n";
101 return join ($ps, @para);
109 Text::Wrap - line wrapping to form simple paragraphs
117 $initial_tab = "\t"; # Tab before first line
118 $subsequent_tab = ""; # All other lines flush left
120 print wrap($initial_tab, $subsequent_tab, @text);
121 print fill($initial_tab, $subsequent_tab, @text);
123 $lines = wrap($initial_tab, $subsequent_tab, @text);
125 @paragraphs = fill($initial_tab, $subsequent_tab, @text);
129 use Text::Wrap qw(wrap $columns $huge);
131 $columns = 132; # Wrap at 132 characters
140 $Text::Wrap::columns = 72;
141 print wrap('', '', @text);
145 C<Text::Wrap::wrap()> is a very simple paragraph formatter. It formats a
146 single paragraph at a time by breaking lines at word boundries.
147 Indentation is controlled for the first line (C<$initial_tab>) and
148 all subsequent lines (C<$subsequent_tab>) independently. Please note:
149 C<$initial_tab> and C<$subsequent_tab> are the literal strings that will
150 be used: it is unlikley you would want to pass in a number.
152 Text::Wrap::fill() is a simple multi-paragraph formatter. It formats
153 each paragraph separately and then joins them together when it's done. It
154 will destroy any whitespace in the original text. It breaks text into
155 paragraphs by looking for whitespace after a newline. In other respects
160 C<Text::Wrap::wrap()> has a number of variables that control its behavior.
161 Because other modules might be using C<Text::Wrap::wrap()> it is suggested
162 that you leave these variables alone! If you can't do that, then
163 use C<local($Text::Wrap::VARIABLE) = YOURVALUE> when you change the
164 values so that the original value is restored. This C<local()> trick
165 will not work if you import the variable into your own namespace.
167 Lines are wrapped at C<$Text::Wrap::columns> columns. C<$Text::Wrap::columns>
168 should be set to the full width of your output device. In fact,
169 every resulting line will have length of no more than C<$columns - 1>.
171 It is possible to control which characters terminate words by
172 modifying C<$Text::Wrap::break>. Set this to a string such as
173 C<'[\s:]'> (to break before spaces or colons) or a pre-compiled regexp
174 such as C<qr/[\s']/> (to break before spaces or apostrophes). The
175 default is simply C<'\s'>; that is, words are terminated by spaces.
176 (This means, among other things, that trailing punctuation such as
177 full stops or commas stay with the word they are "attached" to.)
179 Beginner note: In example 2, above C<$columns> is imported into
180 the local namespace, and set locally. In example 3,
181 C<$Text::Wrap::columns> is set in its own namespace without importing it.
183 C<Text::Wrap::wrap()> starts its work by expanding all the tabs in its
184 input into spaces. The last thing it does it to turn spaces back
185 into tabs. If you do not want tabs in your results, set
186 C<$Text::Wrap::unexpand> to a false value. Likewise if you do not
187 want to use 8-character tabstops, set C<$Text::Wrap::tabstop> to
188 the number of characters you do want for your tabstops.
190 If you want to separate your lines with something other than C<\n>
191 then set C<$Text::Wrap::separator> to your preference.
193 When words that are longer than C<$columns> are encountered, they
194 are broken up. C<wrap()> adds a C<"\n"> at column C<$columns>.
195 This behavior can be overridden by setting C<$huge> to
196 'die' or to 'overflow'. When set to 'die', large words will cause
197 C<die()> to be called. When set to 'overflow', large words will be
200 Historical notes: 'die' used to be the default value of
201 C<$huge>. Now, 'wrap' is the default value.
205 print wrap("\t","","This is a bit of text that forms
206 a normal book-style paragraph");
210 David Muir Sharnoff <muir@idiom.com> with help from Tim Pierce and