lib/Text/Wrap.pm

   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.09291;
  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|\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 destory 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::unexapand> 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::seporator> 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