Commit | Line | Data |
---|---|---|
4633a7c4 LW |
1 | package Text::Wrap; |
2 | ||
58389ed2 | 3 | use warnings::register; |
9a09eeb5 | 4 | require Exporter; |
4633a7c4 | 5 | |
0c5a43b5 GS |
6 | @ISA = qw(Exporter); |
7 | @EXPORT = qw(wrap fill); | |
8 | @EXPORT_OK = qw($columns $break $huge); | |
4633a7c4 | 9 | |
69e34dac | 10 | $VERSION = 2009.0305; |
b1a524cb | 11 | |
37a581db | 12 | use vars qw($VERSION $columns $debug $break $huge $unexpand $tabstop |
8dfcc161 | 13 | $separator $separator2); |
9a09eeb5 | 14 | use strict; |
b1a524cb | 15 | |
4633a7c4 | 16 | BEGIN { |
9a09eeb5 DMS |
17 | $columns = 76; # <= screen width |
18 | $debug = 0; | |
19 | $break = '\s'; | |
3e2ea5df | 20 | $huge = 'wrap'; # alternatively: 'die' or 'overflow' |
37a581db JH |
21 | $unexpand = 1; |
22 | $tabstop = 8; | |
23 | $separator = "\n"; | |
8dfcc161 | 24 | $separator2 = undef; |
4633a7c4 LW |
25 | } |
26 | ||
9a09eeb5 DMS |
27 | use Text::Tabs qw(expand unexpand); |
28 | ||
4633a7c4 LW |
29 | sub wrap |
30 | { | |
9a09eeb5 DMS |
31 | my ($ip, $xp, @t) = @_; |
32 | ||
37a581db | 33 | local($Text::Tabs::tabstop) = $tabstop; |
9a09eeb5 | 34 | my $r = ""; |
3e2ea5df | 35 | my $tail = pop(@t); |
37a581db | 36 | my $t = expand(join("", (map { /\s+\z/ ? ( $_ ) : ($_, ' ') } @t), $tail)); |
9a09eeb5 | 37 | my $lead = $ip; |
69e34dac S |
38 | my $nll = $columns - length(expand($xp)) - 1; |
39 | if ($nll <= 0 && $xp ne '') { | |
40 | my $nc = length(expand($xp)) + 2; | |
41 | warnings::warnif "Increasing \$Text::Wrap::columns from $columns to $nc to accommodate length of subsequent tab"; | |
42 | $columns = $nc; | |
43 | $nll = 1; | |
44 | } | |
9a09eeb5 | 45 | my $ll = $columns - length(expand($ip)) - 1; |
718842b0 | 46 | $ll = 0 if $ll < 0; |
9a09eeb5 DMS |
47 | my $nl = ""; |
48 | my $remainder = ""; | |
49 | ||
37a581db JH |
50 | use re 'taint'; |
51 | ||
3e2ea5df | 52 | pos($t) = 0; |
95925ace SP |
53 | while ($t !~ /\G(?:$break)*\Z/gc) { |
54 | if ($t =~ /\G([^\n]{0,$ll})($break|\n+|\z)/xmgc) { | |
37a581db JH |
55 | $r .= $unexpand |
56 | ? unexpand($nl . $lead . $1) | |
57 | : $nl . $lead . $1; | |
9a09eeb5 | 58 | $remainder = $2; |
3e2ea5df | 59 | } elsif ($huge eq 'wrap' && $t =~ /\G([^\n]{$ll})/gc) { |
37a581db JH |
60 | $r .= $unexpand |
61 | ? unexpand($nl . $lead . $1) | |
62 | : $nl . $lead . $1; | |
8dfcc161 | 63 | $remainder = defined($separator2) ? $separator2 : $separator; |
95925ace | 64 | } elsif ($huge eq 'overflow' && $t =~ /\G([^\n]*?)($break|\n+|\z)/xmgc) { |
37a581db JH |
65 | $r .= $unexpand |
66 | ? unexpand($nl . $lead . $1) | |
67 | : $nl . $lead . $1; | |
3e2ea5df | 68 | $remainder = $2; |
9a09eeb5 DMS |
69 | } elsif ($huge eq 'die') { |
70 | die "couldn't wrap '$t'"; | |
95925ace | 71 | } elsif ($columns < 2) { |
58389ed2 | 72 | warnings::warnif "Increasing \$Text::Wrap::columns from $columns to 2"; |
95925ace SP |
73 | $columns = 2; |
74 | return ($ip, $xp, @t); | |
9a09eeb5 DMS |
75 | } else { |
76 | die "This shouldn't happen"; | |
77 | } | |
78 | ||
79 | $lead = $xp; | |
80 | $ll = $nll; | |
8dfcc161 RGS |
81 | $nl = defined($separator2) |
82 | ? ($remainder eq "\n" | |
83 | ? "\n" | |
84 | : $separator2) | |
85 | : $separator; | |
9b599b2a | 86 | } |
9a09eeb5 | 87 | $r .= $remainder; |
b1a524cb | 88 | |
9a09eeb5 | 89 | print "-----------$r---------\n" if $debug; |
b1a524cb | 90 | |
3e2ea5df | 91 | print "Finish up with '$lead'\n" if $debug; |
b1a524cb | 92 | |
3e2ea5df JH |
93 | $r .= $lead . substr($t, pos($t), length($t)-pos($t)) |
94 | if pos($t) ne length($t); | |
b1a524cb | 95 | |
9a09eeb5 | 96 | print "-----------$r---------\n" if $debug;; |
3e2ea5df | 97 | |
9a09eeb5 | 98 | return $r; |
4633a7c4 LW |
99 | } |
100 | ||
0c5a43b5 GS |
101 | sub fill |
102 | { | |
103 | my ($ip, $xp, @raw) = @_; | |
104 | my @para; | |
105 | my $pp; | |
106 | ||
107 | for $pp (split(/\n\s+/, join("\n",@raw))) { | |
108 | $pp =~ s/\s+/ /g; | |
109 | my $x = wrap($ip, $xp, $pp); | |
110 | push(@para, $x); | |
111 | } | |
112 | ||
113 | # if paragraph_indent is the same as line_indent, | |
114 | # separate paragraphs with blank lines | |
115 | ||
3e2ea5df JH |
116 | my $ps = ($ip eq $xp) ? "\n\n" : "\n"; |
117 | return join ($ps, @para); | |
0c5a43b5 GS |
118 | } |
119 | ||
4633a7c4 | 120 | 1; |
68e56a55 | 121 | __END__ |
b1a524cb | 122 | |
123 | =head1 NAME | |
124 | ||
125 | Text::Wrap - line wrapping to form simple paragraphs | |
126 | ||
127 | =head1 SYNOPSIS | |
128 | ||
3e2ea5df JH |
129 | B<Example 1> |
130 | ||
bc1e993d | 131 | use Text::Wrap; |
b1a524cb | 132 | |
3e2ea5df JH |
133 | $initial_tab = "\t"; # Tab before first line |
134 | $subsequent_tab = ""; # All other lines flush left | |
135 | ||
b1a524cb | 136 | print wrap($initial_tab, $subsequent_tab, @text); |
0c5a43b5 | 137 | print fill($initial_tab, $subsequent_tab, @text); |
b1a524cb | 138 | |
7b614c55 | 139 | $lines = wrap($initial_tab, $subsequent_tab, @text); |
3e2ea5df JH |
140 | |
141 | @paragraphs = fill($initial_tab, $subsequent_tab, @text); | |
142 | ||
143 | B<Example 2> | |
144 | ||
9a09eeb5 | 145 | use Text::Wrap qw(wrap $columns $huge); |
b1a524cb | 146 | |
3e2ea5df | 147 | $columns = 132; # Wrap at 132 characters |
9a09eeb5 DMS |
148 | $huge = 'die'; |
149 | $huge = 'wrap'; | |
3e2ea5df | 150 | $huge = 'overflow'; |
b1a524cb | 151 | |
3e2ea5df | 152 | B<Example 3> |
95925ace | 153 | |
bc1e993d | 154 | use Text::Wrap; |
b1a524cb | 155 | |
3e2ea5df JH |
156 | $Text::Wrap::columns = 72; |
157 | print wrap('', '', @text); | |
9a09eeb5 | 158 | |
3e2ea5df | 159 | =head1 DESCRIPTION |
9a09eeb5 | 160 | |
37a581db | 161 | C<Text::Wrap::wrap()> is a very simple paragraph formatter. It formats a |
3c4b39be | 162 | single paragraph at a time by breaking lines at word boundaries. |
3e2ea5df | 163 | Indentation is controlled for the first line (C<$initial_tab>) and |
718842b0 | 164 | all subsequent lines (C<$subsequent_tab>) independently. Please note: |
3e2ea5df | 165 | C<$initial_tab> and C<$subsequent_tab> are the literal strings that will |
3c4b39be | 166 | be used: it is unlikely you would want to pass in a number. |
3e2ea5df | 167 | |
37a581db JH |
168 | Text::Wrap::fill() is a simple multi-paragraph formatter. It formats |
169 | each paragraph separately and then joins them together when it's done. It | |
818675a5 | 170 | will destroy any whitespace in the original text. It breaks text into |
37a581db JH |
171 | paragraphs by looking for whitespace after a newline. In other respects |
172 | it acts like wrap(). | |
173 | ||
95925ace SP |
174 | Both C<wrap()> and C<fill()> return a single string. |
175 | ||
37a581db JH |
176 | =head1 OVERRIDES |
177 | ||
178 | C<Text::Wrap::wrap()> has a number of variables that control its behavior. | |
179 | Because other modules might be using C<Text::Wrap::wrap()> it is suggested | |
180 | that you leave these variables alone! If you can't do that, then | |
181 | use C<local($Text::Wrap::VARIABLE) = YOURVALUE> when you change the | |
182 | values so that the original value is restored. This C<local()> trick | |
183 | will not work if you import the variable into your own namespace. | |
184 | ||
69e34dac S |
185 | Lines are wrapped at C<$Text::Wrap::columns> columns (default value: 76). |
186 | C<$Text::Wrap::columns> should be set to the full width of your output | |
187 | device. In fact, every resulting line will have length of no more than | |
188 | C<$columns - 1>. | |
3e2ea5df | 189 | |
37a581db JH |
190 | It is possible to control which characters terminate words by |
191 | modifying C<$Text::Wrap::break>. Set this to a string such as | |
192 | C<'[\s:]'> (to break before spaces or colons) or a pre-compiled regexp | |
193 | such as C<qr/[\s']/> (to break before spaces or apostrophes). The | |
194 | default is simply C<'\s'>; that is, words are terminated by spaces. | |
195 | (This means, among other things, that trailing punctuation such as | |
196 | full stops or commas stay with the word they are "attached" to.) | |
69e34dac S |
197 | Setting C<$Text::Wrap::break> to a regular expression that doesn't |
198 | eat any characters (perhaps just a forward look-ahead assertion) will | |
199 | cause warnings. | |
37a581db | 200 | |
3e2ea5df JH |
201 | Beginner note: In example 2, above C<$columns> is imported into |
202 | the local namespace, and set locally. In example 3, | |
203 | C<$Text::Wrap::columns> is set in its own namespace without importing it. | |
204 | ||
37a581db JH |
205 | C<Text::Wrap::wrap()> starts its work by expanding all the tabs in its |
206 | input into spaces. The last thing it does it to turn spaces back | |
207 | into tabs. If you do not want tabs in your results, set | |
818675a5 | 208 | C<$Text::Wrap::unexpand> to a false value. Likewise if you do not |
37a581db JH |
209 | want to use 8-character tabstops, set C<$Text::Wrap::tabstop> to |
210 | the number of characters you do want for your tabstops. | |
211 | ||
212 | If you want to separate your lines with something other than C<\n> | |
8dfcc161 | 213 | then set C<$Text::Wrap::separator> to your preference. This replaces |
69e34dac S |
214 | all newlines with C<$Text::Wrap::separator>. If you just want to |
215 | preserve existing newlines but add new breaks with something else, set | |
8dfcc161 | 216 | C<$Text::Wrap::separator2> instead. |
37a581db | 217 | |
3e2ea5df JH |
218 | When words that are longer than C<$columns> are encountered, they |
219 | are broken up. C<wrap()> adds a C<"\n"> at column C<$columns>. | |
220 | This behavior can be overridden by setting C<$huge> to | |
221 | 'die' or to 'overflow'. When set to 'die', large words will cause | |
222 | C<die()> to be called. When set to 'overflow', large words will be | |
223 | left intact. | |
9b599b2a | 224 | |
37a581db | 225 | Historical notes: 'die' used to be the default value of |
3e2ea5df JH |
226 | C<$huge>. Now, 'wrap' is the default value. |
227 | ||
95925ace SP |
228 | =head1 EXAMPLES |
229 | ||
230 | Code: | |
231 | ||
232 | print wrap("\t","",<<END); | |
233 | This is a bit of text that forms | |
234 | a normal book-style indented paragraph | |
235 | END | |
236 | ||
237 | Result: | |
238 | ||
239 | " This is a bit of text that forms | |
240 | a normal book-style indented paragraph | |
241 | " | |
242 | ||
243 | Code: | |
244 | ||
245 | $Text::Wrap::columns=20; | |
246 | $Text::Wrap::separator="|"; | |
247 | print wrap("","","This is a bit of text that forms a normal book-style paragraph"); | |
248 | ||
249 | Result: | |
b1a524cb | 250 | |
95925ace | 251 | "This is a bit of|text that forms a|normal book-style|paragraph" |
b1a524cb | 252 | |
69e34dac S |
253 | =head1 SEE ALSO |
254 | ||
255 | For wrapping multi-byte characters: L<Text::WrapI18N>. | |
256 | For more detailed controls: L<Text::Format>. | |
257 | ||
8dfcc161 | 258 | =head1 LICENSE |
b1a524cb | 259 | |
69e34dac S |
260 | David Muir Sharnoff <muir@idiom.org> with help from Tim Pierce and |
261 | many many others. Copyright (C) 1996-2009 David Muir Sharnoff. | |
8dfcc161 | 262 | This module may be modified, used, copied, and redistributed at |
69e34dac S |
263 | your own risk. Publicly redistributed versions that are modified |
264 | must use a different name. | |
b1a524cb | 265 |