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