1package Text::Wrap;
2
3require 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
11use vars qw($VERSION $columns $debug $break $huge $unexpand $tabstop
12	$separator $separator2);
13use strict;
14
15BEGIN	{
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
26use Text::Tabs qw(expand unexpand);
27
28sub 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
90sub 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
1091;
110__END__
111
112=head1 NAME
113
114Text::Wrap - line wrapping to form simple paragraphs
115
116=head1 SYNOPSIS
117
118B<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
132B<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
141B<Example 3>
142
143	use Text::Wrap
144
145	$Text::Wrap::columns = 72;
146	print wrap('', '', @text);
147
148=head1 DESCRIPTION
149
150C<Text::Wrap::wrap()> is a very simple paragraph formatter.  It formats a
151single paragraph at a time by breaking lines at word boundries.
152Indentation is controlled for the first line (C<$initial_tab>) and
153all subsequent lines (C<$subsequent_tab>) independently.  Please note:
154C<$initial_tab> and C<$subsequent_tab> are the literal strings that will
155be used: it is unlikley you would want to pass in a number.
156
157Text::Wrap::fill() is a simple multi-paragraph formatter.  It formats
158each paragraph separately and then joins them together when it's done.  It
159will destroy any whitespace in the original text.  It breaks text into
160paragraphs by looking for whitespace after a newline.  In other respects
161it acts like wrap().
162
163=head1 OVERRIDES
164
165C<Text::Wrap::wrap()> has a number of variables that control its behavior.
166Because other modules might be using C<Text::Wrap::wrap()> it is suggested
167that you leave these variables alone!  If you can't do that, then
168use C<local($Text::Wrap::VARIABLE) = YOURVALUE> when you change the
169values so that the original value is restored.  This C<local()> trick
170will not work if you import the variable into your own namespace.
171
172Lines are wrapped at C<$Text::Wrap::columns> columns.  C<$Text::Wrap::columns>
173should be set to the full width of your output device.  In fact,
174every resulting line will have length of no more than C<$columns - 1>.
175
176It is possible to control which characters terminate words by
177modifying C<$Text::Wrap::break>. Set this to a string such as
178C<'[\s:]'> (to break before spaces or colons) or a pre-compiled regexp
179such as C<qr/[\s']/> (to break before spaces or apostrophes). The
180default is simply C<'\s'>; that is, words are terminated by spaces.
181(This means, among other things, that trailing punctuation  such as
182full stops or commas stay with the word they are "attached" to.)
183
184Beginner note: In example 2, above C<$columns> is imported into
185the local namespace, and set locally.  In example 3,
186C<$Text::Wrap::columns> is set in its own namespace without importing it.
187
188C<Text::Wrap::wrap()> starts its work by expanding all the tabs in its
189input into spaces.  The last thing it does it to turn spaces back
190into tabs.  If you do not want tabs in your results, set
191C<$Text::Wrap::unexpand> to a false value.  Likewise if you do not
192want to use 8-character tabstops, set C<$Text::Wrap::tabstop> to
193the number of characters you do want for your tabstops.
194
195If you want to separate your lines with something other than C<\n>
196then set C<$Text::Wrap::separator> to your preference.  This replaces
197all newlines with C<$Text::Wrap::separator>.  If you just to preserve
198existing newlines but add new breaks with something else, set
199C<$Text::Wrap::separator2> instead.
200
201When words that are longer than C<$columns> are encountered, they
202are broken up.  C<wrap()> adds a C<"\n"> at column C<$columns>.
203This behavior can be overridden by setting C<$huge> to
204'die' or to 'overflow'.  When set to 'die', large words will cause
205C<die()> to be called.  When set to 'overflow', large words will be
206left intact.
207
208Historical notes: 'die' used to be the default value of
209C<$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
218David Muir Sharnoff <muir@idiom.com> with help from Tim Pierce and
219many many others.  Copyright (C) 1996-2002 David Muir Sharnoff.
220This module may be modified, used, copied, and redistributed at
221your own risk.  Publicly redistributed modified versions must use
222a different name.
223
224