This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Update docs and English.pm for $^C
[perl5.git] / lib / Text / Wrap.pm
CommitLineData
4633a7c4
LW
1package Text::Wrap;
2
4abe8f91 3use vars qw(@ISA @EXPORT @EXPORT_OK $VERSION $columns $debug $min_wrap_width);
9b599b2a
GS
4use strict;
5use Exporter;
4633a7c4 6
4abe8f91 7$VERSION = "97.03";
9b599b2a 8@ISA = qw(Exporter);
4633a7c4 9@EXPORT = qw(wrap);
4abe8f91 10@EXPORT_OK = qw($columns $tabstop $min_wrap_width fill);
4633a7c4 11
9b599b2a 12use Text::Tabs qw(expand unexpand $tabstop);
b1a524cb 13
b1a524cb 14
4633a7c4 15BEGIN {
9b599b2a
GS
16 $columns = 76; # <= screen width
17 $debug = 0;
4abe8f91
GS
18 # minimum wrap width (leaders will be shortened to accomodate this)
19 $min_wrap_width = int($columns/5);
4633a7c4
LW
20}
21
4633a7c4
LW
22sub wrap
23{
9b599b2a
GS
24 my ($ip, $xp, @t) = @_;
25
26 my @rv;
27 my $t = expand(join(" ",@t));
28
4abe8f91
GS
29 my $xll = $columns - length(expand($xp)) - 1;
30 while ($xll < $min_wrap_width) {
31 chop $xp;
32 $xll = $columns - length(expand($xp)) - 1;
33 }
34
35 my $ll = $columns - length(expand($ip)) - 1;
36 while ($ll < $min_wrap_width) {
37 chop $ip;
38 $ll = $columns - length(expand($ip)) - 1;
39 }
9b599b2a 40 my $lead = $ip;
9b599b2a
GS
41 my $nl = "";
42
43 $t =~ s/^\s+//;
44 while(length($t) > $ll) {
45 # remove up to a line length of things that
46 # aren't new lines and tabs.
47 if ($t =~ s/^([^\n]{0,$ll})(\s|\Z(?!\n))//) {
48 my ($l,$r) = ($1,$2);
49 $l =~ s/\s+$//;
50 print "WRAP $lead$l..($r)\n" if $debug;
51 push @rv, unexpand($lead . $l), "\n";
52
53 } elsif ($t =~ s/^([^\n]{$ll})//) {
54 print "SPLIT $lead$1..\n" if $debug;
55 push @rv, unexpand($lead . $1),"\n";
56 }
4abe8f91 57 # reset the leader
9b599b2a 58 $lead = $xp;
4abe8f91 59 $ll = $xll;
9b599b2a
GS
60 $t =~ s/^\s+//;
61 }
62 print "TAIL $lead$t\n" if $debug;
63 push @rv, $lead.$t if $t ne "";
64 return join '', @rv;
65}
b1a524cb 66
b1a524cb 67
9b599b2a
GS
68sub fill
69{
70 my ($ip, $xp, @raw) = @_;
71 my @para;
72 my $pp;
b1a524cb 73
9b599b2a
GS
74 for $pp (split(/\n\s+/, join("\n",@raw))) {
75 $pp =~ s/\s+/ /g;
76 my $x = wrap($ip, $xp, $pp);
77 push(@para, $x);
78 }
b1a524cb 79
9b599b2a
GS
80 # if paragraph_indent is the same as line_indent,
81 # separate paragraphs with blank lines
b1a524cb 82
9b599b2a 83 return join ($ip eq $xp ? "\n\n" : "\n", @para);
4633a7c4
LW
84}
85
861;
68e56a55 87__END__
b1a524cb
PP
88
89=head1 NAME
90
91Text::Wrap - line wrapping to form simple paragraphs
92
93=head1 SYNOPSIS
94
95 use Text::Wrap
96
97 print wrap($initial_tab, $subsequent_tab, @text);
98
9b599b2a 99 use Text::Wrap qw(wrap $columns $tabstop fill);
b1a524cb
PP
100
101 $columns = 132;
9b599b2a
GS
102 $tabstop = 4;
103
104 print fill($initial_tab, $subsequent_tab, @text);
105 print fill("", "", `cat book`);
b1a524cb
PP
106
107=head1 DESCRIPTION
108
4fc6b8d8 109Text::Wrap::wrap() is a very simple paragraph formatter. It formats a
b1a524cb
PP
110single paragraph at a time by breaking lines at word boundries.
111Indentation is controlled for the first line ($initial_tab) and
112all subsquent lines ($subsequent_tab) independently. $Text::Wrap::columns
4abe8f91
GS
113should be set to the full width of your output device (default is 76).
114$Text::Wrap::min_wrap_width controls the minimum number of columns that
115are reserved for the wrapped text (default is 15). Indentation will
116be reduced to accomodate this value.
b1a524cb 117
9b599b2a
GS
118Text::Wrap::fill() is a simple multi-paragraph formatter. It formats
119each paragraph separately and then joins them together when it's done. It
120will destory any whitespace in the original text. It breaks text into
121paragraphs by looking for whitespace after a newline. In other respects
122it acts like wrap().
123
b1a524cb
PP
124=head1 EXAMPLE
125
126 print wrap("\t","","This is a bit of text that forms
127 a normal book-style paragraph");
128
68e56a55
CS
129=head1 BUGS
130
131It's not clear what the correct behavior should be when Wrap() is
132presented with a word that is longer than a line. The previous
9b599b2a 133behavior was to die. Now the word is now split at line-length.
68e56a55 134
b1a524cb
PP
135=head1 AUTHOR
136
4fc6b8d8 137David Muir Sharnoff <muir@idiom.com> with help from Tim Pierce and
9b599b2a 138others. Updated by Jacqui Caren.
b1a524cb
PP
139
140=cut