Debian Codegraph @

upstream/debian-unstable/man3/Text::Wrap.3perl

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