Initial bulk commit for "Git on MSys"
[msysgit/historical-msysgit.git] / lib / perl5 / 5.6.1 / Text / Wrap.pm
blob579e09b395b977d45853575f5288c1b7df30a174
1 package Text::Wrap;
3 require Exporter;
5 @ISA = qw(Exporter);
6 @EXPORT = qw(wrap fill);
7 @EXPORT_OK = qw($columns $break $huge);
9 $VERSION = 2001.0131;
11 use vars qw($VERSION $columns $debug $break $huge);
12 use strict;
14 BEGIN {
15 $columns = 76; # <= screen width
16 $debug = 0;
17 $break = '\s';
18 $huge = 'wrap'; # alternatively: 'die' or 'overflow'
21 use Text::Tabs qw(expand unexpand);
23 sub wrap
25 my ($ip, $xp, @t) = @_;
27 my $r = "";
28 my $tail = pop(@t);
29 my $t = expand(join("", (map { /\s+\Z/ ? ( $_ ) : ($_, ' ') } @t), $tail));
30 my $lead = $ip;
31 my $ll = $columns - length(expand($ip)) - 1;
32 my $nll = $columns - length(expand($xp)) - 1;
33 my $nl = "";
34 my $remainder = "";
36 pos($t) = 0;
37 while ($t !~ /\G\s*\Z/gc) {
38 if ($t =~ /\G([^\n]{0,$ll})($break|\Z(?!\n))/xmgc) {
39 $r .= unexpand($nl . $lead . $1);
40 $remainder = $2;
41 } elsif ($huge eq 'wrap' && $t =~ /\G([^\n]{$ll})/gc) {
42 $r .= unexpand($nl . $lead . $1);
43 $remainder = "\n";
44 } elsif ($huge eq 'overflow' && $t =~ /\G([^\n]*?)($break|\Z(?!\n))/xmgc) {
45 $r .= unexpand($nl . $lead . $1);
46 $remainder = $2;
47 } elsif ($huge eq 'die') {
48 die "couldn't wrap '$t'";
49 } else {
50 die "This shouldn't happen";
53 $lead = $xp;
54 $ll = $nll;
55 $nl = "\n";
57 $r .= $remainder;
59 print "-----------$r---------\n" if $debug;
61 print "Finish up with '$lead'\n" if $debug;
63 $r .= $lead . substr($t, pos($t), length($t)-pos($t))
64 if pos($t) ne length($t);
66 print "-----------$r---------\n" if $debug;;
68 return $r;
71 sub fill
73 my ($ip, $xp, @raw) = @_;
74 my @para;
75 my $pp;
77 for $pp (split(/\n\s+/, join("\n",@raw))) {
78 $pp =~ s/\s+/ /g;
79 my $x = wrap($ip, $xp, $pp);
80 push(@para, $x);
83 # if paragraph_indent is the same as line_indent,
84 # separate paragraphs with blank lines
86 my $ps = ($ip eq $xp) ? "\n\n" : "\n";
87 return join ($ps, @para);
91 __END__
93 =head1 NAME
95 Text::Wrap - line wrapping to form simple paragraphs
97 =head1 SYNOPSIS
99 B<Example 1>
101 use Text::Wrap
103 $initial_tab = "\t"; # Tab before first line
104 $subsequent_tab = ""; # All other lines flush left
106 print wrap($initial_tab, $subsequent_tab, @text);
107 print fill($initial_tab, $subsequent_tab, @text);
109 @lines = wrap($initial_tab, $subsequent_tab, @text);
111 @paragraphs = fill($initial_tab, $subsequent_tab, @text);
113 B<Example 2>
115 use Text::Wrap qw(wrap $columns $huge);
117 $columns = 132; # Wrap at 132 characters
118 $huge = 'die';
119 $huge = 'wrap';
120 $huge = 'overflow';
122 B<Example 3>
124 use Text::Wrap
126 $Text::Wrap::columns = 72;
127 print wrap('', '', @text);
129 =head1 DESCRIPTION
131 Text::Wrap::wrap() is a very simple paragraph formatter. It formats a
132 single paragraph at a time by breaking lines at word boundries.
133 Indentation is controlled for the first line (C<$initial_tab>) and
134 all subsquent lines (C<$subsequent_tab>) independently. Please note:
135 C<$initial_tab> and C<$subsequent_tab> are the literal strings that will
136 be used: it is unlikley you would want to pass in a number.
138 Lines are wrapped at C<$Text::Wrap::columns> columns. C<$Text::Wrap::columns>
139 should be set to the full width of your output device. In fact,
140 every resulting line will have length of no more than C<$columns - 1>.
142 Beginner note: In example 2, above C<$columns> is imported into
143 the local namespace, and set locally. In example 3,
144 C<$Text::Wrap::columns> is set in its own namespace without importing it.
146 When words that are longer than C<$columns> are encountered, they
147 are broken up. C<wrap()> adds a C<"\n"> at column C<$columns>.
148 This behavior can be overridden by setting C<$huge> to
149 'die' or to 'overflow'. When set to 'die', large words will cause
150 C<die()> to be called. When set to 'overflow', large words will be
151 left intact.
153 Text::Wrap::fill() is a simple multi-paragraph formatter. It formats
154 each paragraph separately and then joins them together when it's done. It
155 will destory any whitespace in the original text. It breaks text into
156 paragraphs by looking for whitespace after a newline. In other respects
157 it acts like wrap().
159 When called in list context, C<wrap()> will return a list of lines and
160 C<fill()> will return a list of paragraphs.
162 Historical notes: Older versions of C<wrap()> and C<fill()> always
163 returned strings. Also, 'die' used to be the default value of
164 C<$huge>. Now, 'wrap' is the default value.
166 =head1 EXAMPLE
168 print wrap("\t","","This is a bit of text that forms
169 a normal book-style paragraph");
171 =head1 AUTHOR
173 David Muir Sharnoff <muir@idiom.com> with help from Tim Pierce and
174 many many others.