1Text::Format(3) User Contributed Perl Documentation Text::Format(3)
2
6 Text::Format - Various subroutines to format text.
7
9 use Text::Format;
10 $text = Text::Format->new (
12 {
13 text => [], # all
14 columns => 72, # format, paragraphs, center
15 leftMargin => 0, # format, paragraphs, center
16 rightMargin => 0, # format, paragraphs, center
17 firstIndent => 4, # format, paragraphs
18 bodyIndent => 0, # format, paragraphs
19 rightFill => 0, # format, paragraphs
20 rightAlign => 0, # format, paragraphs
21 justify => 0, # format, paragraphs
22 extraSpace => 0, # format, paragraphs
23 abbrevs => {}, # format, paragraphs
24 hangingIndent => 0, # format, paragraphs
25 hangingText => [], # format, paragraphs
26 noBreak => 0, # format, paragraphs
27 noBreakRegex => {}, # format, paragraphs
28 tabstop => 8, # expand, unexpand, center
29 }
30 ); # these are the default values
31 %abbr = (foo => 1, bar => 1);
33 $text->abbrevs(\%abbr);
34 $text->abbrevs();
35 $text->abbrevs({foo => 1,bar => 1});
36 $text->abbrevs(qw/foo bar/);
37 $text->text(\@text);
38 $text->columns(132);
40 $text->tabstop(4);
41 $text->extraSpace(1);
42 $text->firstIndent(8);
43 $text->bodyIndent(4);
44 $text->config({tabstop => 4,firstIndent => 0});
45 $text->rightFill(0);
46 $text->rightAlign(0);
47
49 The format routine will format under all circumstances even if the
50 width isn't enough to contain the longest words. Text::Wrap will die
51 under these circumstances, although I am told this is fixed. If
52 columns is set to a small number and words are longer than that and the
53 leading 'whitespace' than there will be a single word on each line.
54 This will let you make a simple word list which could be indented or
55 right aligned. There is a chance for croaking if you try to subvert
56 the module. If you don't pass in text then the internal text is worked
57 on, though not modfied. Text::Format is meant for more powerful text
58 formatting than Text::Wrap allows. I also have a module called
59 Text::NWrap that is meant as a direct replacement for Text::Wrap.
60 Text::NWrap requires Text::Format since it uses Text::Format->format to
61 do the actual wrapping but gives you the interface of Text::Wrap.
62 General setup should be explained with the below graph.
64 columns
66 <------------------------------------------------------------>
67 <----------><------><---------------------------><----------->
68 leftMargin indent text is formatted into here rightMargin
69 indent is firstIndent or bodyIndent depending on where we are in the
71 paragraph.
72 format @ARRAY || \@ARRAY || [<FILEHANDLE>] || NOTHING
74 Allows to do some advanced formatting of text into a paragraph,
75 with indent for first line and body set separately. Can specify
76 total width of text, right fill with spaces or right align or
77 justify (align to both margins), right margin and left margin, non-
78 breaking space, two spaces at end of sentence, hanging indents
79 (tagged paragraphs). Strips all leading and trailing whitespace
80 before proceeding. Text is first split into words and then
81 reassembled. If no text is passed in then the internal text in the
82 object is formatted.
83 paragraphs @ARRAY || \@ARRAY || [<FILEHANDLE>] || NOTHING
85 Considers each element of text as a paragraph and if the indents
86 are the same for first line and the body then the paragraphs are
87 separated by a single empty line otherwise they follow one under
88 the other. If hanging indent is set then a single empty line will
89 separate each paragraph as well. Calls format to do the actual
90 formatting. If no text is passed in then the internal text in the
91 object is formatted, though not changed.
92 center @ARRAY || NOTHING
94 Centers a list of strings in @ARRAY or internal text. Empty lines
95 appear as, you guessed it, empty lines. Center strips all leading
96 and trailing whitespace before proceeding. Left margin and right
97 margin can be set. If no text is passed in then the internal text
98 in the object is formatted.
99 expand @ARRAY || NOTHING
101 Expand tabs in the list of text to tabstop number of spaces in
102 @ARRAY or internal text. Doesn't modify the internal text just
103 passes back the modified text. If no text is passed in then the
104 internal text in the object is formatted.
105 unexpand @ARRAY || NOTHING
107 Tabstop number of spaces are turned into tabs in @ARRAY or internal
108 text. Doesn't modify the internal text just passes back the
109 modified text. If no text is passed in then the internal text in
110 the object is formatted.
111 new \%HASH || NOTHING
113 Instantiates the object. If you pass a reference to a hash, or an
114 anonymous hash then it's used in setting attributes.
115 config \%HASH
117 Allows the configuration of all object attributes at once. Returns
118 the object prior to configuration. You can use it to make a clone
119 of your object before you change attributes.
120 columns NUMBER || NOTHING
122 Set width of text or retrieve width. This is total width and
123 includes indentation and the right and left margins.
124 tabstop NUMBER || NOTHING
126 Set tabstop size or retrieve tabstop size, only used by expand,
127 unexpand and center.
128 firstIndent NUMBER || NOTHING
130 Set or get indent for the first line of paragraph. This is the
131 number of spaces to indent.
132 bodyIndent NUMBER || NOTHING
134 Set or get indent for the body of paragraph. This is the number of
135 spaces to indent.
136 leftMargin NUMBER || NOTHING
138 Set or get width of left margin. This is the number of spaces used
139 for the margin.
140 rightMargin NUMBER || NOTHING
142 Set or get width of right margin. This is the number of spaces
143 used for the margin.
144 rightFill 0 || 1 || NOTHING
146 Set right fill or retrieve its value. The filling is done with
147 spaces. Keep in mind that if rightAlign is also set then both
148 rightFill and rightAlign are ignored.
149 rightAlign 0 || 1 || NOTHING
151 Set right align or retrieve its value. Text is aligned with the
152 right side of the margin. Keep in mind that if rightFill is also
153 set then both rightFill and rightAlign are ignored.
154 justify 0 || 1 || NOTHING
156 Set justify or retrieve its value. Text is aligned with both
157 margins, adding extra spaces as necessary to align text with left
158 and right margins. Keep in mind that if either of rightAlign or
159 rightFill are set then justify is ignored, even if both are set in
160 which case they are all ignored.
161 text \@ARRAY || NOTHING
163 Pass in a reference to your text, or an anonymous array of text
164 that you want the routines to manipulate. Returns the text held in
165 the object.
166 hangingIndent 0 || 1 || NOTHING
168 Use hanging indents in front of a paragraph, returns current value
169 of attribute. This is also called a tagged paragraph.
170 hangingText \@ARRAY || NOTHING
172 The text that will be displayed in front of each paragraph, if you
173 call format then only the first element is used, if you call
174 paragraphs then paragraphs cycles through all of them. If you have
175 more paragraphs than elements in your array than the remainder of
176 the paragraphs will not have a hanging indented text. Pass a
177 reference to your array. This is also called a tagged paragraph.
178 noBreak 0 || 1 || NOTHING
180 Set whether you want to use the non-breaking space feature.
181 noBreakRegex \%HASH || NOTHING
183 Pass in a reference to your hash that would hold the regexes on
184 which not to break. Returns the hash. eg.
185 {'^Mrs?\.$' => '^\S+$','^\S+$' => '^(?:S|J)r\.$'}
187 don't break names such as Mr. Jones, Mrs. Jones, Jones Jr.
189 The breaking algorithm is simple. If there should not be a break
191 at the current end of sentence, then a backtrack is done till there
192 are two words on which breaking is allowed. If no two such words
193 are found then the end of sentence is broken anyhow. If there is a
194 single word on current line then no backtrack is done and the word
195 is stuck on the end. This is so you can make a list of names for
196 example.
197 extraSpace 0 || 1 || NOTHING
199 Add extra space after end of sentence, normally format would add 1
200 space after end of sentence, if this is set to 1 then 2 spaces are
201 used. Abbreviations are not followed by two spaces. There are a
202 few internal abbreviations and you can add your own to the object
203 with abbrevs
204 abbrevs \%HASH || @ARRAY || NOTHING
206 Add to the current abbreviations, takes a reference to your hash or
207 an array of abbreviations, if called a second time the original
208 reference is removed and replaced by the new one. Returns the
209 current INTERNAL abbreviations.
210
212 use Text::Format;
213 $text = new Text::Format;
215 $text->rightFill(1);
216 $text->columns(65);
217 $text->tabstop(4);
218 print $text->format("a line to format to an indented regular
219 paragraph using 65 character wide display");
220 print $text->paragraphs("paragraph one","paragraph two");
221 print $text->center("hello world","nifty line 2");
222 print $text->expand("\t\thello world\n","hmm,\twell\n");
223 print $text->unexpand(" hello world\n"," hmm");
224 $text->config({columns => 132, tabstop => 4});
225 $text = Text::Format->new();
227 print $text->format(@text);
228 print $text->paragraphs(@text);
229 print $text->center(@text);
230 print $text->format([<FILEHANDLE>]);
231 print $text->format([$fh->getlines()]);
232 print $text->paragraphs([<FILEHANDLE>]);
233 print $text->expand(@text);
234 print $text->unexpand(@text);
235 $text = Text::Format->new
237 ({tabstop => 4,bodyIndent => 4,text => \@text});
238 print $text->format();
239 print $text->paragraphs();
240 print $text->center();
241 print $text->expand();
242 print $text->unexpand();
243 print Text::Format->new({columns => 95})->format(@text);
245
247 Line length can exceed columns specified if columns is set to a small
248 number and long words plus leading whitespace exceed column length
249 specified. Actually I see this as a feature since it can be used to
250 make up a nice word list.
251
253 Gabor Egressy gabor@vmunix.com
254 Copyright (c) 1998 Gabor Egressy. All rights reserved. All wrongs
256 reversed. This program is free software; you can redistribute and/or
257 modify it under the same terms as Perl itself.
258
260 Tom Phoenix found bug with code for two spaces at end of sentence and
261 provided code fragment for a better solution, some preliminary
262 suggestions on design
263 Brad Appleton suggesting and explanation of hanging indents, suggestion
265 for non-breaking whitespace, general suggestions with regard to
266 interface design
267 Byron Brummer suggestion for better interface design and object design,
269 code for better implementation of getting abbreviations
270 H. Merijn Brand suggestion for justify feature and original code for
272 doing the justification. I changed the code to take into account the
273 extra space at end of sentence feature.
274
276perl v5.12.0 1998-03-29 Text::Format(3)