Debian Codegraph @

upstream/mageia-cauldron/man3pm/Text::Wrap.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Text::Wrap 3pm"
61 .TH Text::Wrap 3pm 2024-05-07 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Text::Wrap \- line wrapping to form simple paragraphs
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 \&\fBExample 1\fR
71 .PP
72 .Vb 1
73 \& use Text::Wrap;
74 \&
75 \& $initial_tab = "\et"; # Tab before first line
76 \& $subsequent_tab = ""; # All other lines flush left
77 \&
78 \& print wrap($initial_tab, $subsequent_tab, @text);
79 \& print fill($initial_tab, $subsequent_tab, @text);
80 \&
81 \& $lines = wrap($initial_tab, $subsequent_tab, @text);
82 \&
83 \& @paragraphs = fill($initial_tab, $subsequent_tab, @text);
84 .Ve
85 .PP
86 \&\fBExample 2\fR
87 .PP
88 .Vb 1
89 \& use Text::Wrap qw(wrap $columns $huge);
90 \&
91 \& $columns = 132; # Wrap at 132 characters
92 \& $huge = \*(Aqdie\*(Aq;
93 \& $huge = \*(Aqwrap\*(Aq;
94 \& $huge = \*(Aqoverflow\*(Aq;
95 .Ve
96 .PP
97 \&\fBExample 3\fR
98 .PP
99 .Vb 1
100 \& use Text::Wrap;
101 \&
102 \& $Text::Wrap::columns = 72;
103 \& print wrap(\*(Aq\*(Aq, \*(Aq\*(Aq, @text);
104 .Ve
105 .SH DESCRIPTION
106 .IX Header "DESCRIPTION"
107 \&\f(CWText::Wrap::wrap()\fR is a very simple paragraph formatter. It formats a
108 single paragraph at a time by breaking lines at word boundaries.
109 Indentation is controlled for the first line (\f(CW$initial_tab\fR) and
110 all subsequent lines (\f(CW$subsequent_tab\fR) independently. Please note:
111 \&\f(CW$initial_tab\fR and \f(CW$subsequent_tab\fR are the literal strings that will
112 be used: it is unlikely you would want to pass in a number.
113 .PP
114 \&\f(CWText::Wrap::fill()\fR is a simple multi\-paragraph formatter. It formats
115 each paragraph separately and then joins them together when it\*(Aqs done. It
116 will destroy any whitespace in the original text. It breaks text into
117 paragraphs by looking for whitespace after a newline. In other respects,
118 it acts like \fBwrap()\fR.
119 .PP
120 \&\f(CWwrap()\fR compresses trailing whitespace into one newline, and \f(CWfill()\fR
121 deletes all trailing whitespace.
122 .PP
123 Both \f(CWwrap()\fR and \f(CWfill()\fR return a single string.
124 .PP
125 Unlike the old Unix \fBfmt\fR\|(1) utility, this module correctly accounts for
126 any Unicode combining characters (such as diacriticals) that may occur
127 in each line for both expansion and unexpansion. These are overstrike
128 characters that do not increment the logical position. Make sure
129 you have the appropriate Unicode settings enabled.
130 .SH OVERRIDES
131 .IX Header "OVERRIDES"
132 \&\f(CWText::Wrap::wrap()\fR has a number of variables that control its behavior.
133 Because other modules might be using \f(CWText::Wrap::wrap()\fR it is suggested
134 that you leave these variables alone! If you can\*(Aqt do that, then
135 use \f(CW\*(C`local($Text::Wrap::VARIABLE) = YOURVALUE\*(C'\fR when you change the
136 values so that the original value is restored. This \f(CWlocal()\fR trick
137 will not work if you import the variable into your own namespace.
138 .PP
139 Lines are wrapped at \f(CW$Text::Wrap::columns\fR columns (default value: 76).
140 \&\f(CW$Text::Wrap::columns\fR should be set to the full width of your output
141 device. In fact, every resulting line will have length of no more than
142 \&\f(CW\*(C`$columns \- 1\*(C'\fR.
143 .PP
144 It is possible to control which characters terminate words by
145 modifying \f(CW$Text::Wrap::break\fR. Set this to a string such as
146 \&\f(CW\*(Aq[\es:]\*(Aq\fR (to break before spaces or colons) or a pre\-compiled regexp
147 such as \f(CW\*(C`qr/[\es\*(Aq]/\*(C'\fR (to break before spaces or apostrophes). The
148 default is simply \f(CW\*(Aq\es\*(Aq\fR; that is, words are terminated by spaces.
149 (This means, among other things, that trailing punctuation such as
150 full stops or commas stay with the word they are "attached" to.)
151 Setting \f(CW$Text::Wrap::break\fR to a regular expression that doesn\*(Aqt
152 eat any characters (perhaps just a forward look\-ahead assertion) will
153 cause warnings.
154 .PP
155 Beginner note: In example 2, above \f(CW$columns\fR is imported into
156 the local namespace, and set locally. In example 3,
157 \&\f(CW$Text::Wrap::columns\fR is set in its own namespace without importing it.
158 .PP
159 \&\f(CWText::Wrap::wrap()\fR starts its work by expanding all the tabs in its
160 input into spaces. The last thing it does it to turn spaces back
161 into tabs. If you do not want tabs in your results, set
162 \&\f(CW$Text::Wrap::unexpand\fR to a false value. Likewise if you do not
163 want to use 8\-character tabstops, set \f(CW$Text::Wrap::tabstop\fR to
164 the number of characters you do want for your tabstops.
165 .PP
166 If you want to separate your lines with something other than \f(CW\*(C`\en\*(C'\fR
167 then set \f(CW$Text::Wrap::separator\fR to your preference. This replaces
168 all newlines with \f(CW$Text::Wrap::separator\fR. If you just want to
169 preserve existing newlines but add new breaks with something else, set
170 \&\f(CW$Text::Wrap::separator2\fR instead.
171 .PP
172 When words that are longer than \f(CW$columns\fR are encountered, they
173 are broken up. \f(CWwrap()\fR adds a \f(CW"\en"\fR at column \f(CW$columns\fR.
174 This behavior can be overridden by setting \f(CW$huge\fR to
175 \&\*(Aqdie\*(Aq or to \*(Aqoverflow\*(Aq. When set to \*(Aqdie\*(Aq, large words will cause
176 \&\f(CWdie()\fR to be called. When set to \*(Aqoverflow\*(Aq, large words will be
177 left intact.
178 .PP
179 Historical notes: \*(Aqdie\*(Aq used to be the default value of
180 \&\f(CW$huge\fR. Now, \*(Aqwrap\*(Aq is the default value.
181 .SH EXAMPLES
182 .IX Header "EXAMPLES"
183 Code:
184 .PP
185 .Vb 4
186 \& print wrap("\et","",<<END);
187 \& This is a bit of text that forms
188 \& a normal book\-style indented paragraph
189 \& END
190 .Ve
191 .PP
192 Result:
193 .PP
194 .Vb 3
195 \& " This is a bit of text that forms
196 \& a normal book\-style indented paragraph
197 \& "
198 .Ve
199 .PP
200 Code:
201 .PP
202 .Vb 3
203 \& $Text::Wrap::columns=20;
204 \& $Text::Wrap::separator="|";
205 \& print wrap("","","This is a bit of text that forms a normal book\-style paragraph");
206 .Ve
207 .PP
208 Result:
209 .PP
210 .Vb 1
211 \& "This is a bit of|text that forms a|normal book\-style|paragraph"
212 .Ve
213 .SH "SEE ALSO"
214 .IX Header "SEE ALSO"
215 For correct handling of East Asian half\- and full\-width characters,
216 see Text::WrapI18N. For more detailed controls: Text::Format.
217 .SH AUTHOR
218 .IX Header "AUTHOR"
219 David Muir Sharnoff <[email protected]> with help from Tim Pierce and
220 many many others.
221 .SH LICENSE
222 .IX Header "LICENSE"
223 Copyright (C) 1996\-2009 David Muir Sharnoff.
224 Copyright (C) 2012\-2013 Google, Inc.
225 This module may be modified, used, copied, and redistributed at your own risk.
226 Although allowed by the preceding license, please do not publicly
227 redistribute modified versions of this code with the name "Text::Wrap"
228 unless it passes the unmodified Text::Wrap test suite.