/ 
Text-Format0.32
River stage two • 8 direct dependents • 12 total dependents
/ Text::Format

NAME

Text::Format - Various subroutines to manipulate text.

SYNOPSIS

use Text::Format;

$text = Text::Format->new({
    columns        => 72,
    tabstop        =>  8,
    firstIndent    => "\t",
    bodyIndent     => '',
    rightFill      => 0,
    rightAlign     => 0,
    expandTabs     => 0,
    extraSpace     => 0,
    abbrevs        => {}, # reference to a hash
    text           => [], # reference to a list
    hangingIndent  => 0,
    hangingText    => [], # reference to a list
}); # these are the default settings

$text = Text::Format->new();
print $text->wrap(@text);
print $text->fill(@text);
print $text->center(@text);
print $text->wrap([<FILEHANDLE>]);
print $text->fill([<FILEHANDLE>]);
print $text->expand(@text);
print $text->unexpand(@text);

$text = Text::Format->new
    ({tabstop => 4,bodyIndent => "\t",text => \@text});
print $text->wrap();
print $text->fill();
print $text->center();
print $text->expand();
print $text->unexpand();

print Text::Format->new->wrap(@text);
%abbr = (foo => 1, bar => 1);
$text->abbrevs(\%abbr);
$text->abbrevs();
$text->abbrevs(qw/foo bar/);
$text->text(\@text);

$text->columns(132);
$text->tabstop(4);
$text->expandTabs(1);
$text->extraSpace(1);
$text->firstIndent("\t\t");
$text->bodyIndent("\t"
$text->config({tabstop => 4,firstIndent => ''});
$text->rightFill(0);
$text->rightAlign(0);

DESCRIPTION

The wrap routine will wrap under all circumstances even if the width isn't enough to contain the longest words. Text::Wrap will die under these circumstances which isn't quite desirable in my opinion. 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.

wrap @ARRAY || \@ARRAY || [<FILEHANDLE>] || NOTHING

Allows to do basic formatting of text into paragraphs, with indent for first line and following lines separately. Can specify tab size and columns, width of total text, right fill with spaces and right align. Strips all leading and trailing whitespace before proceding. If right alignment is set or tab expansion is set or hanging indents is set then all tabs are expanded to spaces.

fill @ARRAY || \@ARRAY || [<FILEHANDLE>] || NOTHING

Considers each element of text as a paragraph and if the indents are the same for first line and the rest of the lines then they are separated by a single empty line otherwise they follow one under the other. If hanging indent is set then a single ampty line will separate each paragraph as well.

center @ARRAY || NOTHING

Centers a list of strings. empty lines appear as, you guessed it, empty lines. Center strips all leading and trailing whitespace before proceding.

expand @ARRAY || NOTHING

Expand tabs in the list of text to tabstop number of spaces.

unexpand @ARRAY || NOTHING

Tabstop number of spaces are turned into tabs.

columns NUMBER || NOTHING

Set width of text or retrieve width.

tabstop NUMBER || NOTHING

Set tabstop size or retrieve tabstop size.

rightFill 0 || 1 || NOTHING

Set right fill to true or retrieve its value.

rightAlign 0 || 1 || NOTHING

Set right align to true or retrieve its value.

expandTabs 0 || 1 || NOTHING

Expand leading tabs to spaces, or in case of center, expand internal tabs. Returns current setting of attribute.

abbrevs \%HASH || @ARRAY || NOTHING

Add to the current abbreviations, takes a reference to your array, if called a second time the original reference is removed. Returns the current INTERNAL abbreviations

extraSpace 0 || 1 || NOTHING

Add extra space after end of sentence, normally wrap would add 1 space after end of sentence, if this is set to 1 then 2 spaces are used.

hangingText \@ARRAY || NOTHING

The text that will be displayed in front of each paragraph, if you call wrap than only the first element is used, if you call fill then fill cycles through all of them. If you have more paragraphs than elements in your array than the first one will get reused. Pass a reference to your array.

hangingIndent 0 || 1 || NOTHING

Use hanging indents in front of a paragraph, returns current value of attribute.

config \%HASH

Allows the configuration of all object attributes at once.

text \@ARRAY || NOTHING

Pass in a reference to your text that you want the routines to manipulate. Returns the text held in the object.

EXAMPLE

use Text::Format;

$text = new Text::Format;
$text->rightFill(1);
$text->columns(65);
$text->tabstop(4);
print $text->wrap("a line to format to an indented regular
        paragraph using 65 character wide display and a
        tabstop of 4");
$text->expandTabs(1); # tab will be expanded to spaces
print $text->fill("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});

BUGS

Line length can exceed columns specified if columns is set to a small number and long words plus leading whitespace exceed column length specified. Actually I see this as a feature since it can be used to make up a nice wordlist.

AUTHOR

Gabor Egressy <gabor@vmunix.com>, some suggestions for improvement by Tom Phoenix, Andreas Koenig, Brad Appleton, and Byron Brummer

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.

TODO

Add the following features

1.  support for non-breaking whitespace
    - use hash to store the regex on which not to break eg.
      %hash = ('Mrs?\.' => '^\S+$');