home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _fd1f5eb1b784ac21d03b03d724eeab22 < prev    next >
Text File  |  2004-06-01  |  6KB  |  213 lines
  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.  
  213.