1Text::Format(3)       User Contributed Perl Documentation      Text::Format(3)
2
3
4

NAME

6       Text::Format - Various subroutines to format text.
7

VERSION

9       version 0.61
10

SYNOPSIS

12           use Text::Format;
13
14           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
35           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
42           $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

DESCRIPTION

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
62       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
68       General setup should be explained with the below graph.
69
70                                  columns
71       <------------------------------------------------------------>
72       <----------><------><---------------------------><----------->
73        leftMargin  indent  text is formatted into here  rightMargin
74
75       indent is firstIndent or bodyIndent depending on where we are in the
76       paragraph.
77
78       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
89       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
98       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
105       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
111       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
117       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
121       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
126       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
130       tabstop NUMBER || NOTHING
131           Set tabstop size or retrieve tabstop size, only used by expand,
132           unexpand and center.
133
134       firstIndent NUMBER || NOTHING
135           Set or get indent for the first line of paragraph.  This is the
136           number of spaces to indent.
137
138       bodyIndent NUMBER || NOTHING
139           Set or get indent for the body of paragraph.  This is the number of
140           spaces to indent.
141
142       leftMargin NUMBER || NOTHING
143           Set or get width of left margin.  This is the number of spaces used
144           for the margin.
145
146       rightMargin NUMBER || NOTHING
147           Set or get width of right margin.  This is the number of spaces
148           used for the margin.
149
150       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
155       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
160       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
167       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
172       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
176       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
184       noBreak 0 || 1 || NOTHING
185           Set whether you want to use the non-breaking space feature (see
186           noBreakRegex below).
187
188       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
194               {'^Mrs?\.$' => '^\S+$','^\S+$' => '^(?:S|J)r\.$'}
195
196           don't break names such as Mr. Jones, Mrs. Jones, Jones Jr.
197
198           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
206           Note: this feature requires noBreak to be set to true.
207
208       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
215       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

VERSION

222       version 0.61
223

EXAMPLE

225           use Text::Format;
226
227           my $text = Text::Format->new;
228
229           $text->rightFill(1);
230           $text->columns(65);
231           $text->tabstop(4);
232
233           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
240           $text->config({columns => 132, tabstop => 4});
241
242           $text = Text::Format->new();
243
244           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
253           $text = Text::Format->new
254               ({tabstop => 4,bodyIndent => 4,text => \@text});
255
256           print $text->format();
257           print $text->paragraphs();
258           print $text->center();
259           print $text->expand();
260           print $text->unexpand();
261
262           print Text::Format->new({columns => 95})->format(@text);
263

BUGS

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

LICENSE

271       Copyright (c) 1998 Gabor Egressy.  All rights reserved.
272
273       This program is free software; you can redistribute and/or modify it
274       under the same terms as Perl itself.
275

AUTHOR

277       Gabor Egressy gabor@vmunix.com
278
279       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
283       Adopted and modified by Shlomi Fish, <http://www.shlomifish.org/> - all
284       rights disclaimed.
285

ACKNOWLEDGMENTS

287       Tom Phoenix
288
289       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
293       Brad Appleton
294
295       Suggestion and explanation of hanging indents, suggestion for non-
296       breaking whitespace, general suggestions with regard to interface
297       design.
298
299       Byron Brummer
300
301       Suggestion for better interface design and object design, code for
302       better implementation of getting abbreviations.
303
304       H. Merijn Brand
305
306       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
310       Anne Wainwright
311
312       Inspired a documentation clarification about noBreak required by
313       noBreakRegex , thanks to a report with a problem.
314

TODO

AUTHOR

317       Shlomi Fish <shlomif@cpan.org>
318
320       This software is copyright (c) 2018 by Gabor Egressy.
321
322       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

BUGS

326       Please report any bugs or feature requests on the bugtracker website
327       <https://github.com/shlomif/text-format/issues>
328
329       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

SUPPORT

333   Perldoc
334       You can find documentation for this module with the perldoc command.
335
336         perldoc Text::Format
337
338   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
343       ·   MetaCPAN
344
345           A modern, open-source CPAN search engine, useful to view POD in
346           HTML format.
347
348           <https://metacpan.org/release/Text-Format>
349
350       ·   Search CPAN
351
352           The default CPAN search engine, useful to view POD in HTML format.
353
354           <http://search.cpan.org/dist/Text-Format>
355
356       ·   RT: CPAN's Bug Tracker
357
358           The RT ( Request Tracker ) website is the default bug/issue
359           tracking system for CPAN.
360
361           <https://rt.cpan.org/Public/Dist/Display.html?Name=Text-Format>
362
363       ·   AnnoCPAN
364
365           The AnnoCPAN is a website that allows community annotations of Perl
366           module documentation.
367
368           <http://annocpan.org/dist/Text-Format>
369
370       ·   CPAN Ratings
371
372           The CPAN Ratings is a website that allows community ratings and
373           reviews of Perl modules.
374
375           <http://cpanratings.perl.org/d/Text-Format>
376
377       ·   CPANTS
378
379           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
380           of a distribution.
381
382           <http://cpants.cpanauthors.org/dist/Text-Format>
383
384       ·   CPAN Testers
385
386           The CPAN Testers is a network of smoke testers who run automated
387           tests on uploaded CPAN distributions.
388
389           <http://www.cpantesters.org/distro/T/Text-Format>
390
391       ·   CPAN Testers Matrix
392
393           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
397           <http://matrix.cpantesters.org/?dist=Text-Format>
398
399       ·   CPAN Testers Dependencies
400
401           The CPAN Testers Dependencies is a website that shows a chart of
402           the test results of all dependencies for a distribution.
403
404           <http://deps.cpantesters.org/?module=Text::Format>
405
406   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
413   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
419       <https://github.com/shlomif/text-format>
420
421         git clone https://github.com/shlomif/perl-Module-Format
422
423
424
425perl v5.30.1                      2020-01-30                   Text::Format(3)
Impressum