@EXPORT = qw(wrap fill);
@EXPORT_OK = qw($columns $break $huge);
-$VERSION = 2001.0131;
+$VERSION = 2001.0929;
-use vars qw($VERSION $columns $debug $break $huge);
+use vars qw($VERSION $columns $debug $break $huge $unexpand $tabstop
+ $separator);
use strict;
BEGIN {
$debug = 0;
$break = '\s';
$huge = 'wrap'; # alternatively: 'die' or 'overflow'
+ $unexpand = 1;
+ $tabstop = 8;
+ $separator = "\n";
}
use Text::Tabs qw(expand unexpand);
{
my ($ip, $xp, @t) = @_;
+ local($Text::Tabs::tabstop) = $tabstop;
my $r = "";
my $tail = pop(@t);
- my $t = expand(join("", (map { /\s+\Z/ ? ( $_ ) : ($_, ' ') } @t), $tail));
+ my $t = expand(join("", (map { /\s+\z/ ? ( $_ ) : ($_, ' ') } @t), $tail));
my $lead = $ip;
my $ll = $columns - length(expand($ip)) - 1;
+ $ll = 0 if $ll < 0;
my $nll = $columns - length(expand($xp)) - 1;
my $nl = "";
my $remainder = "";
+ use re 'taint';
+
pos($t) = 0;
while ($t !~ /\G\s*\Z/gc) {
- if ($t =~ /\G([^\n]{0,$ll})($break|\Z(?!\n))/xmgc) {
- $r .= unexpand($nl . $lead . $1);
+ if ($t =~ /\G([^\n]{0,$ll})($break|\z)/xmgc) {
+ $r .= $unexpand
+ ? unexpand($nl . $lead . $1)
+ : $nl . $lead . $1;
$remainder = $2;
} elsif ($huge eq 'wrap' && $t =~ /\G([^\n]{$ll})/gc) {
- $r .= unexpand($nl . $lead . $1);
- $remainder = "\n";
- } elsif ($huge eq 'overflow' && $t =~ /\G([^\n]*?)($break|\Z(?!\n))/xmgc) {
- $r .= unexpand($nl . $lead . $1);
+ $r .= $unexpand
+ ? unexpand($nl . $lead . $1)
+ : $nl . $lead . $1;
+ $remainder = $separator;
+ } elsif ($huge eq 'overflow' && $t =~ /\G([^\n]*?)($break|\z)/xmgc) {
+ $r .= $unexpand
+ ? unexpand($nl . $lead . $1)
+ : $nl . $lead . $1;
$remainder = $2;
} elsif ($huge eq 'die') {
die "couldn't wrap '$t'";
$lead = $xp;
$ll = $nll;
- $nl = "\n";
+ $nl = $separator;
}
$r .= $remainder;
=head1 DESCRIPTION
-Text::Wrap::wrap() is a very simple paragraph formatter. It formats a
+C<Text::Wrap::wrap()> is a very simple paragraph formatter. It formats a
single paragraph at a time by breaking lines at word boundries.
Indentation is controlled for the first line (C<$initial_tab>) and
-all subsquent lines (C<$subsequent_tab>) independently. Please note:
+all subsequent lines (C<$subsequent_tab>) independently. Please note:
C<$initial_tab> and C<$subsequent_tab> are the literal strings that will
be used: it is unlikley you would want to pass in a number.
+Text::Wrap::fill() is a simple multi-paragraph formatter. It formats
+each paragraph separately and then joins them together when it's done. It
+will destory any whitespace in the original text. It breaks text into
+paragraphs by looking for whitespace after a newline. In other respects
+it acts like wrap().
+
+=head1 OVERRIDES
+
+C<Text::Wrap::wrap()> has a number of variables that control its behavior.
+Because other modules might be using C<Text::Wrap::wrap()> it is suggested
+that you leave these variables alone! If you can't do that, then
+use C<local($Text::Wrap::VARIABLE) = YOURVALUE> when you change the
+values so that the original value is restored. This C<local()> trick
+will not work if you import the variable into your own namespace.
+
Lines are wrapped at C<$Text::Wrap::columns> columns. C<$Text::Wrap::columns>
should be set to the full width of your output device. In fact,
every resulting line will have length of no more than C<$columns - 1>.
+It is possible to control which characters terminate words by
+modifying C<$Text::Wrap::break>. Set this to a string such as
+C<'[\s:]'> (to break before spaces or colons) or a pre-compiled regexp
+such as C<qr/[\s']/> (to break before spaces or apostrophes). The
+default is simply C<'\s'>; that is, words are terminated by spaces.
+(This means, among other things, that trailing punctuation such as
+full stops or commas stay with the word they are "attached" to.)
+
Beginner note: In example 2, above C<$columns> is imported into
the local namespace, and set locally. In example 3,
C<$Text::Wrap::columns> is set in its own namespace without importing it.
+C<Text::Wrap::wrap()> starts its work by expanding all the tabs in its
+input into spaces. The last thing it does it to turn spaces back
+into tabs. If you do not want tabs in your results, set
+C<$Text::Wrap::unexapand> to a false value. Likewise if you do not
+want to use 8-character tabstops, set C<$Text::Wrap::tabstop> to
+the number of characters you do want for your tabstops.
+
+If you want to separate your lines with something other than C<\n>
+then set C<$Text::Wrap::seporator> to your preference.
+
When words that are longer than C<$columns> are encountered, they
are broken up. C<wrap()> adds a C<"\n"> at column C<$columns>.
This behavior can be overridden by setting C<$huge> to
C<die()> to be called. When set to 'overflow', large words will be
left intact.
-Text::Wrap::fill() is a simple multi-paragraph formatter. It formats
-each paragraph separately and then joins them together when it's done. It
-will destory any whitespace in the original text. It breaks text into
-paragraphs by looking for whitespace after a newline. In other respects
-it acts like wrap().
-
-When called in list context, C<wrap()> will return a list of lines and
-C<fill()> will return a list of paragraphs.
-
-Historical notes: Older versions of C<wrap()> and C<fill()> always
-returned strings. Also, 'die' used to be the default value of
+Historical notes: 'die' used to be the default value of
C<$huge>. Now, 'wrap' is the default value.
=head1 EXAMPLE