1Text::Format(3) User Contributed Perl Documentation Text::Format(3)
2
6 Text::Format - Various subroutines to format text.
7
9 version 0.61
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 version 0.61
223
225 use Text::Format;
226 my $text = Text::Format->new;
228 $text->rightFill(1);
230 $text->columns(65);
231 $text->tabstop(4);
232 print $text->format("a line to format to an indented regular
234 paragraph using 65 character wide display");
235 print $text->paragraphs("paragraph one","paragraph two");
236 print $text->center("hello world","nifty line 2");
237 print $text->expand("\t\thello world\n","hmm,\twell\n");
238 print $text->unexpand(" hello world\n"," hmm");
239 $text->config({columns => 132, tabstop => 4});
241 $text = Text::Format->new();
243 print $text->format(@text);
245 print $text->paragraphs(@text);
246 print $text->center(@text);
247 print $text->format([<FILEHANDLE>]);
248 print $text->format([$fh->getlines()]);
249 print $text->paragraphs([<FILEHANDLE>]);
250 print $text->expand(@text);
251 print $text->unexpand(@text);
252 $text = Text::Format->new
254 ({tabstop => 4,bodyIndent => 4,text => \@text});
255 print $text->format();
257 print $text->paragraphs();
258 print $text->center();
259 print $text->expand();
260 print $text->unexpand();
261 print Text::Format->new({columns => 95})->format(@text);
263
265 Line length can exceed the number of specified columns if columns is
266 set to a small number and long words plus leading whitespace exceed the
267 specified column length. Actually I see this as a feature since it can
268 be used to make up a nice word list.
269
271 Copyright (c) 1998 Gabor Egressy. All rights reserved.
272 This program is free software; you can redistribute and/or modify it
274 under the same terms as Perl itself.
275
277 Gabor Egressy gabor@vmunix.com
278 Copyright (c) 1998 Gabor Egressy. All rights reserved. All wrongs
280 reversed. This program is free software; you can redistribute and/or
281 modify it under the same terms as Perl itself.
282 Adopted and modified by Shlomi Fish, <http://www.shlomifish.org/> - all
284 rights disclaimed.
285
287 Tom Phoenix
288 Found a bug with code for two spaces at the end of the sentence and
290 provided a code fragment for a better solution. Also some preliminary
291 suggestions on the design.
292 Brad Appleton
294 Suggestion and explanation of hanging indents, suggestion for non-
296 breaking whitespace, general suggestions with regard to interface
297 design.
298 Byron Brummer
300 Suggestion for better interface design and object design, code for
302 better implementation of getting abbreviations.
303 H. Merijn Brand
305 Suggestion for a justify feature and original code for doing the
307 justification. I changed the code to take into account the extra space
308 at end of sentence feature.
309 Anne Wainwright
311 Inspired a documentation clarification about noBreak required by
313 noBreakRegex , thanks to a report with a problem.
314
317 Shlomi Fish <shlomif@cpan.org>
318
320 This software is copyright (c) 2018 by Gabor Egressy.
321 This is free software; you can redistribute it and/or modify it under
323 the same terms as the Perl 5 programming language system itself.
324
326 Please report any bugs or feature requests on the bugtracker website
327 <https://github.com/shlomif/text-format/issues>
328 When submitting a bug or request, please include a test-file or a patch
330 to an existing test-file that illustrates the bug or desired feature.
331
333 Perldoc
334 You can find documentation for this module with the perldoc command.
335 perldoc Text::Format
337 Websites
339 The following websites have more information about this module, and may
340 be of help to you. As always, in addition to those websites please use
341 your favorite search engine to discover more resources.
342 · MetaCPAN
344 A modern, open-source CPAN search engine, useful to view POD in
346 HTML format.
347 <https://metacpan.org/release/Text-Format>
349 · Search CPAN
351 The default CPAN search engine, useful to view POD in HTML format.
353 <http://search.cpan.org/dist/Text-Format>
355 · RT: CPAN's Bug Tracker
357 The RT ( Request Tracker ) website is the default bug/issue
359 tracking system for CPAN.
360 <https://rt.cpan.org/Public/Dist/Display.html?Name=Text-Format>
362 · AnnoCPAN
364 The AnnoCPAN is a website that allows community annotations of Perl
366 module documentation.
367 <http://annocpan.org/dist/Text-Format>
369 · CPAN Ratings
371 The CPAN Ratings is a website that allows community ratings and
373 reviews of Perl modules.
374 <http://cpanratings.perl.org/d/Text-Format>
376 · CPANTS
378 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
380 of a distribution.
381 <http://cpants.cpanauthors.org/dist/Text-Format>
383 · CPAN Testers
385 The CPAN Testers is a network of smoke testers who run automated
387 tests on uploaded CPAN distributions.
388 <http://www.cpantesters.org/distro/T/Text-Format>
390 · CPAN Testers Matrix
392 The CPAN Testers Matrix is a website that provides a visual
394 overview of the test results for a distribution on various
395 Perls/platforms.
396 <http://matrix.cpantesters.org/?dist=Text-Format>
398 · CPAN Testers Dependencies
400 The CPAN Testers Dependencies is a website that shows a chart of
402 the test results of all dependencies for a distribution.
403 <http://deps.cpantesters.org/?module=Text::Format>
405 Bugs / Feature Requests
407 Please report any bugs or feature requests by email to "bug-text-format
408 at rt.cpan.org", or through the web interface at
409 <https://rt.cpan.org/Public/Bug/Report.html?Queue=Text-Format>. You
410 will be automatically notified of any progress on the request by the
411 system.
412 Source Code
414 The code is open to the world, and available for you to hack on. Please
415 feel free to browse it and play with it, or whatever. If you want to
416 contribute patches, please send me a diff or prod me to pull from your
417 repository :)
418 <https://github.com/shlomif/text-format>
420 git clone https://github.com/shlomif/perl-Module-Format
422perl v5.30.1 2020-01-30 Text::Format(3)