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