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