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