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 <[email protected]> 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 |
|
---|