This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
#12272 wasn't right, it introduced an extra ().
[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
3e2ea5df 9$VERSION = 2001.0131;
b1a524cb 10
9a09eeb5
DMS
11use vars qw($VERSION $columns $debug $break $huge);
12use strict;
b1a524cb 13
4633a7c4 14BEGIN {
9a09eeb5
DMS
15 $columns = 76; # <= screen width
16 $debug = 0;
17 $break = '\s';
3e2ea5df 18 $huge = 'wrap'; # alternatively: 'die' or 'overflow'
4633a7c4
LW
19}
20
9a09eeb5
DMS
21use Text::Tabs qw(expand unexpand);
22
4633a7c4
LW
23sub wrap
24{
9a09eeb5
DMS
25 my ($ip, $xp, @t) = @_;
26
27 my $r = "";
3e2ea5df
JH
28 my $tail = pop(@t);
29 my $t = expand(join("", (map { /\s+\Z/ ? ( $_ ) : ($_, ' ') } @t), $tail));
9a09eeb5
DMS
30 my $lead = $ip;
31 my $ll = $columns - length(expand($ip)) - 1;
32 my $nll = $columns - length(expand($xp)) - 1;
33 my $nl = "";
34 my $remainder = "";
35
3e2ea5df
JH
36 pos($t) = 0;
37 while ($t !~ /\G\s*\Z/gc) {
38 if ($t =~ /\G([^\n]{0,$ll})($break|\Z(?!\n))/xmgc) {
9a09eeb5
DMS
39 $r .= unexpand($nl . $lead . $1);
40 $remainder = $2;
3e2ea5df 41 } elsif ($huge eq 'wrap' && $t =~ /\G([^\n]{$ll})/gc) {
9a09eeb5
DMS
42 $r .= unexpand($nl . $lead . $1);
43 $remainder = "\n";
3e2ea5df
JH
44 } elsif ($huge eq 'overflow' && $t =~ /\G([^\n]*?)($break|\Z(?!\n))/xmgc) {
45 $r .= unexpand($nl . $lead . $1);
46 $remainder = $2;
9a09eeb5
DMS
47 } elsif ($huge eq 'die') {
48 die "couldn't wrap '$t'";
49 } else {
50 die "This shouldn't happen";
51 }
52
53 $lead = $xp;
54 $ll = $nll;
55 $nl = "\n";
9b599b2a 56 }
9a09eeb5 57 $r .= $remainder;
b1a524cb 58
9a09eeb5 59 print "-----------$r---------\n" if $debug;
b1a524cb 60
3e2ea5df 61 print "Finish up with '$lead'\n" if $debug;
b1a524cb 62
3e2ea5df
JH
63 $r .= $lead . substr($t, pos($t), length($t)-pos($t))
64 if pos($t) ne length($t);
b1a524cb 65
9a09eeb5 66 print "-----------$r---------\n" if $debug;;
3e2ea5df 67
9a09eeb5 68 return $r;
4633a7c4
LW
69}
70
0c5a43b5
GS
71sub fill
72{
73 my ($ip, $xp, @raw) = @_;
74 my @para;
75 my $pp;
76
77 for $pp (split(/\n\s+/, join("\n",@raw))) {
78 $pp =~ s/\s+/ /g;
79 my $x = wrap($ip, $xp, $pp);
80 push(@para, $x);
81 }
82
83 # if paragraph_indent is the same as line_indent,
84 # separate paragraphs with blank lines
85
3e2ea5df
JH
86 my $ps = ($ip eq $xp) ? "\n\n" : "\n";
87 return join ($ps, @para);
0c5a43b5
GS
88}
89
4633a7c4 901;
68e56a55 91__END__
b1a524cb
PP
92
93=head1 NAME
94
95Text::Wrap - line wrapping to form simple paragraphs
96
97=head1 SYNOPSIS
98
3e2ea5df
JH
99B<Example 1>
100
b1a524cb
PP
101 use Text::Wrap
102
3e2ea5df
JH
103 $initial_tab = "\t"; # Tab before first line
104 $subsequent_tab = ""; # All other lines flush left
105
b1a524cb 106 print wrap($initial_tab, $subsequent_tab, @text);
0c5a43b5 107 print fill($initial_tab, $subsequent_tab, @text);
b1a524cb 108
3e2ea5df
JH
109 @lines = wrap($initial_tab, $subsequent_tab, @text);
110
111 @paragraphs = fill($initial_tab, $subsequent_tab, @text);
112
113B<Example 2>
114
9a09eeb5 115 use Text::Wrap qw(wrap $columns $huge);
b1a524cb 116
3e2ea5df 117 $columns = 132; # Wrap at 132 characters
9a09eeb5
DMS
118 $huge = 'die';
119 $huge = 'wrap';
3e2ea5df 120 $huge = 'overflow';
b1a524cb 121
3e2ea5df 122B<Example 3>
bbc7dcd2 123
3e2ea5df 124 use Text::Wrap
b1a524cb 125
3e2ea5df
JH
126 $Text::Wrap::columns = 72;
127 print wrap('', '', @text);
9a09eeb5 128
3e2ea5df 129=head1 DESCRIPTION
9a09eeb5 130
3e2ea5df
JH
131Text::Wrap::wrap() is a very simple paragraph formatter. It formats a
132single paragraph at a time by breaking lines at word boundries.
133Indentation is controlled for the first line (C<$initial_tab>) and
134all subsquent lines (C<$subsequent_tab>) independently. Please note:
135C<$initial_tab> and C<$subsequent_tab> are the literal strings that will
136be used: it is unlikley you would want to pass in a number.
137
138Lines are wrapped at C<$Text::Wrap::columns> columns. C<$Text::Wrap::columns>
139should be set to the full width of your output device. In fact,
140every resulting line will have length of no more than C<$columns - 1>.
141
142Beginner note: In example 2, above C<$columns> is imported into
143the local namespace, and set locally. In example 3,
144C<$Text::Wrap::columns> is set in its own namespace without importing it.
145
146When words that are longer than C<$columns> are encountered, they
147are broken up. C<wrap()> adds a C<"\n"> at column C<$columns>.
148This behavior can be overridden by setting C<$huge> to
149'die' or to 'overflow'. When set to 'die', large words will cause
150C<die()> to be called. When set to 'overflow', large words will be
151left intact.
9b599b2a 152
0c5a43b5
GS
153Text::Wrap::fill() is a simple multi-paragraph formatter. It formats
154each paragraph separately and then joins them together when it's done. It
3e2ea5df 155will destory any whitespace in the original text. It breaks text into
0c5a43b5
GS
156paragraphs by looking for whitespace after a newline. In other respects
157it acts like wrap().
158
3e2ea5df
JH
159When called in list context, C<wrap()> will return a list of lines and
160C<fill()> will return a list of paragraphs.
161
162Historical notes: Older versions of C<wrap()> and C<fill()> always
163returned strings. Also, 'die' used to be the default value of
164C<$huge>. Now, 'wrap' is the default value.
165
b1a524cb
PP
166=head1 EXAMPLE
167
168 print wrap("\t","","This is a bit of text that forms
169 a normal book-style paragraph");
170
171=head1 AUTHOR
172
4fc6b8d8 173David Muir Sharnoff <muir@idiom.com> with help from Tim Pierce and
0c5a43b5 174many many others.
b1a524cb 175