mingw/html/lib/Text/Wrap.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>Text::Wrap - line wrapping to form simple paragraphs</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;Text::Wrap - line wrapping to form simple paragraphs</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#overrides">OVERRIDES</a></li>
  26         <li><a href="#example">EXAMPLE</a></li>
  27         <li><a href="#license">LICENSE</a></li>
  28 </ul>
  29 <!-- INDEX END -->
  30
  31 <hr />
  32 <p>
  33 </p>
  34 <h1><a name="name">NAME</a></h1>
  35 <p>Text::Wrap - line wrapping to form simple paragraphs</p>
  36 <p>
  37 </p>
  38 <hr />
  39 <h1><a name="synopsis">SYNOPSIS</a></h1>
  40 <p><strong>Example 1</strong></p>
  41 <pre>
  42         use Text::Wrap</pre>
  43 <pre>
  44         $initial_tab = &quot;\t&quot;;    # Tab before first line
  45         $subsequent_tab = &quot;&quot;;   # All other lines flush left</pre>
  46 <pre>
  47         print wrap($initial_tab, $subsequent_tab, @text);
  48         print fill($initial_tab, $subsequent_tab, @text);</pre>
  49 <pre>
  50         $lines = wrap($initial_tab, $subsequent_tab, @text);</pre>
  51 <pre>
  52         @paragraphs = fill($initial_tab, $subsequent_tab, @text);</pre>
  53 <p><strong>Example 2</strong></p>
  54 <pre>
  55         use Text::Wrap qw(wrap $columns $huge);</pre>
  56 <pre>
  57         $columns = 132;         # Wrap at 132 characters
  58         $huge = 'die';
  59         $huge = 'wrap';
  60         $huge = 'overflow';</pre>
  61 <p><strong>Example 3</strong></p>
  62 <pre>
  63         use Text::Wrap</pre>
  64 <pre>
  65         $Text::Wrap::columns = 72;
  66         print wrap('', '', @text);</pre>
  67 <p>
  68 </p>
  69 <hr />
  70 <h1><a name="description">DESCRIPTION</a></h1>
  71 <p><code>Text::Wrap::wrap()</code> is a very simple paragraph formatter.  It formats a
  72 single paragraph at a time by breaking lines at word boundries.
  73 Indentation is controlled for the first line (<code>$initial_tab</code>) and
  74 all subsequent lines (<code>$subsequent_tab</code>) independently.  Please note:
  75 <code>$initial_tab</code> and <code>$subsequent_tab</code> are the literal strings that will
  76 be used: it is unlikley you would want to pass in a number.</p>
  77 <p>Text::Wrap::fill() is a simple multi-paragraph formatter.  It formats
  78 each paragraph separately and then joins them together when it's done.  It
  79 will destroy any whitespace in the original text.  It breaks text into
  80 paragraphs by looking for whitespace after a newline.  In other respects
  81 it acts like wrap().</p>
  82 <p>
  83 </p>
  84 <hr />
  85 <h1><a name="overrides">OVERRIDES</a></h1>
  86 <p><code>Text::Wrap::wrap()</code> has a number of variables that control its behavior.
  87 Because other modules might be using <code>Text::Wrap::wrap()</code> it is suggested
  88 that you leave these variables alone!  If you can't do that, then
  89 use <code>local($Text::Wrap::VARIABLE) = YOURVALUE</code> when you change the
  90 values so that the original value is restored.  This <code>local()</code> trick
  91 will not work if you import the variable into your own namespace.</p>
  92 <p>Lines are wrapped at <code>$Text::Wrap::columns</code> columns.  <code>$Text::Wrap::columns</code>
  93 should be set to the full width of your output device.  In fact,
  94 every resulting line will have length of no more than <code>$columns - 1</code>.</p>
  95 <p>It is possible to control which characters terminate words by
  96 modifying <code>$Text::Wrap::break</code>. Set this to a string such as
  97 <code>'[\s:]'</code> (to break before spaces or colons) or a pre-compiled regexp
  98 such as <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_qr_"><code>qr/[\s']/</code></a> (to break before spaces or apostrophes). The
  99 default is simply <code>'\s'</code>; that is, words are terminated by spaces.
 100 (This means, among other things, that trailing punctuation  such as
 101 full stops or commas stay with the word they are ``attached'' to.)</p>
 102 <p>Beginner note: In example 2, above <code>$columns</code> is imported into
 103 the local namespace, and set locally.  In example 3,
 104 <code>$Text::Wrap::columns</code> is set in its own namespace without importing it.</p>
 105 <p><code>Text::Wrap::wrap()</code> starts its work by expanding all the tabs in its
 106 input into spaces.  The last thing it does it to turn spaces back
 107 into tabs.  If you do not want tabs in your results, set
 108 <code>$Text::Wrap::unexpand</code> to a false value.  Likewise if you do not
 109 want to use 8-character tabstops, set <code>$Text::Wrap::tabstop</code> to
 110 the number of characters you do want for your tabstops.</p>
 111 <p>If you want to separate your lines with something other than <code>\n</code>
 112 then set <code>$Text::Wrap::separator</code> to your preference.  This replaces
 113 all newlines with <code>$Text::Wrap::separator</code>.  If you just to preserve
 114 existing newlines but add new breaks with something else, set
 115 <code>$Text::Wrap::separator2</code> instead.</p>
 116 <p>When words that are longer than <code>$columns</code> are encountered, they
 117 are broken up.  <code>wrap()</code> adds a <code>&quot;\n&quot;</code> at column <code>$columns</code>.
 118 This behavior can be overridden by setting <code>$huge</code> to
 119 'die' or to 'overflow'.  When set to 'die', large words will cause
 120 <code>die()</code> to be called.  When set to 'overflow', large words will be
 121 left intact.</p>
 122 <p>Historical notes: 'die' used to be the default value of
 123 <code>$huge</code>.  Now, 'wrap' is the default value.</p>
 124 <p>
 125 </p>
 126 <hr />
 127 <h1><a name="example">EXAMPLE</a></h1>
 128 <pre>
 129         print wrap(&quot;\t&quot;,&quot;&quot;,&quot;This is a bit of text that forms
 130                 a normal book-style paragraph&quot;);</pre>
 131 <p>
 132 </p>
 133 <hr />
 134 <h1><a name="license">LICENSE</a></h1>
 135 <p>David Muir Sharnoff &lt;<a href="mailto:muir@idiom.com">muir@idiom.com</a>&gt; with help from Tim Pierce and
 136 many many others.  Copyright (C) 1996-2002 David Muir Sharnoff.
 137 This module may be modified, used, copied, and redistributed at
 138 your own risk.  Publicly redistributed modified versions must use
 139 a different name.</p>
 140 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 141 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 142 <big><strong><span class="block">&nbsp;Text::Wrap - line wrapping to form simple paragraphs</span></strong></big>
 143 </td></tr>
 144 </table>
 145
 146 </body>
 147
 148 </html>