MAN page from Fedora 28 perl-Text-Format-0.60-5.fc28.noarch.rpm


Section: User Contributed Perl Documentation (3)
Updated: 2016-08-22


Text::Format - Various subroutines to format text. 


    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);


The format routine will format under all circumstances even if thewidth isn't enough to contain the longest words. Text::Wrap will dieunder these circumstances, although I am told this is fixed. If columnsis 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 willlet you make a simple word list which could be indented or rightaligned. There is a chance for croaking if you try to subvert themodule. 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 whatText::Wrap allows. I also have a module called Text::NWrap thatis meant as a direct replacement for Text::Wrap. Text::NWraprequires Text::Format since it uses Text::Format->format to do theactual 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 theparagraph.

Allows one to do some advanced formatting of text into a paragraph, withindent for first line and body set separately. Can specify total widthof text, right fill with spaces or right align or justify (align to bothmargins), right margin and left margin, non-breaking space, two spacesat end of sentence, hanging indents (tagged paragraphs). Strips allleading and trailing whitespace before proceeding. Text is first splitinto words and then reassembled. If no text is passed in then theinternal text in the object is formatted.
paragraphs @ARRAY || \@ARRAY || [<FILEHANDLE>] || NOTHING
Considers each element of text as a paragraph and if the indents are thesame for first line and the body then the paragraphs are separated by asingle empty line otherwise they follow one under the other. If hangingindent is set then a single empty line will separate each paragraph aswell. Calls format to do the actual formatting. If no text ispassed in then the internal text in the object is formatted, though notchanged.
center @ARRAY || NOTHING
Centers a list of strings in @ARRAY or internal text. Empty linesappear as, you guessed it, empty lines. Center strips all leading andtrailing whitespace before proceeding. Left margin and right margin canbe set. If no text is passed in then the internal text in the object isformatted.
expand @ARRAY || NOTHING
Expand tabs in the list of text to tabstop number of spaces in @ARRAY orinternal text. Doesn't modify the internal text just passes back themodified text. If no text is passed in then the internal text in theobject is formatted.
unexpand @ARRAY || NOTHING
Tabstop number of spaces are turned into tabs in @ARRAY or internaltext. Doesn't modify the internal text just passes back the modifiedtext. If no text is passed in then the internal text in the object isformatted.
Instantiates the object. If you pass a reference to a hash, or ananonymous hash then it is used in setting attributes.
config \%HASH
Allows the configuration of all object attributes at once. Returns theobject prior to configuration. You can use it to make a clone of yourobject before you change attributes.
Set width of text or retrieve width. This is total width and includesindentation and the right and left margins.
Set tabstop size or retrieve tabstop size, only used by expand, unexpandand center.
firstIndent NUMBER || NOTHING
Set or get indent for the first line of paragraph. This is the numberof spaces to indent.
bodyIndent NUMBER || NOTHING
Set or get indent for the body of paragraph. This is the number ofspaces to indent.
leftMargin NUMBER || NOTHING
Set or get width of left margin. This is the number of spaces used forthe margin.
rightMargin NUMBER || NOTHING
Set or get width of right margin. This is the number of spaces used forthe 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 rightFilland rightAlign are ignored.
rightAlign 0 || 1 || NOTHING
Set right align or retrieve its value. Text is aligned with the rightside of the margin. Keep in mind that if rightFill is also set thenboth 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 rightmargins. Keep in mind that if either of rightAlign or rightFillare set then justify is ignored, even if both are set in which casethey are all ignored.
Pass in a reference to your text, or an anonymous array of text that youwant 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 ofattribute. This is also called a tagged paragraph.
hangingText \@ARRAY || NOTHING
The text that will be displayed in front of each paragraph, if you callformat then only the first element is used, if you call paragraphsthen paragraphs cycles through all of them. If you have moreparagraphs than elements in your array than the remainder of theparagraphs will not have a hanging indented text. Pass a reference toyour array. This is also called a tagged paragraph.
noBreak 0 || 1 || NOTHING
Set whether you want to use the non-breaking space feature (seenoBreakRegex below).
noBreakRegex \%HASH || NOTHING
Pass in a reference to a hash that would hold the regexes on which notto break. In order for this to happen, it requires noBreak to be setto true - see above. Without any arguments, itreturns the hash. E.g:

    {'^Mrs?\.$' => '^\S+$','^\S+$' => '^(?:S|J)r\.$'}

don't break names such asMr. Jones, Mrs. Jones, Jones Jr.

The breaking algorithm is simple. If there should not be a break at thecurrent end of sentence, then a backtrack is done till there are twowords on which breaking is allowed. If no two such words are found thenthe end of sentence is broken anyhow. If there is a single word oncurrent 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 1space 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 internalabbreviations 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 anarray of abbreviations, if called a second time the original referenceis removed and replaced by the new one. Returns the current INTERNALabbreviations.


    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);


Line length can exceed the number of specified columnsif columns is set to a small number and long words plus leading whitespaceexceed the specified column length. Actually I see this as a feature since itcan be used to make up a nice word list. 


Copyright (c) 1998 Gabor Egressy. All rights reserved.

This program is free software; you can redistribute and/ormodify it under the same terms as Perl itself. 


Gabor Egressy

Copyright (c) 1998 Gabor Egressy. All rights reserved. All wrongsreversed. This program is free software; you can redistribute and/ormodify it under the same terms as Perl itself.

Adopted and modified by Shlomi Fish, <> - allrights disclaimed. 


Tom Phoenix

Found a bug with code for two spaces at the end of the sentence and provideda code fragment for a better solution. Also some preliminary suggestions onthe design.

Brad Appleton

Suggestion and explanation of hanging indents, suggestion fornon-breaking whitespace, general suggestions with regard to interfacedesign.

Byron Brummer

Suggestion for better interface design and object design, code forbetter implementation of getting abbreviations.

H. Merijn Brand

Suggestion for a justify feature and original code for doing thejustification. I changed the code to take into account the extra spaceat end of sentence feature.

Anne Wainwright

Inspired a documentation clarification about noBreak required bynoBreakRegex , thanks to a report with a problem. 





This document was created byman2html,using the manual pages.