package Text::Wrap;
-use vars qw(@ISA @EXPORT @EXPORT_OK $VERSION $columns $debug);
-use strict;
-use Exporter;
+require Exporter;
-$VERSION = "97.02";
@ISA = qw(Exporter);
-@EXPORT = qw(wrap);
-@EXPORT_OK = qw($columns $tabstop fill);
+@EXPORT = qw(wrap fill);
+@EXPORT_OK = qw($columns $break $huge);
-use Text::Tabs qw(expand unexpand $tabstop);
+$VERSION = 2001.0929;
+use vars qw($VERSION $columns $debug $break $huge $unexpand $tabstop
+ $separator);
+use strict;
BEGIN {
- $columns = 76; # <= screen width
- $debug = 0;
+ $columns = 76; # <= screen width
+ $debug = 0;
+ $break = '\s';
+ $huge = 'wrap'; # alternatively: 'die' or 'overflow'
+ $unexpand = 1;
+ $tabstop = 8;
+ $separator = "\n";
}
+use Text::Tabs qw(expand unexpand);
+
sub wrap
{
- my ($ip, $xp, @t) = @_;
-
- my @rv;
- my $t = expand(join(" ",@t));
-
- my $lead = $ip;
- my $ll = $columns - length(expand($lead)) - 1;
- my $nl = "";
-
- $t =~ s/^\s+//;
- while(length($t) > $ll) {
- # remove up to a line length of things that
- # aren't new lines and tabs.
- if ($t =~ s/^([^\n]{0,$ll})(\s|\Z(?!\n))//) {
- my ($l,$r) = ($1,$2);
- $l =~ s/\s+$//;
- print "WRAP $lead$l..($r)\n" if $debug;
- push @rv, unexpand($lead . $l), "\n";
-
- } elsif ($t =~ s/^([^\n]{$ll})//) {
- print "SPLIT $lead$1..\n" if $debug;
- push @rv, unexpand($lead . $1),"\n";
+ 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 $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)/xmgc) {
+ $r .= $unexpand
+ ? unexpand($nl . $lead . $1)
+ : $nl . $lead . $1;
+ $remainder = $2;
+ } elsif ($huge eq 'wrap' && $t =~ /\G([^\n]{$ll})/gc) {
+ $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'";
+ } else {
+ die "This shouldn't happen";
+ }
+
+ $lead = $xp;
+ $ll = $nll;
+ $nl = $separator;
}
- # recompute the leader
- $lead = $xp;
- $ll = $columns - length(expand($lead)) - 1;
- $t =~ s/^\s+//;
- }
- print "TAIL $lead$t\n" if $debug;
- push @rv, $lead.$t if $t ne "";
- return join '', @rv;
-}
+ $r .= $remainder;
+
+ print "-----------$r---------\n" if $debug;
+
+ print "Finish up with '$lead'\n" if $debug;
+ $r .= $lead . substr($t, pos($t), length($t)-pos($t))
+ if pos($t) ne length($t);
+
+ print "-----------$r---------\n" if $debug;;
+
+ return $r;
+}
sub fill
{
# if paragraph_indent is the same as line_indent,
# separate paragraphs with blank lines
- return join ($ip eq $xp ? "\n\n" : "\n", @para);
+ my $ps = ($ip eq $xp) ? "\n\n" : "\n";
+ return join ($ps, @para);
}
1;
=head1 SYNOPSIS
+B<Example 1>
+
use Text::Wrap
+ $initial_tab = "\t"; # Tab before first line
+ $subsequent_tab = ""; # All other lines flush left
+
print wrap($initial_tab, $subsequent_tab, @text);
+ print fill($initial_tab, $subsequent_tab, @text);
- use Text::Wrap qw(wrap $columns $tabstop fill);
+ @lines = wrap($initial_tab, $subsequent_tab, @text);
- $columns = 132;
- $tabstop = 4;
+ @paragraphs = fill($initial_tab, $subsequent_tab, @text);
- print fill($initial_tab, $subsequent_tab, @text);
- print fill("", "", `cat book`);
+B<Example 2>
+
+ use Text::Wrap qw(wrap $columns $huge);
+
+ $columns = 132; # Wrap at 132 characters
+ $huge = 'die';
+ $huge = 'wrap';
+ $huge = 'overflow';
+
+B<Example 3>
+
+ use Text::Wrap
+
+ $Text::Wrap::columns = 72;
+ print wrap('', '', @text);
=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 ($initial_tab) and
-all subsquent lines ($subsequent_tab) independently. $Text::Wrap::columns
-should be set to the full width of your output device.
+Indentation is controlled for the first line (C<$initial_tab>) and
+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
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
+'die' or to 'overflow'. When set to 'die', large words will cause
+C<die()> to be called. When set to 'overflow', large words will be
+left intact.
+
+Historical notes: 'die' used to be the default value of
+C<$huge>. Now, 'wrap' is the default value.
+
=head1 EXAMPLE
print wrap("\t","","This is a bit of text that forms
a normal book-style paragraph");
-=head1 BUGS
-
-It's not clear what the correct behavior should be when Wrap() is
-presented with a word that is longer than a line. The previous
-behavior was to die. Now the word is now split at line-length.
-
=head1 AUTHOR
David Muir Sharnoff <muir@idiom.com> with help from Tim Pierce and
-others. Updated by Jacqui Caren.
+many many others.
-=cut