Text::Wrap(3pm)

1Text::Wrap(3pm)        Perl Programmers Reference Guide        Text::Wrap(3pm)
2
3
4

NAME

6       Text::Wrap - line wrapping to form simple paragraphs
7

SYNOPSIS

9       Example 1
10
11               use Text::Wrap;
12
13               $initial_tab = "\t";    # Tab before first line
14               $subsequent_tab = "";   # All other lines flush left
15
16               print wrap($initial_tab, $subsequent_tab, @text);
17               print fill($initial_tab, $subsequent_tab, @text);
18
19               $lines = wrap($initial_tab, $subsequent_tab, @text);
20
21               @paragraphs = fill($initial_tab, $subsequent_tab, @text);
22
23       Example 2
24
25               use Text::Wrap qw(wrap $columns $huge);
26
27               $columns = 132;         # Wrap at 132 characters
28               $huge = 'die';
29               $huge = 'wrap';
30               $huge = 'overflow';
31
32       Example 3
33
34               use Text::Wrap;
35
36               $Text::Wrap::columns = 72;
37               print wrap('', '', @text);
38

DESCRIPTION

40       "Text::Wrap::wrap()" is a very simple paragraph formatter.  It formats
41       a single paragraph at a time by breaking lines at word boundaries.
42       Indentation is controlled for the first line ($initial_tab) and all
43       subsequent lines ($subsequent_tab) independently.  Please note:
44       $initial_tab and $subsequent_tab are the literal strings that will be
45       used: it is unlikely you would want to pass in a number.
46
47       Text::Wrap::fill() is a simple multi-paragraph formatter.  It formats
48       each paragraph separately and then joins them together when it's done.
49       It will destroy any whitespace in the original text.  It breaks text
50       into paragraphs by looking for whitespace after a newline.  In other
51       respects it acts like wrap().
52
53       Both "wrap()" and "fill()" return a single string.
54

OVERRIDES

56       "Text::Wrap::wrap()" has a number of variables that control its
57       behavior.  Because other modules might be using "Text::Wrap::wrap()" it
58       is suggested that you leave these variables alone!  If you can't do
59       that, then use "local($Text::Wrap::VARIABLE) = YOURVALUE" when you
60       change the values so that the original value is restored.  This
61       "local()" trick will not work if you import the variable into your own
62       namespace.
63
64       Lines are wrapped at $Text::Wrap::columns columns (default value: 76).
65       $Text::Wrap::columns should be set to the full width of your output
66       device.  In fact, every resulting line will have length of no more than
67       "$columns - 1".
68
69       It is possible to control which characters terminate words by modifying
70       $Text::Wrap::break. Set this to a string such as '[\s:]' (to break
71       before spaces or colons) or a pre-compiled regexp such as "qr/[\s']/"
72       (to break before spaces or apostrophes). The default is simply '\s';
73       that is, words are terminated by spaces.  (This means, among other
74       things, that trailing punctuation  such as full stops or commas stay
75       with the word they are "attached" to.)  Setting $Text::Wrap::break to a
76       regular expression that doesn't eat any characters (perhaps just a
77       forward look-ahead assertion) will cause warnings.
78
79       Beginner note: In example 2, above $columns is imported into the local
80       namespace, and set locally.  In example 3, $Text::Wrap::columns is set
81       in its own namespace without importing it.
82
83       "Text::Wrap::wrap()" starts its work by expanding all the tabs in its
84       input into spaces.  The last thing it does it to turn spaces back into
85       tabs.  If you do not want tabs in your results, set
86       $Text::Wrap::unexpand to a false value.  Likewise if you do not want to
87       use 8-character tabstops, set $Text::Wrap::tabstop to the number of
88       characters you do want for your tabstops.
89
90       If you want to separate your lines with something other than "\n" then
91       set $Text::Wrap::separator to your preference.  This replaces all
92       newlines with $Text::Wrap::separator.  If you just want to preserve
93       existing newlines but add new breaks with something else, set
94       $Text::Wrap::separator2 instead.
95
96       When words that are longer than $columns are encountered, they are
97       broken up.  "wrap()" adds a "\n" at column $columns.  This behavior can
98       be overridden by setting $huge to 'die' or to 'overflow'.  When set to
99       'die', large words will cause "die()" to be called.  When set to
100       'overflow', large words will be left intact.
101
102       Historical notes: 'die' used to be the default value of $huge.  Now,
103       'wrap' is the default value.
104

EXAMPLES

106       Code:
107
108         print wrap("\t","",<<END);
109         This is a bit of text that forms
110         a normal book-style indented paragraph
111         END
112
113       Result:
114
115         "     This is a bit of text that forms
116         a normal book-style indented paragraph
117         "
118
119       Code:
120
121         $Text::Wrap::columns=20;
122         $Text::Wrap::separator="|";
123         print wrap("","","This is a bit of text that forms a normal book-style paragraph");
124
125       Result:
126
127         "This is a bit of|text that forms a|normal book-style|paragraph"
128

LICENSE

134       David Muir Sharnoff <muir@idiom.org> with help from Tim Pierce and many
135       many others.  Copyright (C) 1996-2009 David Muir Sharnoff.  This module
136       may be modified, used, copied, and redistributed at your own risk.
137       Publicly redistributed versions that are modified must use a different
138       name.
139
140
141
142perl v5.12.4                      2011-06-01                   Text::Wrap(3pm)

NAME

SYNOPSIS

DESCRIPTION

OVERRIDES

EXAMPLES

SEE ALSO

LICENSE