Subject: announce Text::Format was Manip
From: [email-masked] (Gabor)
Date: 22 Jan 1998 23:24:43 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.modules

I'd like to announce the release to CPAN my Perl module Text::Format.
It's a basic formatting module(object oriented).  The main routines
are wrap(), fill(), and center().
It's still in beta, so pelase report bugs. :-)
Here is the pod2text output

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,
            leftMargin     => 0,
            rightMargin    => 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 values

        $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. General setup should be explained with the below graph.

                                  Columns
    <------------------------------------------------------------>
    <---------><----->                                <---------->
    Left Margin Indent                                Right Margin

    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, right margin and left margin. 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 empty line will
        separate each paragraph as well. Calls wrap to do the actual
        formatting.

    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 proceding. Left margin and right
        margin can be set.

    expand @ARRAY || NOTHING
        Expand tabs in the list of text to tabstop number of spaces in
        @ARRAY or internal text.

    unexpand @ARRAY || NOTHING
        Tabstop number of spaces are turned into tabs in @ARRAY or internal
        text.

    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.

    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.

    leftMargin NUMBER || NOTHING
        Set or get width of left margin.

    rightMargin NUMBER || NOTHING
        Set or get width of right margin.

    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 <[email-masked]>, some suggestions for improvement by
    Tom Phoenix, Brad Appleton, Byron Brummer, and Andreas Koenig

    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+$');

gabor.
--
    Chip Salzenberg sent me a complete patch to add System V IPC (msg,
    sem and shm calls), so I added them.  If that bothers you, you can
    always undefine them in config.sh.  :-)
        -- Larry Wall in <[email-masked]>