lib/Text/Wrap.pm

package Text::Wrap;

require Exporter;

@ISA = qw(Exporter);
@EXPORT = qw(wrap fill);
@EXPORT_OK = qw($columns $break $huge);

$VERSION = 2001.09293;

use vars qw($VERSION $columns $debug $break $huge $unexpand $tabstop
        $separator);
use strict;

BEGIN   {
        $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) = @_;

        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|\n*\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;
        }
        $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 
{
        my ($ip, $xp, @raw) = @_;
        my @para;
        my $pp;

        for $pp (split(/\n\s+/, join("\n",@raw))) {
                $pp =~ s/\s+/ /g;
                my $x = wrap($ip, $xp, $pp);
                push(@para, $x);
        }

        # if paragraph_indent is the same as line_indent, 
        # separate paragraphs with blank lines

        my $ps = ($ip eq $xp) ? "\n\n" : "\n";
        return join ($ps, @para);
}

1;
__END__

=head1 NAME

Text::Wrap - line wrapping to form simple paragraphs

=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);

        $lines = wrap($initial_tab, $subsequent_tab, @text);

        @paragraphs = fill($initial_tab, $subsequent_tab, @text);

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

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 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 destroy 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::unexpand> 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::separator> 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 AUTHOR

David Muir Sharnoff <muir@idiom.com> with help from Tim Pierce and
many many others.  

Revision:	1.1
Committed:	Thu Jun 30 14:27:16 2005 UTC (21 years, 4 months ago) by root
Branch:	MAIN
CVS Tags:	PERL-5-8-7, HEAD
Branch point for:	PERL
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.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