1Text::Format(3) User Contributed Perl Documentation Text::Format(3)
2
6 Text::Format - Various subroutines to format text.
7
9 version 0.62
10
12 use Text::Format;
13 my $text = Text::Format->new (
15 {
16 text => [], # all
17 columns => 72, # format, paragraphs, center
18 leftMargin => 0, # format, paragraphs, center
19 rightMargin => 0, # format, paragraphs, center
20 firstIndent => 4, # format, paragraphs
21 bodyIndent => 0, # format, paragraphs
22 rightFill => 0, # format, paragraphs
23 rightAlign => 0, # format, paragraphs
24 justify => 0, # format, paragraphs
25 extraSpace => 0, # format, paragraphs
26 abbrevs => {}, # format, paragraphs
27 hangingIndent => 0, # format, paragraphs
28 hangingText => [], # format, paragraphs
29 noBreak => 0, # format, paragraphs
30 noBreakRegex => {}, # format, paragraphs
31 tabstop => 8, # expand, unexpand, center
32 }
33 ); # these are the default values
34 my %abbr = (foo => 1, bar => 1);
36 $text->abbrevs(\%abbr);
37 $text->abbrevs();
38 $text->abbrevs({foo => 1,bar => 1});
39 $text->abbrevs(qw/foo bar/);
40 $text->text(\@text);
41 $text->columns(132);
43 $text->tabstop(4);
44 $text->extraSpace(1);
45 $text->firstIndent(8);
46 $text->bodyIndent(4);
47 $text->config({tabstop => 4,firstIndent => 0});
48 $text->rightFill(0);
49 $text->rightAlign(0);
50
52 The format routine will format under all circumstances even if the
53 width isn't enough to contain the longest words. Text::Wrap will die
54 under these circumstances, although I am told this is fixed. If
55 columns is set to a small number and words are longer than that and the
56 leading 'whitespace' than there will be a single word on each line.
57 This will let you make a simple word list which could be indented or
58 right aligned. There is a chance for croaking if you try to subvert
59 the module. If you don't pass in text then the internal text is worked
60 on, though not modified.
61 Text::Format is meant for more powerful text formatting than what
63 Text::Wrap allows. I also have a module called Text::NWrap that is
64 meant as a direct replacement for Text::Wrap. Text::NWrap requires
65 Text::Format since it uses Text::Format->format to do the actual
66 wrapping but gives you the interface of Text::Wrap.
67 General setup should be explained with the below graph.
69 columns
71 <------------------------------------------------------------>
72 <----------><------><---------------------------><----------->
73 leftMargin indent text is formatted into here rightMargin
74 indent is firstIndent or bodyIndent depending on where we are in the
76 paragraph.
77 format @ARRAY || \@ARRAY || [<FILEHANDLE>] || NOTHING
79 Allows one to do some advanced formatting of text into a paragraph,
80 with indent for first line and body set separately. Can specify
81 total width of text, right fill with spaces or right align or
82 justify (align to both margins), right margin and left margin, non-
83 breaking space, two spaces at end of sentence, hanging indents
84 (tagged paragraphs). Strips all leading and trailing whitespace
85 before proceeding. Text is first split into words and then
86 reassembled. If no text is passed in then the internal text in the
87 object is formatted.
88 paragraphs @ARRAY || \@ARRAY || [<FILEHANDLE>] || NOTHING
90 Considers each element of text as a paragraph and if the indents
91 are the same for first line and the body then the paragraphs are
92 separated by a single empty line otherwise they follow one under
93 the other. If hanging indent is set then a single empty line will
94 separate each paragraph as well. Calls format to do the actual
95 formatting. If no text is passed in then the internal text in the
96 object is formatted, though not changed.
97 center @ARRAY || NOTHING
99 Centers a list of strings in @ARRAY or internal text. Empty lines
100 appear as, you guessed it, empty lines. Center strips all leading
101 and trailing whitespace before proceeding. Left margin and right
102 margin can be set. If no text is passed in then the internal text
103 in the object is formatted.
104 expand @ARRAY || NOTHING
106 Expand tabs in the list of text to tabstop number of spaces in
107 @ARRAY or internal text. Doesn't modify the internal text just
108 passes back the modified text. If no text is passed in then the
109 internal text in the object is formatted.
110 unexpand @ARRAY || NOTHING
112 Tabstop number of spaces are turned into tabs in @ARRAY or internal
113 text. Doesn't modify the internal text just passes back the
114 modified text. If no text is passed in then the internal text in
115 the object is formatted.
116 new \%HASH || NOTHING
118 Instantiates the object. If you pass a reference to a hash, or an
119 anonymous hash then it is used in setting attributes.
120 config \%HASH
122 Allows the configuration of all object attributes at once. Returns
123 the object prior to configuration. You can use it to make a clone
124 of your object before you change attributes.
125 columns NUMBER || NOTHING
127 Set width of text or retrieve width. This is total width and
128 includes indentation and the right and left margins.
129 tabstop NUMBER || NOTHING
131 Set tabstop size or retrieve tabstop size, only used by expand,
132 unexpand and center.
133 firstIndent NUMBER || NOTHING
135 Set or get indent for the first line of paragraph. This is the
136 number of spaces to indent.
137 bodyIndent NUMBER || NOTHING
139 Set or get indent for the body of paragraph. This is the number of
140 spaces to indent.
141 leftMargin NUMBER || NOTHING
143 Set or get width of left margin. This is the number of spaces used
144 for the margin.
145 rightMargin NUMBER || NOTHING
147 Set or get width of right margin. This is the number of spaces
148 used for the margin.
149 rightFill 0 || 1 || NOTHING
151 Set right fill or retrieve its value. The filling is done with
152 spaces. Keep in mind that if rightAlign is also set then both
153 rightFill and rightAlign are ignored.
154 rightAlign 0 || 1 || NOTHING
156 Set right align or retrieve its value. Text is aligned with the
157 right side of the margin. Keep in mind that if rightFill is also
158 set then both rightFill and rightAlign are ignored.
159 justify 0 || 1 || NOTHING
161 Set justify or retrieve its value. Text is aligned with both
162 margins, adding extra spaces as necessary to align text with left
163 and right margins. Keep in mind that if either of rightAlign or
164 rightFill are set then justify is ignored, even if both are set in
165 which case they are all ignored.
166 text \@ARRAY || NOTHING
168 Pass in a reference to your text, or an anonymous array of text
169 that you want the routines to manipulate. Returns the text held in
170 the object.
171 hangingIndent 0 || 1 || NOTHING
173 Use hanging indents in front of a paragraph, returns current value
174 of attribute. This is also called a tagged paragraph.
175 hangingText \@ARRAY || NOTHING
177 The text that will be displayed in front of each paragraph, if you
178 call format then only the first element is used, if you call
179 paragraphs then paragraphs cycles through all of them. If you have
180 more paragraphs than elements in your array than the remainder of
181 the paragraphs will not have a hanging indented text. Pass a
182 reference to your array. This is also called a tagged paragraph.
183 noBreak 0 || 1 || NOTHING
185 Set whether you want to use the non-breaking space feature (see
186 noBreakRegex below).
187 noBreakRegex \%HASH || NOTHING
189 Pass in a reference to a hash that would hold the regexes on which
190 not to break. In order for this to happen, it requires noBreak to
191 be set to true - see above. Without any arguments, it returns the
192 hash. E.g:
193 {'^Mrs?\.$' => '^\S+$','^\S+$' => '^(?:S|J)r\.$'}
195 don't break names such as Mr. Jones, Mrs. Jones, Jones Jr.
197 The breaking algorithm is simple. If there should not be a break
199 at the current end of sentence, then a backtrack is done till there
200 are two words on which breaking is allowed. If no two such words
201 are found then the end of sentence is broken anyhow. If there is a
202 single word on current line then no backtrack is done and the word
203 is stuck on the end. This is so you can make a list of names for
204 example.
205 Note: this feature requires noBreak to be set to true.
207 extraSpace 0 || 1 || NOTHING
209 Add extra space after end of sentence, normally format would add 1
210 space after end of sentence, if this is set to 1 then 2 spaces are
211 used. Abbreviations are not followed by two spaces. There are a
212 few internal abbreviations and you can add your own to the object
213 with abbrevs
214 abbrevs \%HASH || @ARRAY || NOTHING
216 Add to the current abbreviations, takes a reference to your hash or
217 an array of abbreviations, if called a second time the original
218 reference is removed and replaced by the new one. Returns the
219 current INTERNAL abbreviations.
220
222 use Text::Format;
223 my $text = Text::Format->new;
225 $text->rightFill(1);
227 $text->columns(65);
228 $text->tabstop(4);
229 print $text->format("a line to format to an indented regular
231 paragraph using 65 character wide display");
232 print $text->paragraphs("paragraph one","paragraph two");
233 print $text->center("hello world","nifty line 2");
234 print $text->expand("\t\thello world\n","hmm,\twell\n");
235 print $text->unexpand(" hello world\n"," hmm");
236 $text->config({columns => 132, tabstop => 4});
238 $text = Text::Format->new();
240 print $text->format(@text);
242 print $text->paragraphs(@text);
243 print $text->center(@text);
244 print $text->format([<FILEHANDLE>]);
245 print $text->format([$fh->getlines()]);
246 print $text->paragraphs([<FILEHANDLE>]);
247 print $text->expand(@text);
248 print $text->unexpand(@text);
249 $text = Text::Format->new
251 ({tabstop => 4,bodyIndent => 4,text => \@text});
252 print $text->format();
254 print $text->paragraphs();
255 print $text->center();
256 print $text->expand();
257 print $text->unexpand();
258 print Text::Format->new({columns => 95})->format(@text);
260
262 Line length can exceed the number of specified columns if columns is
263 set to a small number and long words plus leading whitespace exceed the
264 specified column length. Actually I see this as a feature since it can
265 be used to make up a nice word list.
266
268 Copyright (c) 1998 Gabor Egressy. All rights reserved.
269 This program is free software; you can redistribute and/or modify it
271 under the same terms as Perl itself.
272
274 Gabor Egressy gabor@vmunix.com
275 Copyright (c) 1998 Gabor Egressy. All rights reserved. All wrongs
277 reversed. This program is free software; you can redistribute and/or
278 modify it under the same terms as Perl itself.
279 Adopted and modified by Shlomi Fish, <http://www.shlomifish.org/> - all
281 rights disclaimed.
282
284 Tom Phoenix
285 Found a bug with code for two spaces at the end of the sentence and
287 provided a code fragment for a better solution. Also some preliminary
288 suggestions on the design.
289 Brad Appleton
291 Suggestion and explanation of hanging indents, suggestion for non-
293 breaking whitespace, general suggestions with regard to interface
294 design.
295 Byron Brummer
297 Suggestion for better interface design and object design, code for
299 better implementation of getting abbreviations.
300 H. Merijn Brand
302 Suggestion for a justify feature and original code for doing the
304 justification. I changed the code to take into account the extra space
305 at end of sentence feature.
306 Anne Wainwright
308 Inspired a documentation clarification about noBreak required by
310 noBreakRegex , thanks to a report with a problem.
311
314 Websites
315 The following websites have more information about this module, and may
316 be of help to you. As always, in addition to those websites please use
317 your favorite search engine to discover more resources.
318 • MetaCPAN
320 A modern, open-source CPAN search engine, useful to view POD in
322 HTML format.
323 <https://metacpan.org/release/Text-Format>
325 • RT: CPAN's Bug Tracker
327 The RT ( Request Tracker ) website is the default bug/issue
329 tracking system for CPAN.
330 <https://rt.cpan.org/Public/Dist/Display.html?Name=Text-Format>
332 • CPANTS
334 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
336 of a distribution.
337 <http://cpants.cpanauthors.org/dist/Text-Format>
339 • CPAN Testers
341 The CPAN Testers is a network of smoke testers who run automated
343 tests on uploaded CPAN distributions.
344 <http://www.cpantesters.org/distro/T/Text-Format>
346 • CPAN Testers Matrix
348 The CPAN Testers Matrix is a website that provides a visual
350 overview of the test results for a distribution on various
351 Perls/platforms.
352 <http://matrix.cpantesters.org/?dist=Text-Format>
354 • CPAN Testers Dependencies
356 The CPAN Testers Dependencies is a website that shows a chart of
358 the test results of all dependencies for a distribution.
359 <http://deps.cpantesters.org/?module=Text::Format>
361 Bugs / Feature Requests
363 Please report any bugs or feature requests by email to "bug-text-format
364 at rt.cpan.org", or through the web interface at
365 <https://rt.cpan.org/Public/Bug/Report.html?Queue=Text-Format>. You
366 will be automatically notified of any progress on the request by the
367 system.
368 Source Code
370 The code is open to the world, and available for you to hack on. Please
371 feel free to browse it and play with it, or whatever. If you want to
372 contribute patches, please send me a diff or prod me to pull from your
373 repository :)
374 <https://github.com/shlomif/perl-Module-Format>
376 git clone https://github.com/shlomif/perl-Module-Format
378
380 Shlomi Fish <shlomif@cpan.org>
381
383 Please report any bugs or feature requests on the bugtracker website
384 <https://github.com/shlomif/perl-Module-Format/issues>
385 When submitting a bug or request, please include a test-file or a patch
387 to an existing test-file that illustrates the bug or desired feature.
388
390 This software is copyright (c) 2020 by Gabor Egressy.
391 This is free software; you can redistribute it and/or modify it under
393 the same terms as the Perl 5 programming language system itself.
394perl v5.38.0 2023-07-21 Text::Format(3)