Provided by: libtext-format-perl_0.60-1_all 
NAME
Text::Format - Various subroutines to format text.
SYNOPSIS
use Text::Format;
my $text = Text::Format->new (
{
text => [], # all
columns => 72, # format, paragraphs, center
leftMargin => 0, # format, paragraphs, center
rightMargin => 0, # format, paragraphs, center
firstIndent => 4, # format, paragraphs
bodyIndent => 0, # format, paragraphs
rightFill => 0, # format, paragraphs
rightAlign => 0, # format, paragraphs
justify => 0, # format, paragraphs
extraSpace => 0, # format, paragraphs
abbrevs => {}, # format, paragraphs
hangingIndent => 0, # format, paragraphs
hangingText => [], # format, paragraphs
noBreak => 0, # format, paragraphs
noBreakRegex => {}, # format, paragraphs
tabstop => 8, # expand, unexpand, center
}
); # these are the default values
my %abbr = (foo => 1, bar => 1);
$text->abbrevs(\%abbr);
$text->abbrevs();
$text->abbrevs({foo => 1,bar => 1});
$text->abbrevs(qw/foo bar/);
$text->text(\@text);
$text->columns(132);
$text->tabstop(4);
$text->extraSpace(1);
$text->firstIndent(8);
$text->bodyIndent(4);
$text->config({tabstop => 4,firstIndent => 0});
$text->rightFill(0);
$text->rightAlign(0);
DESCRIPTION
The format routine will format under all circumstances even if the width isn't enough to contain the
longest words. Text::Wrap will die under these circumstances, although I am told this is fixed. If
columns is set to a small number and words are longer than that and the leading 'whitespace' than there
will be a single word on each line. This will let you make a simple word list which could be indented or
right aligned. There is a chance for croaking if you try to subvert the module. If you don't pass in
text then the internal text is worked on, though not modified.
Text::Format is meant for more powerful text formatting than what Text::Wrap allows. I also have a
module called Text::NWrap that is meant as a direct replacement for Text::Wrap. Text::NWrap requires
Text::Format since it uses Text::Format->format to do the actual wrapping but gives you the interface of
Text::Wrap.
General setup should be explained with the below graph.
columns
<------------------------------------------------------------>
<----------><------><---------------------------><----------->
leftMargin indent text is formatted into here rightMargin
indent is firstIndent or bodyIndent depending on where we are in the paragraph.
format @ARRAY || \@ARRAY || [<FILEHANDLE>] || NOTHING
Allows one to do some advanced formatting of text into a paragraph, with indent for first line and
body set separately. Can specify total width of text, right fill with spaces or right align or
justify (align to both margins), right margin and left margin, non-breaking space, two spaces at end
of sentence, hanging indents (tagged paragraphs). Strips all leading and trailing whitespace before
proceeding. Text is first split into words and then reassembled. If no text is passed in then the
internal text in the object is formatted.
paragraphs @ARRAY || \@ARRAY || [<FILEHANDLE>] || NOTHING
Considers each element of text as a paragraph and if the indents are the same for first line and the
body then the paragraphs are separated by a single empty line otherwise they follow one under the
other. If hanging indent is set then a single empty line will separate each paragraph as well.
Calls format to do the actual formatting. If no text is passed in then the internal text in the
object is formatted, though not changed.
center @ARRAY || NOTHING
Centers a list of strings in @ARRAY or internal text. Empty lines appear as, you guessed it, empty
lines. Center strips all leading and trailing whitespace before proceeding. Left margin and right
margin can be set. If no text is passed in then the internal text in the object is formatted.
expand @ARRAY || NOTHING
Expand tabs in the list of text to tabstop number of spaces in @ARRAY or internal text. Doesn't
modify the internal text just passes back the modified text. If no text is passed in then the
internal text in the object is formatted.
unexpand @ARRAY || NOTHING
Tabstop number of spaces are turned into tabs in @ARRAY or internal text. Doesn't modify the
internal text just passes back the modified text. If no text is passed in then the internal text in
the object is formatted.
new \%HASH || NOTHING
Instantiates the object. If you pass a reference to a hash, or an anonymous hash then it is used in
setting attributes.
config \%HASH
Allows the configuration of all object attributes at once. Returns the object prior to
configuration. You can use it to make a clone of your object before you change attributes.
columns NUMBER || NOTHING
Set width of text or retrieve width. This is total width and includes indentation and the right and
left margins.
tabstop NUMBER || NOTHING
Set tabstop size or retrieve tabstop size, only used by expand, unexpand and center.
firstIndent NUMBER || NOTHING
Set or get indent for the first line of paragraph. This is the number of spaces to indent.
bodyIndent NUMBER || NOTHING
Set or get indent for the body of paragraph. This is the number of spaces to indent.
leftMargin NUMBER || NOTHING
Set or get width of left margin. This is the number of spaces used for the margin.
rightMargin NUMBER || NOTHING
Set or get width of right margin. This is the number of spaces used for the margin.
rightFill 0 || 1 || NOTHING
Set right fill or retrieve its value. The filling is done with spaces. Keep in mind that if
rightAlign is also set then both rightFill and rightAlign are ignored.
rightAlign 0 || 1 || NOTHING
Set right align or retrieve its value. Text is aligned with the right side of the margin. Keep in
mind that if rightFill is also set then both rightFill and rightAlign are ignored.
justify 0 || 1 || NOTHING
Set justify or retrieve its value. Text is aligned with both margins, adding extra spaces as
necessary to align text with left and right margins. Keep in mind that if either of rightAlign or
rightFill are set then justify is ignored, even if both are set in which case they are all ignored.
text \@ARRAY || NOTHING
Pass in a reference to your text, or an anonymous array of text that you want the routines to
manipulate. Returns the text held in the object.
hangingIndent 0 || 1 || NOTHING
Use hanging indents in front of a paragraph, returns current value of attribute. This is also called
a tagged paragraph.
hangingText \@ARRAY || NOTHING
The text that will be displayed in front of each paragraph, if you call format then only the first
element is used, if you call paragraphs then paragraphs cycles through all of them. If you have more
paragraphs than elements in your array than the remainder of the paragraphs will not have a hanging
indented text. Pass a reference to your array. This is also called a tagged paragraph.
noBreak 0 || 1 || NOTHING
Set whether you want to use the non-breaking space feature (see noBreakRegex below).
noBreakRegex \%HASH || NOTHING
Pass in a reference to a hash that would hold the regexes on which not to break. In order for this to
happen, it requires noBreak to be set to true - see above. Without any arguments, it returns the
hash. E.g:
{'^Mrs?\.$' => '^\S+$','^\S+$' => '^(?:S|J)r\.$'}
don't break names such as Mr. Jones, Mrs. Jones, Jones Jr.
The breaking algorithm is simple. If there should not be a break at the current end of sentence,
then a backtrack is done till there are two words on which breaking is allowed. If no two such words
are found then the end of sentence is broken anyhow. If there is a single word on current line then
no backtrack is done and the word is stuck on the end. This is so you can make a list of names for
example.
Note: this feature requires noBreak to be set to true.
extraSpace 0 || 1 || NOTHING
Add extra space after end of sentence, normally format would add 1 space after end of sentence, if
this is set to 1 then 2 spaces are used. Abbreviations are not followed by two spaces. There are a
few internal abbreviations and you can add your own to the object with abbrevs
abbrevs \%HASH || @ARRAY || NOTHING
Add to the current abbreviations, takes a reference to your hash or an array of abbreviations, if
called a second time the original reference is removed and replaced by the new one. Returns the
current INTERNAL abbreviations.
EXAMPLE
use Text::Format;
my $text = Text::Format->new;
$text->rightFill(1);
$text->columns(65);
$text->tabstop(4);
print $text->format("a line to format to an indented regular
paragraph using 65 character wide display");
print $text->paragraphs("paragraph one","paragraph two");
print $text->center("hello world","nifty line 2");
print $text->expand("\t\thello world\n","hmm,\twell\n");
print $text->unexpand(" hello world\n"," hmm");
$text->config({columns => 132, tabstop => 4});
$text = Text::Format->new();
print $text->format(@text);
print $text->paragraphs(@text);
print $text->center(@text);
print $text->format([<FILEHANDLE>]);
print $text->format([$fh->getlines()]);
print $text->paragraphs([<FILEHANDLE>]);
print $text->expand(@text);
print $text->unexpand(@text);
$text = Text::Format->new
({tabstop => 4,bodyIndent => 4,text => \@text});
print $text->format();
print $text->paragraphs();
print $text->center();
print $text->expand();
print $text->unexpand();
print Text::Format->new({columns => 95})->format(@text);
BUGS
Line length can exceed the number of specified columns if columns is set to a small number and long words
plus leading whitespace exceed the specified column length. Actually I see this as a feature since it
can be used to make up a nice word list.
LICENSE
Copyright (c) 1998 Gabor Egressy. All rights reserved.
This program is free software; you can redistribute and/or modify it under the same terms as Perl itself.
AUTHOR
Gabor Egressy gabor@vmunix.com
Copyright (c) 1998 Gabor Egressy. All rights reserved. All wrongs reversed. This program is free
software; you can redistribute and/or modify it under the same terms as Perl itself.
Adopted and modified by Shlomi Fish, <http://www.shlomifish.org/> - all rights disclaimed.
ACKNOWLEDGMENTS
Tom Phoenix
Found a bug with code for two spaces at the end of the sentence and provided a code fragment for a better
solution. Also some preliminary suggestions on the design.
Brad Appleton
Suggestion and explanation of hanging indents, suggestion for non-breaking whitespace, general
suggestions with regard to interface design.
Byron Brummer
Suggestion for better interface design and object design, code for better implementation of getting
abbreviations.
H. Merijn Brand
Suggestion for a justify feature and original code for doing the justification. I changed the code to
take into account the extra space at end of sentence feature.
Anne Wainwright
Inspired a documentation clarification about noBreak required by noBreakRegex , thanks to a report with a
problem.