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.0929;
  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         my $nll = $columns - length(expand($xp)) - 1;
  38         my $nl = "";
  39         my $remainder = "";
  40
  41         use re 'taint';
  42
  43         pos($t) = 0;
  44         while ($t !~ /\G\s*\Z/gc) {
  45                 if ($t =~ /\G([^\n]{0,$ll})($break|\z)/xmgc) {
  46                         $r .= $unexpand
  47                                 ? unexpand($nl . $lead . $1)
  48                                 : $nl . $lead . $1;
  49                         $remainder = $2;
  50                 } elsif ($huge eq 'wrap' && $t =~ /\G([^\n]{$ll})/gc) {
  51                         $r .= $unexpand
  52                                 ? unexpand($nl . $lead . $1)
  53                                 : $nl . $lead . $1;
  54                         $remainder = $separator;
  55                 } elsif ($huge eq 'overflow' && $t =~ /\G([^\n]*?)($break|\z)/xmgc) {
  56                         $r .= $unexpand
  57                                 ? unexpand($nl . $lead . $1)
  58                                 : $nl . $lead . $1;
  59                         $remainder = $2;
  60                 } elsif ($huge eq 'die') {
  61                         die "couldn't wrap '$t'";
  62                 } else {
  63                         die "This shouldn't happen";
  64                 }
  65
  66                 $lead = $xp;
  67                 $ll = $nll;
  68                 $nl = $separator;
  69         }
  70         $r .= $remainder;
  71
  72         print "-----------$r---------\n" if $debug;
  73
  74         print "Finish up with '$lead'\n" if $debug;
  75
  76         $r .= $lead . substr($t, pos($t), length($t)-pos($t))
  77                 if pos($t) ne length($t);
  78
  79         print "-----------$r---------\n" if $debug;;
  80
  81         return $r;
  82 }
  83
  84 sub fill
  85 {
  86         my ($ip, $xp, @raw) = @_;
  87         my @para;
  88         my $pp;
  89
  90         for $pp (split(/\n\s+/, join("\n",@raw))) {
  91                 $pp =~ s/\s+/ /g;
  92                 my $x = wrap($ip, $xp, $pp);
  93                 push(@para, $x);
  94         }
  95
  96         # if paragraph_indent is the same as line_indent,
  97         # separate paragraphs with blank lines
  98
  99         my $ps = ($ip eq $xp) ? "\n\n" : "\n";
 100         return join ($ps, @para);
 101 }
 102
 103 1;
 104 __END__
 105
 106 =head1 NAME
 107
 108 Text::Wrap - line wrapping to form simple paragraphs
 109
 110 =head1 SYNOPSIS
 111
 112 B<Example 1>
 113
 114         use Text::Wrap
 115
 116         $initial_tab = "\t";    # Tab before first line
 117         $subsequent_tab = "";   # All other lines flush left
 118
 119         print wrap($initial_tab, $subsequent_tab, @text);
 120         print fill($initial_tab, $subsequent_tab, @text);
 121
 122         @lines = wrap($initial_tab, $subsequent_tab, @text);
 123
 124         @paragraphs = fill($initial_tab, $subsequent_tab, @text);
 125
 126 B<Example 2>
 127
 128         use Text::Wrap qw(wrap $columns $huge);
 129
 130         $columns = 132;         # Wrap at 132 characters
 131         $huge = 'die';
 132         $huge = 'wrap';
 133         $huge = 'overflow';
 134
 135 B<Example 3>
 136
 137         use Text::Wrap
 138
 139         $Text::Wrap::columns = 72;
 140         print wrap('', '', @text);
 141
 142 =head1 DESCRIPTION
 143
 144 C<Text::Wrap::wrap()> is a very simple paragraph formatter.  It formats a
 145 single paragraph at a time by breaking lines at word boundries.
 146 Indentation is controlled for the first line (C<$initial_tab>) and
 147 all subsquent lines (C<$subsequent_tab>) independently.  Please note:
 148 C<$initial_tab> and C<$subsequent_tab> are the literal strings that will
 149 be used: it is unlikley you would want to pass in a number.
 150
 151 Text::Wrap::fill() is a simple multi-paragraph formatter.  It formats
 152 each paragraph separately and then joins them together when it's done.  It
 153 will destory any whitespace in the original text.  It breaks text into
 154 paragraphs by looking for whitespace after a newline.  In other respects
 155 it acts like wrap().
 156
 157 =head1 OVERRIDES
 158
 159 C<Text::Wrap::wrap()> has a number of variables that control its behavior.
 160 Because other modules might be using C<Text::Wrap::wrap()> it is suggested
 161 that you leave these variables alone!  If you can't do that, then
 162 use C<local($Text::Wrap::VARIABLE) = YOURVALUE> when you change the
 163 values so that the original value is restored.  This C<local()> trick
 164 will not work if you import the variable into your own namespace.
 165
 166 Lines are wrapped at C<$Text::Wrap::columns> columns.  C<$Text::Wrap::columns>
 167 should be set to the full width of your output device.  In fact,
 168 every resulting line will have length of no more than C<$columns - 1>.
 169
 170 It is possible to control which characters terminate words by
 171 modifying C<$Text::Wrap::break>. Set this to a string such as
 172 C<'[\s:]'> (to break before spaces or colons) or a pre-compiled regexp
 173 such as C<qr/[\s']/> (to break before spaces or apostrophes). The
 174 default is simply C<'\s'>; that is, words are terminated by spaces.
 175 (This means, among other things, that trailing punctuation  such as
 176 full stops or commas stay with the word they are "attached" to.)
 177
 178 Beginner note: In example 2, above C<$columns> is imported into
 179 the local namespace, and set locally.  In example 3,
 180 C<$Text::Wrap::columns> is set in its own namespace without importing it.
 181
 182 C<Text::Wrap::wrap()> starts its work by expanding all the tabs in its
 183 input into spaces.  The last thing it does it to turn spaces back
 184 into tabs.  If you do not want tabs in your results, set
 185 C<$Text::Wrap::unexapand> to a false value.  Likewise if you do not
 186 want to use 8-character tabstops, set C<$Text::Wrap::tabstop> to
 187 the number of characters you do want for your tabstops.
 188
 189 If you want to separate your lines with something other than C<\n>
 190 then set C<$Text::Wrap::seporator> to your preference.
 191
 192 When words that are longer than C<$columns> are encountered, they
 193 are broken up.  C<wrap()> adds a C<"\n"> at column C<$columns>.
 194 This behavior can be overridden by setting C<$huge> to
 195 'die' or to 'overflow'.  When set to 'die', large words will cause
 196 C<die()> to be called.  When set to 'overflow', large words will be
 197 left intact.
 198
 199 Historical notes: 'die' used to be the default value of
 200 C<$huge>.  Now, 'wrap' is the default value.
 201
 202 =head1 EXAMPLE
 203
 204         print wrap("\t","","This is a bit of text that forms
 205                 a normal book-style paragraph");
 206
 207 =head1 AUTHOR
 208
 209 David Muir Sharnoff <muir@idiom.com> with help from Tim Pierce and
 210 many many others.
 211