This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
[perl #34902] Text::Wrap::wrap() fails with non-space separator
[perl5.git] / lib / Text / Wrap.pm
CommitLineData
4633a7c4
LW
1package Text::Wrap;
2
9a09eeb5 3require Exporter;
4633a7c4 4
0c5a43b5
GS
5@ISA = qw(Exporter);
6@EXPORT = qw(wrap fill);
7@EXPORT_OK = qw($columns $break $huge);
4633a7c4 8
ff270add 9$VERSION = 2001.09292;
b1a524cb 10
37a581db
JH
11use vars qw($VERSION $columns $debug $break $huge $unexpand $tabstop
12 $separator);
9a09eeb5 13use strict;
b1a524cb 14
4633a7c4 15BEGIN {
9a09eeb5
DMS
16 $columns = 76; # <= screen width
17 $debug = 0;
18 $break = '\s';
3e2ea5df 19 $huge = 'wrap'; # alternatively: 'die' or 'overflow'
37a581db
JH
20 $unexpand = 1;
21 $tabstop = 8;
22 $separator = "\n";
4633a7c4
LW
23}
24
9a09eeb5
DMS
25use Text::Tabs qw(expand unexpand);
26
4633a7c4
LW
27sub wrap
28{
9a09eeb5
DMS
29 my ($ip, $xp, @t) = @_;
30
37a581db 31 local($Text::Tabs::tabstop) = $tabstop;
9a09eeb5 32 my $r = "";
3e2ea5df 33 my $tail = pop(@t);
37a581db 34 my $t = expand(join("", (map { /\s+\z/ ? ( $_ ) : ($_, ' ') } @t), $tail));
9a09eeb5
DMS
35 my $lead = $ip;
36 my $ll = $columns - length(expand($ip)) - 1;
718842b0 37 $ll = 0 if $ll < 0;
9a09eeb5
DMS
38 my $nll = $columns - length(expand($xp)) - 1;
39 my $nl = "";
40 my $remainder = "";
41
37a581db
JH
42 use re 'taint';
43
3e2ea5df
JH
44 pos($t) = 0;
45 while ($t !~ /\G\s*\Z/gc) {
818675a5 46 if ($t =~ /\G([^\n]{0,$ll})($break|\n*\z)/xmgc) {
37a581db
JH
47 $r .= $unexpand
48 ? unexpand($nl . $lead . $1)
49 : $nl . $lead . $1;
9a09eeb5 50 $remainder = $2;
3e2ea5df 51 } elsif ($huge eq 'wrap' && $t =~ /\G([^\n]{$ll})/gc) {
37a581db
JH
52 $r .= $unexpand
53 ? unexpand($nl . $lead . $1)
54 : $nl . $lead . $1;
55 $remainder = $separator;
56 } elsif ($huge eq 'overflow' && $t =~ /\G([^\n]*?)($break|\z)/xmgc) {
57 $r .= $unexpand
58 ? unexpand($nl . $lead . $1)
59 : $nl . $lead . $1;
3e2ea5df 60 $remainder = $2;
9a09eeb5
DMS
61 } elsif ($huge eq 'die') {
62 die "couldn't wrap '$t'";
63 } else {
64 die "This shouldn't happen";
65 }
66
67 $lead = $xp;
68 $ll = $nll;
37a581db 69 $nl = $separator;
9b599b2a 70 }
9a09eeb5 71 $r .= $remainder;
b1a524cb 72
9a09eeb5 73 print "-----------$r---------\n" if $debug;
b1a524cb 74
3e2ea5df 75 print "Finish up with '$lead'\n" if $debug;
b1a524cb 76
3e2ea5df
JH
77 $r .= $lead . substr($t, pos($t), length($t)-pos($t))
78 if pos($t) ne length($t);
b1a524cb 79
9a09eeb5 80 print "-----------$r---------\n" if $debug;;
3e2ea5df 81
9a09eeb5 82 return $r;
4633a7c4
LW
83}
84
0c5a43b5
GS
85sub fill
86{
87 my ($ip, $xp, @raw) = @_;
88 my @para;
89 my $pp;
90
91 for $pp (split(/\n\s+/, join("\n",@raw))) {
92 $pp =~ s/\s+/ /g;
93 my $x = wrap($ip, $xp, $pp);
94 push(@para, $x);
95 }
96
97 # if paragraph_indent is the same as line_indent,
98 # separate paragraphs with blank lines
99
3e2ea5df
JH
100 my $ps = ($ip eq $xp) ? "\n\n" : "\n";
101 return join ($ps, @para);
0c5a43b5
GS
102}
103
4633a7c4 1041;
68e56a55 105__END__
b1a524cb
PP
106
107=head1 NAME
108
109Text::Wrap - line wrapping to form simple paragraphs
110
111=head1 SYNOPSIS
112
3e2ea5df
JH
113B<Example 1>
114
b1a524cb
PP
115 use Text::Wrap
116
3e2ea5df
JH
117 $initial_tab = "\t"; # Tab before first line
118 $subsequent_tab = ""; # All other lines flush left
119
b1a524cb 120 print wrap($initial_tab, $subsequent_tab, @text);
0c5a43b5 121 print fill($initial_tab, $subsequent_tab, @text);
b1a524cb 122
7b614c55 123 $lines = wrap($initial_tab, $subsequent_tab, @text);
3e2ea5df
JH
124
125 @paragraphs = fill($initial_tab, $subsequent_tab, @text);
126
127B<Example 2>
128
9a09eeb5 129 use Text::Wrap qw(wrap $columns $huge);
b1a524cb 130
3e2ea5df 131 $columns = 132; # Wrap at 132 characters
9a09eeb5
DMS
132 $huge = 'die';
133 $huge = 'wrap';
3e2ea5df 134 $huge = 'overflow';
b1a524cb 135
3e2ea5df 136B<Example 3>
bbc7dcd2 137
3e2ea5df 138 use Text::Wrap
b1a524cb 139
3e2ea5df
JH
140 $Text::Wrap::columns = 72;
141 print wrap('', '', @text);
9a09eeb5 142
3e2ea5df 143=head1 DESCRIPTION
9a09eeb5 144
37a581db 145C<Text::Wrap::wrap()> is a very simple paragraph formatter. It formats a
3e2ea5df
JH
146single paragraph at a time by breaking lines at word boundries.
147Indentation is controlled for the first line (C<$initial_tab>) and
718842b0 148all subsequent lines (C<$subsequent_tab>) independently. Please note:
3e2ea5df
JH
149C<$initial_tab> and C<$subsequent_tab> are the literal strings that will
150be used: it is unlikley you would want to pass in a number.
151
37a581db
JH
152Text::Wrap::fill() is a simple multi-paragraph formatter. It formats
153each paragraph separately and then joins them together when it's done. It
818675a5 154will destroy any whitespace in the original text. It breaks text into
37a581db
JH
155paragraphs by looking for whitespace after a newline. In other respects
156it acts like wrap().
157
158=head1 OVERRIDES
159
160C<Text::Wrap::wrap()> has a number of variables that control its behavior.
161Because other modules might be using C<Text::Wrap::wrap()> it is suggested
162that you leave these variables alone! If you can't do that, then
163use C<local($Text::Wrap::VARIABLE) = YOURVALUE> when you change the
164values so that the original value is restored. This C<local()> trick
165will not work if you import the variable into your own namespace.
166
3e2ea5df
JH
167Lines are wrapped at C<$Text::Wrap::columns> columns. C<$Text::Wrap::columns>
168should be set to the full width of your output device. In fact,
169every resulting line will have length of no more than C<$columns - 1>.
170
37a581db
JH
171It is possible to control which characters terminate words by
172modifying C<$Text::Wrap::break>. Set this to a string such as
173C<'[\s:]'> (to break before spaces or colons) or a pre-compiled regexp
174such as C<qr/[\s']/> (to break before spaces or apostrophes). The
175default is simply C<'\s'>; that is, words are terminated by spaces.
176(This means, among other things, that trailing punctuation such as
177full stops or commas stay with the word they are "attached" to.)
178
3e2ea5df
JH
179Beginner note: In example 2, above C<$columns> is imported into
180the local namespace, and set locally. In example 3,
181C<$Text::Wrap::columns> is set in its own namespace without importing it.
182
37a581db
JH
183C<Text::Wrap::wrap()> starts its work by expanding all the tabs in its
184input into spaces. The last thing it does it to turn spaces back
185into tabs. If you do not want tabs in your results, set
818675a5 186C<$Text::Wrap::unexpand> to a false value. Likewise if you do not
37a581db
JH
187want to use 8-character tabstops, set C<$Text::Wrap::tabstop> to
188the number of characters you do want for your tabstops.
189
190If you want to separate your lines with something other than C<\n>
818675a5 191then set C<$Text::Wrap::separator> to your preference.
37a581db 192
3e2ea5df
JH
193When words that are longer than C<$columns> are encountered, they
194are broken up. C<wrap()> adds a C<"\n"> at column C<$columns>.
195This behavior can be overridden by setting C<$huge> to
196'die' or to 'overflow'. When set to 'die', large words will cause
197C<die()> to be called. When set to 'overflow', large words will be
198left intact.
9b599b2a 199
37a581db 200Historical notes: 'die' used to be the default value of
3e2ea5df
JH
201C<$huge>. Now, 'wrap' is the default value.
202
b1a524cb
PP
203=head1 EXAMPLE
204
205 print wrap("\t","","This is a bit of text that forms
206 a normal book-style paragraph");
207
208=head1 AUTHOR
209
4fc6b8d8 210David Muir Sharnoff <muir@idiom.com> with help from Tim Pierce and
0c5a43b5 211many many others.
b1a524cb 212