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